feat(tracing)!: Improve control plane tracing configuration #14557

sfleen · 2025-09-30T17:58:33Z

The current control plane tracing relies on the linkerd-jaeger extension, and does not work when using the native tracing configuration.

This removes the previous configs, and adds new control plane tracing config that mirrors the existing proxy tracing configs.

The previous configuration was meant entirely for internal testing purposes, and shouldn't be subject to any breaking change guarantees.

This clarifies the tracing documentation that the trace collector must be meshed, along with the specifics of how the service account name for the collector should be set. Signed-off-by: Scott Fleener <[email protected]>

This separates out the service account namespace from the name to make it clearer how to set the correct service account for the trace collector. Signed-off-by: Scott Fleener <[email protected]>

…lector mesh identity Signed-off-by: Scott Fleener <[email protected]>

The current control plane tracing relies on the linkerd-jaeger extension, and does not work when using the native tracing configuration. This removes the previous configs, and adds new control plane tracing config that mirrors the existing proxy tracing configs. The previous configuration was meant entirely for internal testing purposes, and shouldn't be subject to any breaking change guarantees. Signed-off-by: Scott Fleener <[email protected]>

olix0r · 2025-09-30T18:40:40Z

pkg/charts/linkerd2/values.go

 	// PodDisruptionBudget contains the fields to set the PDB
 	PodDisruptionBudget struct {
-		MaxUnavailable int `json:"maxUnavailable"`
+		MaxUnavailable string `json:"maxUnavailable"`


This is a little surprising. Why is this necessary?

This field can also be a percentage value, which can't parse as an int. Not sure if there's a better way to encode this

olix0r · 2025-09-30T18:44:42Z

charts/linkerd-control-plane/values.yaml

+        # -- Service account namespace for the trace collector. If there's no explicitly set service account for the
+        # trace collector, this should be set to the namespace of the deployment/statefulset/daemonset of the trace
+        # collector instead.
+        serviceAccountNamespace: ""


Suggested change

serviceAccountNamespace: ""

namespace: ""

blegh, sorry to yakshave this, but we are probably better off just calling this 'namespace'

WDYT about "name" and "namespace" for the fields? That lets us leave the old one in with the same semantics to avoid a breaking change, and have a less confusing name since "Service account" isn't exactly the right name for this.

Sorry, I think I'm partial to serviceAccountName and namespace here:

these are how these fields are named on pod spec/metadata resources, so it's consistent

the 'name' is ambiguous. i think it's clearer if we document that this is explicitly a serviceAccountName (as on the pod spec).

the namespace is more general -- it includes the workloads and the services blah blah blah

adleong · 2025-09-30T18:33:58Z

charts/linkerd-control-plane/values.yaml

+        # collector, this should be set to the name of the deployment/statefulset/daemonset of the trace collector
+        # instead.


is this true? if the collector doesn't specify a service account, I thought it used the default service account for it's namespace.

From all of my testing, the value here is correct. However, I'm not entirely sure "service account" is the most accurate name, since this is actually the name of the mesh identity the collector's proxy uses (which is either the service account or deployment/etc. name if not present).

adleong · 2025-09-30T18:37:18Z

charts/linkerd-control-plane/values.yaml

+        # -- Service account namespace for the trace collector. If there's no explicitly set service account for the
+        # trace collector, this should be set to the namespace of the deployment/statefulset/daemonset of the trace
+        # collector instead.
+        serviceAccountNamespace: ""


Prior to this change, did the namespace need to be specified as part of the serviceAccountName? Is this breaking change necessary?

Furthermore, we're introducing a new, required value here so this breaking change will affect everyone who has proxy.tracing enabled.

The namespace did need to be specified before this, in the format <service account>.<namespace>. I'd rather we have two separate fields with a clearer intent.

WDYT about #14557 (comment) as a better state?

In that case, can we leave serviceAccountName in the values.yaml but document it as deprecated and that the name/namespace fields are preferred but that it still exists for backwards compatibility. Let's leave a paper trail of why there are two different configuration methods here.

adleong · 2025-09-30T18:50:43Z

charts/linkerd-control-plane/values.yaml

+  # Configures tracing in the controllers and how traces are exported
+  tracing:
+    # -- Enables trace collection and export in the proxy
+    enable: false


any point to having this boolean vs just looking at if collector.endpoints is empty?

I vaguely remember @alpeb suggesting an explicit enable/disable field, but I don't remember the specifics of why.

I can't remember either 😆
Looking through #13994, there was discussion around not using boolean values, and validating that tracing.enable is consistent with the contents of collector.endpoint in the proxy config below. Anyways, relying on collector.endpoints emptiness sounds like a simpler approach to me too, but would be good to use the same approach here and in the proxy section.

Signed-off-by: Scott Fleener <[email protected]>

…e fields Signed-off-by: Scott Fleener <[email protected]>

# Conflicts: # cli/cmd/install_test.go # pkg/charts/linkerd2/values.go

cratelyn · 2025-09-30T21:20:00Z

if you will pardon the drive-by nitpick; i've renamed this to follow the conventional commit spec for breaking changes with a specified scope.

Signed-off-by: Scott Fleener <[email protected]>

adleong · 2025-10-01T17:06:22Z

BUILD.md

-flag.
+[Distributed Tracing](https://opentracing.io/docs/overview/what-is-tracing/)
+for  development purposes. It can be enabled globally i.e Control plane
+components  and their proxies by using the


nit: there's an extra space character after "components"

adleong · 2025-10-01T17:46:44Z

charts/linkerd-control-plane/values.yaml

+        # -- Service account namespace for the trace collector. If there's no explicitly set service account for the
+        # trace collector, this should be set to the namespace of the deployment/statefulset/daemonset of the trace
+        # collector instead.
+        serviceAccountNamespace: ""


In that case, can we leave serviceAccountName in the values.yaml but document it as deprecated and that the name/namespace fields are preferred but that it still exists for backwards compatibility. Let's leave a paper trail of why there are two different configuration methods here.

Signed-off-by: Scott Fleener <[email protected]>

# Conflicts: # cli/cmd/install_test.go # pkg/charts/linkerd2/values.go # pkg/charts/linkerd2/values_test.go

Signed-off-by: Scott Fleener <[email protected]>

# Conflicts: # cli/cmd/install_test.go # pkg/charts/linkerd2/values.go

Signed-off-by: Scott Fleener <[email protected]>

# Conflicts: # cli/cmd/install_test.go # pkg/charts/linkerd2/values.go # pkg/charts/linkerd2/values_test.go

sfleen added 4 commits September 30, 2025 09:34

chore(docs): Update tracing documentation

5f0a72e

This clarifies the tracing documentation that the trace collector must be meshed, along with the specifics of how the service account name for the collector should be set. Signed-off-by: Scott Fleener <[email protected]>

chore(docs): Include serviceAccountNamespace for tracing collector

5b22d29

This separates out the service account namespace from the name to make it clearer how to set the correct service account for the trace collector. Signed-off-by: Scott Fleener <[email protected]>

chore(docs): Make docs clearer about what needs to be set for the col…

878388b

…lector mesh identity Signed-off-by: Scott Fleener <[email protected]>

Merge branch 'main' into sfleen/tracing-docs

7d466ad

sfleen requested a review from a team as a code owner September 30, 2025 17:58

sfleen force-pushed the sfleen/trace-control-plane branch from 839876c to 7f43cf4 Compare September 30, 2025 18:00

olix0r reviewed Sep 30, 2025

View reviewed changes

adleong reviewed Sep 30, 2025

View reviewed changes

sfleen added 3 commits September 30, 2025 15:05

fix(test): Update tracing test values

3bf0807

Signed-off-by: Scott Fleener <[email protected]>

feat(charts): Switch ServiceAccountName to separate Name and Namespac…

ee54f4b

…e fields Signed-off-by: Scott Fleener <[email protected]>

Merge branch 'sfleen/tracing-docs' into sfleen/trace-control-plane

6929527

# Conflicts: # cli/cmd/install_test.go # pkg/charts/linkerd2/values.go

cratelyn changed the title ~~feat!(tracing): Improve control plane tracing configuration~~ feat(tracing)!: Improve control plane tracing configuration Sep 30, 2025

sfleen added 2 commits October 1, 2025 09:36

fix: Change deprecated casing for lint

4ff225a

Signed-off-by: Scott Fleener <[email protected]>

Merge branch 'sfleen/tracing-docs' into sfleen/trace-control-plane

94c7733

sfleen requested review from olix0r and adleong October 1, 2025 15:59

adleong reviewed Oct 1, 2025

View reviewed changes

sfleen added 4 commits October 1, 2025 14:03

chore: Rename fields and semantics of tracing identity

2e13994

Signed-off-by: Scott Fleener <[email protected]>

Merge branch 'sfleen/tracing-docs' into sfleen/trace-control-plane

07befbb

# Conflicts: # cli/cmd/install_test.go # pkg/charts/linkerd2/values.go # pkg/charts/linkerd2/values_test.go

chore: Fix bad auto-rename

834bf51

Signed-off-by: Scott Fleener <[email protected]>

Merge branch 'sfleen/tracing-docs' into sfleen/trace-control-plane

181ce2e

sfleen changed the base branch from main to sfleen/tracing-docs October 1, 2025 18:23

sfleen added 5 commits October 1, 2025 14:37

chore: Change to breaking API change

4dd8b35

Signed-off-by: Scott Fleener <[email protected]>

Merge branch 'sfleen/tracing-docs' into sfleen/trace-control-plane

84e19fa

# Conflicts: # cli/cmd/install_test.go # pkg/charts/linkerd2/values.go

chore: Regenerate goldens

13ef917

Signed-off-by: Scott Fleener <[email protected]>

fix: Use correct trace enable value

5bd0ee9

Signed-off-by: Scott Fleener <[email protected]>

fix(docs): Typos in docs

1b0da85

Signed-off-by: Scott Fleener <[email protected]>

olix0r approved these changes Oct 1, 2025

View reviewed changes

adleong approved these changes Oct 1, 2025

View reviewed changes

Base automatically changed from sfleen/tracing-docs to main October 1, 2025 19:21

Merge branch 'main' into sfleen/trace-control-plane

f65e7e0

# Conflicts: # cli/cmd/install_test.go # pkg/charts/linkerd2/values.go # pkg/charts/linkerd2/values_test.go

sfleen enabled auto-merge (squash) October 1, 2025 19:23

sfleen merged commit 3b46333 into main Oct 1, 2025
69 of 72 checks passed

sfleen deleted the sfleen/trace-control-plane branch October 1, 2025 19:54

		# collector, this should be set to the name of the deployment/statefulset/daemonset of the trace collector
		# instead.

feat(tracing)!: Improve control plane tracing configuration #14557

feat(tracing)!: Improve control plane tracing configuration #14557

Uh oh!

Conversation

sfleen commented Sep 30, 2025

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!

Choose a reason for hiding this comment

Uh oh!

adleong Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

cratelyn commented Sep 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adleong Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

adleong Oct 1, 2025 •

edited

Loading

adleong Oct 1, 2025 •

edited

Loading