Add collector migration guide

Signed-off-by: ChrsMark <[email protected]>
open-telemetry · Nov 26, 2024 · 3f4eca3 · 3f4eca3
1 parent ade37df
commit 3f4eca3
Showing 1 changed file with 12 additions and 4 deletions.
diff --git a/docs/non-normative/k8s-migration.md b/docs/non-normative/k8s-migration.md
@@ -9,7 +9,7 @@ affected by them, existing K8s instrumentations published by
 OpenTelemetry are required to implement a migration plan that will assist users in
 transitioning to the stable K8s semantic conventions.
 
-Specifically, when existing K8s instrumentations published by OpenTelemetry are
+When existing K8s instrumentations published by OpenTelemetry are
 updated to the stable K8s semantic conventions, they:
 
 - SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` in
@@ -26,6 +26,15 @@ updated to the stable K8s semantic conventions, they:
 - May drop the environment variable in their next major version and emit only
   the stable k8s conventions.
 
+Specifically for the Opentelemetry Collector:
+
+The transition will happen through two different feature gates.
+One for enabling the new schema, and one for disabling the old schema. Then:
+
+- On alpha the old schema is enabled, while the new schema is disabled
+- On beta/stable the old schema is disabled, while the new is enabled
+- It is an error to disable both
+
 <!-- toc -->
 
 - [Summary of changes](#summary-of-changes)
@@ -37,14 +46,13 @@ updated to the stable K8s semantic conventions, they:
 
 This section summarizes the changes made to the K8s semantic conventions
 from a range of versions. Each starting version shows all the changes required
-to bring the conventions to
-[v1.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/k8s/README.md).
+to bring the conventions to stable (TODO: link to specific version once it exists).
 
 ### K8s network metrics
 
 The K8s network metrics implemented by the Collector and specifically the
 [kubeletstats](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.112.0/receiver/kubeletstatsreceiver/documentation.md)
-receiver were introduced as semantic conventions in [v1.TODO](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/k8s/README.md).
+receiver were introduced as semantic conventions in [v1.29.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.29.0/docs/system/k8s-metrics.md).
 
 The changes in their attributes are the following: