Add RFC: Instrumentation v1beta1 by pavolloffay · Pull Request #5079 · open-telemetry/opentelemetry-operator

pavolloffay · 2026-05-13T15:16:33Z

Description:

This PR adds RFC for Instrumenation v1beta1

Link to tracking Issue(s):

Related to #5060

Explanation fo managing multiple CRD versions: https://gist.github.com/pavolloffay/e8bf0ad2c42cd94e82f2354a3559894f

Testing:

Documentation:

swiatekm

Looks good to me overall. I have a major question involving the annotation -> label change, and some minor ones.

github-actions · 2026-05-27T14:32:28Z

E2E Test Results

38 files 271 suites 2h 19m 57s ⏱️
115 tests 114 ✅ 1 💤 0 ❌
293 runs 291 ✅ 2 💤 0 ❌

Results for commit 4f08a47.

♻️ This comment has been updated with latest results.

swiatekm

LGTM overall, some questions about the annotation -> label migration.

swiatekm · 2026-05-30T10:17:42Z

+#### Deprecation path
+
+1. **v1beta1**: Both labels and annotations supported. Annotations deprecated but functional.
+2. **v1alpha1 removal**: Annotations no longer documented, labels become the primary mechanism. Annotations support is eventually dropped.


This isn't fully clear to me. Are we planning to support annotations until we go to v1? Or do they go away with v1alpha1?

I have clarified it

v1alpha1 removal: Labels become the primary mechanism. Annotations support is dropped.

swiatekm · 2026-05-30T10:18:30Z

+```yaml
+webhooks:
+  - name: mpod.kb.io
+    objectSelector:
+      matchExpressions:
+        - key: instrumentation.opentelemetry.io/inject-java
+          operator: Exists
+        - key: instrumentation.opentelemetry.io/inject-python
+          operator: Exists
+        # ... other languages
+```
+
+This reduces webhook invocations to only pods that have opted in via labels, improving cluster performance. Pods using legacy annotations will still pass through the webhook (no `objectSelector` match), maintaining backwards compatibility.


This only works if we're not supporting annotations, right? So it'll have to be an option in either the kustomize manifests or the Helm Chart.

yes it can be only enforced once we don't support annotations. I would give it as opt-in before we fully drop support for the annotation.

Added some clarification ot the readme.

jaronoff97

a few small thoughts, otherwise looks great. thank you Pavol! 🙇

jaronoff97 · 2026-06-05T15:04:51Z

+1. Aligns with OpenTelemetry's [declarative configuration](https://github.com/open-telemetry/opentelemetry-configuration) initiative
+2. Fixes structural inconsistencies in the current API
+
+## Objectives


One thing i think we should also do is let users target specific otelcol CRDs rather than needing to hand write a svc / url. i.e. someone could target namespace/otelcol or something like that and we would validate that the collector exists and then write the url for them.

jaronoff97 · 2026-06-05T15:05:53Z

+spec:
+  declarativeConfig:
+    file_format: "0.4"
+    resource:


I know why it's like this, but i don't love that we mix camel case and snake case.

jaronoff97 · 2026-06-05T15:07:28Z

+
+The declarative config supports [environment variable substitution](https://opentelemetry.io/docs/specs/otel/configuration/file-configuration/#environment-variable-substitution) using the `${VAR}` syntax. This is useful for injecting secrets like API tokens without hardcoding them in the CR. Environment variables can be set via `spec.env` or per-language `env` fields.
+
+This also addresses a limitation in v1alpha1 where Kubernetes `$(VAR)` substitution fails due to env var ordering ([#3022](https://github.com/open-telemetry/opentelemetry-operator/issues/3022)). Since `${VAR}` substitution in declarative config happens at SDK runtime rather than Kubernetes pod creation time, it works regardless of the order in which env vars are defined.


One thing that I think would be useful here is to add a "presets" section for setting the resource hierarchy like we do today, this would make it easier for users to opt out and then all we do internally is set the declarative config and let that figure out the layering later on.

The resource attributes in v1beta1 will be handled by:

spec.resource.k8sMetadata.enabled — toggle for K8s resource attributes

spec.resource.k8sMetadata.includeUIDs — toggle for UID attributes

spec.resource.serviceMetadata.enabled — toggle for service identity attributes

They are mutually exclusive. The service name resolution uses the spec https://opentelemetry.io/docs/specs/semconv/non-normative/k8s-attributes/#service-attributes

jaronoff97 · 2026-06-05T15:18:34Z

+metadata:
+  name: env-example
+spec:
+  envConfig:


we should note that this will be removed/deprecated when we go to v1

I don't think that is the goal. We might remove it if the SDKs stop supporting the env config

mmanciop · 2026-06-17T17:53:20Z

+1. Aligns with OpenTelemetry's [declarative configuration](https://github.com/open-telemetry/opentelemetry-configuration) initiative
+2. Fixes structural inconsistencies in the current API
+
+## Objectives


Out of experience with multiple OTel adopters, treating the trace-context propagation format (and, specifically, opt-in to AWS XRay) as a first-class citizen in the CRD, pays off

We already support in as a first-class citizen in the CRD. The goal is to support as much as possible from the stable config symbols.

mmanciop · 2026-06-17T17:59:07Z

+
+The operator will have a flag to control declarative configuration support  (e.g., `--instrumentation-declarative-config=java,python,dotnet,cpp,nodejs`). This allows enabling support as SDKs mature without requiring operator upgrades.
+
+#### Declarative config example


In the system packages SIG, we are having issues with the fact that all implementations of the declarative SDK but Java seem not to allow per-language overrides, e.g. to disable instrumentations. It seems to me you may face the same issue.

Are you referring to this part of the config https://github.com/open-telemetry/opentelemetry-configuration/blob/main/schema-docs.md#experimentalinstrumentation- ?

Signed-off-by: Pavol Loffay <p.loffay@gmail.com>

pavolloffay requested a review from a team as a code owner May 13, 2026 15:16

pavolloffay mentioned this pull request May 13, 2026

Stability and Production Readiness of Instrumentation CRD (v1alpha1) #5060

Open

swiatekm reviewed May 14, 2026

View reviewed changes

Comment thread docs/rfcs/instrumentation-v1beta1.md Outdated

Comment thread docs/rfcs/instrumentation-v1beta1.md

Comment thread docs/rfcs/instrumentation-v1beta1.md

Comment thread docs/rfcs/instrumentation-v1beta1.md

pavolloffay added the Skip Changelog PRs that do not require a CHANGELOG.md entry label May 18, 2026

swiatekm reviewed May 30, 2026

View reviewed changes

swiatekm approved these changes Jun 1, 2026

View reviewed changes

jaronoff97 approved these changes Jun 5, 2026

View reviewed changes

mmanciop reviewed Jun 17, 2026

View reviewed changes

Comment thread docs/rfcs/instrumentation-v1beta1.md Outdated

mmanciop reviewed Jun 17, 2026

View reviewed changes

pavolloffay added 10 commits June 25, 2026 16:13

Add RFC: Instrumentation v1beta1

cff6d7b

Signed-off-by: Pavol Loffay <p.loffay@gmail.com>

Some review comments

baacd6b

Signed-off-by: Pavol Loffay <p.loffay@gmail.com>

Add CRD versioning explanation

c65e592

Signed-off-by: Pavol Loffay <p.loffay@gmail.com>

Add CRD versioning explanation

ac492f0

Signed-off-by: Pavol Loffay <p.loffay@gmail.com>

Add supporting doc

30f1a04

Signed-off-by: Pavol Loffay <p.loffay@gmail.com>

Add section about migration

925fb11

Signed-off-by: Pavol Loffay <p.loffay@gmail.com>

Add labels support

b5b6471

Signed-off-by: Pavol Loffay <p.loffay@gmail.com>

Review comments

49f5cdc

Signed-off-by: Pavol Loffay <p.loffay@gmail.com>

Review comments

24e884e

Signed-off-by: Pavol Loffay <p.loffay@gmail.com>

Fix review comments

cc98f69

Signed-off-by: Pavol Loffay <p.loffay@gmail.com>

pavolloffay force-pushed the inst-rfc branch from 4f08a47 to cc98f69 Compare June 25, 2026 14:51

pavolloffay merged commit b985889 into open-telemetry:main Jun 25, 2026
58 checks passed


		The declarative config supports [environment variable substitution](https://opentelemetry.io/docs/specs/otel/configuration/file-configuration/#environment-variable-substitution) using the `${VAR}` syntax. This is useful for injecting secrets like API tokens without hardcoding them in the CR. Environment variables can be set via `spec.env` or per-language `env` fields.

		This also addresses a limitation in v1alpha1 where Kubernetes `$(VAR)` substitution fails due to env var ordering ([#3022](https://github.com/open-telemetry/opentelemetry-operator/issues/3022)). Since `${VAR}` substitution in declarative config happens at SDK runtime rather than Kubernetes pod creation time, it works regardless of the order in which env vars are defined.


		The operator will have a flag to control declarative configuration support (e.g., `--instrumentation-declarative-config=java,python,dotnet,cpp,nodejs`). This allows enabling support as SDKs mature without requiring operator upgrades.

		#### Declarative config example

Uh oh!

Conversation

pavolloffay commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

swiatekm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Test Results

Uh oh!

swiatekm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaronoff97 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

pavolloffay commented May 13, 2026 •

edited

Loading

github-actions Bot commented May 27, 2026 •

edited

Loading