Add deprecated components migration howto

docs/reference/edot-collector/components.md

@@ -21,7 +21,7 @@ The {{edot}} (EDOT) Collector includes embedded Collector components from the [O
 The components included in the EDOT Collector are categorized into **[Core]** and **[Extended]** components. The following table describes the current components included in the EDOT Collector, their source, and support status.
 
 ::::{note}
-Components marked as "Deprecated" in the table are retained in EDOT Collector 9.x to maintain backwards compatibility during the official deprecation window. If you're running EDOT Collector 9.x with {{product.elastic-stack}} 8.18 or 8.19, continue using these deprecated components as specified in the configuration for your Stack version. For more details, refer to [Configuration compatibility with {{product.elastic-stack}} versions](/reference/edot-collector/config/default-config-standalone.md#configuration-compatibility-with-elastic-stack-versions).
+Components marked as "Deprecated" in the table are retained in EDOT Collector 9.x to maintain backwards compatibility during the official deprecation window. If you're running EDOT Collector 9.x with {{product.elastic-stack}} 8.18 or 8.19, continue using these deprecated components as specified in the configuration for your Stack version. For more details, refer to [Configuration compatibility with {{product.elastic-stack}} versions](/reference/edot-collector/config/default-config-standalone.md#configuration-compatibility-with-elastic-stack-versions). To migrate your configuration to the new components, refer to [Migrate components](/reference/edot-collector/components/migrate-components.md).
 ::::
 
 % The following table is automatically generated from the EDOT Collector source code.

docs/reference/edot-collector/components/migrate-components.md

@@ -0,0 +1,73 @@
+---
+navigation_title: Migrate components
+description: How to migrate from deprecated EDOT Collector components to their replacements.
+applies_to:
+  stack:
+  serverless:
+    observability:
+  product:
+    edot_collector: ga
+type: how-to
+products:
+  - id: cloud-serverless
+  - id: observability
+  - id: edot-collector
+---
+
+# Migrate from deprecated components
+
+This guide explains how to migrate from deprecated EDOT Collector components to their replacements.
+
+## Before you begin
+
+- Make sure your {{product.elastic-stack}} is running version {{version.stack.base}}. If you're using {{product.elastic-stack}} version 8.18 or 8.19, continue using the deprecated components as specified in the configuration for your Stack version.
+- Have access to a staging environment where you can test the new configuration before deploying to production.
+
+## Migrate your configuration
+
+Follow these steps to migrate your existing EDOT Collector configuration.
+
+:::::{stepper}
+
+::::{step} Download the latest default configuration
+Download the configuration sample that matches your use case from the [default configuration samples](/reference/edot-collector/config/default-config-standalone.md#agent-mode). For Gateway mode, refer to the [Gateway mode section](/reference/edot-collector/config/default-config-standalone.md#gateway-mode).
+
+The latest configurations for {{product.elastic-stack}} 9.x use the latest components instead of the deprecated ones.
+::::
+
+::::{step} Test the new configuration in staging
+Before deploying to production, validate the new configuration in a staging environment:
+
+1. Deploy the EDOT Collector with the new configuration to your staging environment.
+2. Verify that telemetry data (logs, metrics, and traces) is being collected and exported correctly.
+3. Check that the data appears correctly in the {{product.observability}} UIs in {{product.kibana}}.
+4. Test any custom pipelines or configurations you might have added on top of the default configuration.
+
+:::{tip}
+If you have custom configurations, compare your existing configuration with the new default to identify which sections need updating.
+:::
+::::
+
+::::{step} Apply the new configuration in production
+After validating the configuration in staging:
+
+1. Schedule a maintenance window for the update if necessary.
+2. Back up your existing EDOT Collector configuration.
+3. Deploy the new configuration to your production collectors.
+4. Monitor the {{product.observability}} UIs to ensure data continues to flow correctly.
+::::
+
+:::::
+
+::::{important}
+If you're upgrading EDOT Collector to 9.x but keeping your {{product.elastic-stack}} on 8.18 or 8.19:
+
+- Use the configuration examples for your Stack version (8.18 or 8.19), not the latest 9.x configuration.
+- Continue using deprecated components that are included in the configuration for your Stack version.
+- These deprecated components are retained in EDOT Collector 9.x specifically to maintain backwards compatibility during the official deprecation window.
+::::
+
+## Related pages
+
+- [Default configuration (standalone)](/reference/edot-collector/config/default-config-standalone.md)
+- [Components included in the EDOT Collector](/reference/edot-collector/components.md)

docs/reference/edot-collector/config/default-config-standalone.md

@@ -525,7 +525,7 @@ For {{ecloud}} and {{serverless-full}} deployments, mTLS is not required. TLS an
 
 ## Configuration compatibility with Elastic Stack versions
 
-While EDOT Collector 9.x is compatible with {{product.elastic-stack}} 8.18 and 8.19, users running these Stack versions should use the EDOT Collector configuration aligned with their Stack version to ensure the end-to-end experience works properly with {{product.kibana}} Observability UIs.
+While EDOT Collector 9.x is compatible with {{product.elastic-stack}} 8.18 and 8.19, users running these Stack versions should use the EDOT Collector configuration aligned with their Stack version to ensure the end-to-end experience works properly with {{product.kibana}} Observability UIs. Refer to [Migrate components](/reference/edot-collector/components/migrate-components.md) to migrate your configuration to the new components.
 
 ::::{important}
 If you're upgrading EDOT Collector to 9.x but keeping your {{product.elastic-stack}} on 8.18 or 8.19:

docs/reference/edot-collector/toc.yml

@@ -1,3 +1,3 @@
 toc:
   - file: index.md
   - file: download.md
@@ -11,6 +11,7 @@
       - file: config/tail-based-sampling.md
       - file: config/authentication-methods.md
       - file: config/configure-profiles-collection.md
+      - file: components/migrate-components.md
       - file: config/proxy.md
   - file: components.md
     children: