From 106f880ccbf26443f115ce1f48c236ec6a0b6f1b Mon Sep 17 00:00:00 2001 From: Christos Markou Date: Thu, 5 Dec 2024 17:42:03 +0200 Subject: [PATCH] add k8s semconv migration non-normative doc (#1597) Signed-off-by: ChrsMark Co-authored-by: Tyler Helmuth <12352919+TylerHelmuth@users.noreply.github.com> --- .chloggen/k8s-migration.yaml | 22 ++++++++++ .github/CODEOWNERS | 5 ++- docs/non-normative/k8s-migration.md | 68 +++++++++++++++++++++++++++++ 3 files changed, 93 insertions(+), 2 deletions(-) create mode 100755 .chloggen/k8s-migration.yaml create mode 100644 docs/non-normative/k8s-migration.md diff --git a/.chloggen/k8s-migration.yaml b/.chloggen/k8s-migration.yaml new file mode 100755 index 0000000000..f9a4de7bbe --- /dev/null +++ b/.chloggen/k8s-migration.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: k8s + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add migration guide for K8s semantic conventions + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1597] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 5c2a3334df..edaab04fe1 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -58,8 +58,9 @@ /model/device/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-mobile-approvers # K8s semantic conventions -/docs/resource/k8s.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers -/model/k8s/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers +/docs/resource/k8s.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers +/model/k8s/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers +/docs/non-normative/k8s-migration.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers # Container semantic conventions /docs/resource/container.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers diff --git a/docs/non-normative/k8s-migration.md b/docs/non-normative/k8s-migration.md new file mode 100644 index 0000000000..8a8f305dac --- /dev/null +++ b/docs/non-normative/k8s-migration.md @@ -0,0 +1,68 @@ + + +# K8s semantic conventions stability migration + +Due to the significant number of modifications and the extensive user base +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. + +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 + their existing major version, which accepts: + - `k8s` - emit the stable k8s conventions, and stop emitting + the old k8s conventions that the instrumentation emitted previously. + - `k8s/dup` - emit both the old and the stable k8s conventions, + allowing for a phased rollout of the stable semantic conventions. + - The default behavior (in the absence of one of these values) is to continue + emitting whatever version of the old k8s conventions the + instrumentation was emitting previously. +- Need to maintain (security patching at a minimum) their existing major version + for at least six months after it starts emitting both sets of conventions. +- 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 called `semconv.k8s.enableStable`, +and one for disabling the old schema called `semconv.k8s.disableLegacy`. Then: + +- On alpha the old schema is enabled by default (`semconv.k8s.disableLegacy` defaults to false), + while the new schema is disabled by default (`semconv.k8s.enableStable` defaults to false). +- On beta/stable the old schema is disabled by default (`semconv.k8s.disableLegacy` defaults to true), + while the new is enabled by default (`semconv.k8s.enableStable` defaults to true). +- It is an error to disable both schemas +- Both schemas can be enabled with `--feature-gates=-semconv.k8s.disableLegacy,+semconv.k8s.enableStable`. + + + +- [Summary of changes](#summary-of-changes) + - [K8s network metrics](#k8s-network-metrics) + + + +## Summary of changes + +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 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.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: + + +| Old (Collector) ![changed](https://img.shields.io/badge/changed-orange?style=flat) | New | +|------------------------------------------------------------------------------------|---------------------------| +| `interface` | `network.interface.name` | +| `direction` | `network.io.direction` | +