From bb79598c394e04be56160e91b36db220560d4ff8 Mon Sep 17 00:00:00 2001 From: Vlad Stefanescu Date: Fri, 25 Sep 2026 10:52:53 +0200 Subject: [PATCH] feat: expose Zipkin trace_context_option in EnvoyProxy tracing Signed-off-by: Vlad Stefanescu --- api/v1alpha1/envoyproxy_tracing_types.go | 18 ++++++++++++++++++ api/v1alpha1/zz_generated.deepcopy.go | 5 +++++ .../gateway.envoyproxy.io_envoyproxies.yaml | 9 +++++++++ .../gateway.envoyproxy.io_envoyproxies.yaml | 9 +++++++++ .../testdata/in/xds-ir/tracing-zipkin.yaml | 1 + .../out/xds-ir/tracing-zipkin.listeners.yaml | 1 + internal/xds/translator/tracing.go | 5 +++++ .../10112-zipkin-trace-context-option.md | 1 + site/content/en/latest/api/extension_types.md | 16 ++++++++++++++++ test/helm/gateway-crds-helm/all.out.yaml | 9 +++++++++ test/helm/gateway-crds-helm/e2e.out.yaml | 9 +++++++++ .../envoy-gateway-crds.out.yaml | 9 +++++++++ 12 files changed, 92 insertions(+) create mode 100644 release-notes/current/new_features/10112-zipkin-trace-context-option.md diff --git a/api/v1alpha1/envoyproxy_tracing_types.go b/api/v1alpha1/envoyproxy_tracing_types.go index 11eaeb686d9..74bfc794567 100644 --- a/api/v1alpha1/envoyproxy_tracing_types.go +++ b/api/v1alpha1/envoyproxy_tracing_types.go @@ -142,8 +142,26 @@ type ZipkinTracingProvider struct { // client and server spans sharing the same span context should be disabled. // +optional DisableSharedSpanContext *bool `json:"disableSharedSpanContext,omitempty"` + // TraceContextOption determines which trace context headers are used to extract + // the trace context from downstream requests and to inject it into upstream requests. + // Defaults to UseB3. + // +optional + TraceContextOption *ZipkinTraceContextOption `json:"traceContextOption,omitempty"` } +// ZipkinTraceContextOption defines the trace context headers used by the Zipkin tracer. +// +kubebuilder:validation:Enum=UseB3;UseB3WithW3CPropagation +type ZipkinTraceContextOption string + +const ( + // ZipkinTraceContextOptionUseB3 uses B3 headers only, for both extraction and injection. + ZipkinTraceContextOptionUseB3 ZipkinTraceContextOption = "UseB3" + // ZipkinTraceContextOptionUseB3WithW3CPropagation extracts the trace context from B3 headers, + // falling back to the W3C traceparent header if B3 headers are absent, and injects both + // B3 and W3C traceparent headers. + ZipkinTraceContextOptionUseB3WithW3CPropagation ZipkinTraceContextOption = "UseB3WithW3CPropagation" +) + // OpenTelemetryTracingProvider defines the OpenTelemetry tracing provider configuration. type OpenTelemetryTracingProvider struct { // Headers is a list of additional headers to send with OTLP export requests. diff --git a/api/v1alpha1/zz_generated.deepcopy.go b/api/v1alpha1/zz_generated.deepcopy.go index b4fb87d37eb..146641bfa13 100644 --- a/api/v1alpha1/zz_generated.deepcopy.go +++ b/api/v1alpha1/zz_generated.deepcopy.go @@ -9401,6 +9401,11 @@ func (in *ZipkinTracingProvider) DeepCopyInto(out *ZipkinTracingProvider) { *out = new(bool) **out = **in } + if in.TraceContextOption != nil { + in, out := &in.TraceContextOption, &out.TraceContextOption + *out = new(ZipkinTraceContextOption) + **out = **in + } } // DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ZipkinTracingProvider. diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml index a6d2d1b8819..59c1c78a989 100644 --- a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml +++ b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml @@ -18975,6 +18975,15 @@ spec: when creating a new trace instance. If set to false, a 64bit trace id will be used. type: boolean + traceContextOption: + description: |- + TraceContextOption determines which trace context headers are used to extract + the trace context from downstream requests and to inject it into upstream requests. + Defaults to UseB3. + enum: + - UseB3 + - UseB3WithW3CPropagation + type: string type: object required: - type diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml index 90a7c515256..3f1b636b8c7 100644 --- a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml +++ b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml @@ -18974,6 +18974,15 @@ spec: when creating a new trace instance. If set to false, a 64bit trace id will be used. type: boolean + traceContextOption: + description: |- + TraceContextOption determines which trace context headers are used to extract + the trace context from downstream requests and to inject it into upstream requests. + Defaults to UseB3. + enum: + - UseB3 + - UseB3WithW3CPropagation + type: string type: object required: - type diff --git a/internal/xds/translator/testdata/in/xds-ir/tracing-zipkin.yaml b/internal/xds/translator/testdata/in/xds-ir/tracing-zipkin.yaml index de560088d50..bcaf0307a45 100644 --- a/internal/xds/translator/testdata/in/xds-ir/tracing-zipkin.yaml +++ b/internal/xds/translator/testdata/in/xds-ir/tracing-zipkin.yaml @@ -36,6 +36,7 @@ tracing: zipkin: enable128BitTraceId: true disableSharedSpanContext: true + traceContextOption: UseB3WithW3CPropagation http: - name: "first-listener" address: "::" diff --git a/internal/xds/translator/testdata/out/xds-ir/tracing-zipkin.listeners.yaml b/internal/xds/translator/testdata/out/xds-ir/tracing-zipkin.listeners.yaml index ecbf2155ae2..9fd7a1a14bb 100644 --- a/internal/xds/translator/testdata/out/xds-ir/tracing-zipkin.listeners.yaml +++ b/internal/xds/translator/testdata/out/xds-ir/tracing-zipkin.listeners.yaml @@ -52,6 +52,7 @@ collectorEndpoint: /api/v2/spans collectorEndpointVersion: HTTP_JSON sharedSpanContext: false + traceContextOption: USE_B3_WITH_W3C_PROPAGATION traceId128bit: true randomSampling: value: 90 diff --git a/internal/xds/translator/tracing.go b/internal/xds/translator/tracing.go index 203c82bf781..723172f9e65 100644 --- a/internal/xds/translator/tracing.go +++ b/internal/xds/translator/tracing.go @@ -88,12 +88,17 @@ func buildHCMTracing(tracing *ir.Tracing) (*hcm.HttpConnectionManager_Tracing, e providerName = envoyZipkin providerConfig = func() (*anypb.Any, error) { + traceContextOption := tracecfg.ZipkinConfig_USE_B3 + if ptr.Deref(tracing.Provider.Zipkin.TraceContextOption, "") == egv1a1.ZipkinTraceContextOptionUseB3WithW3CPropagation { + traceContextOption = tracecfg.ZipkinConfig_USE_B3_WITH_W3C_PROPAGATION + } config := &tracecfg.ZipkinConfig{ CollectorCluster: tracing.Destination.Name, CollectorEndpoint: "/api/v2/spans", TraceId_128Bit: ptr.Deref(tracing.Provider.Zipkin.Enable128BitTraceID, false), SharedSpanContext: wrapperspb.Bool(!ptr.Deref(tracing.Provider.Zipkin.DisableSharedSpanContext, false)), CollectorEndpointVersion: tracecfg.ZipkinConfig_HTTP_JSON, + TraceContextOption: traceContextOption, } return proto.ToAnyWithValidation(config) diff --git a/release-notes/current/new_features/10112-zipkin-trace-context-option.md b/release-notes/current/new_features/10112-zipkin-trace-context-option.md new file mode 100644 index 00000000000..309852ef8f7 --- /dev/null +++ b/release-notes/current/new_features/10112-zipkin-trace-context-option.md @@ -0,0 +1 @@ +Added an optional `traceContextOption` field to the Zipkin tracing provider (`EnvoyProxy.spec.telemetry.tracing.provider.zipkin.traceContextOption`) that exposes Envoy's Zipkin `trace_context_option`; setting it to `UseB3WithW3CPropagation` extracts the trace context from B3 headers with a fallback to the W3C `traceparent` header, and injects both B3 and `traceparent` headers into upstream requests. diff --git a/site/content/en/latest/api/extension_types.md b/site/content/en/latest/api/extension_types.md index 536538b2790..5ca0f331741 100644 --- a/site/content/en/latest/api/extension_types.md +++ b/site/content/en/latest/api/extension_types.md @@ -7139,6 +7139,21 @@ _Appears in:_ | `DraftVersion03` | XRateLimitHeadersOptionDraftVersion03 enables X-RateLimit headers using RFC draft version 03
for this rate limit rule, regardless of the global ClientTrafficPolicy setting.
| +#### ZipkinTraceContextOption + +_Underlying type:_ _string_ + +ZipkinTraceContextOption defines the trace context headers used by the Zipkin tracer. + +_Appears in:_ +- [ZipkinTracingProvider](#zipkintracingprovider) + +| Value | Description | +| ----- | ----------- | +| `UseB3` | ZipkinTraceContextOptionUseB3 uses B3 headers only, for both extraction and injection.
| +| `UseB3WithW3CPropagation` | ZipkinTraceContextOptionUseB3WithW3CPropagation extracts the trace context from B3 headers,
falling back to the W3C traceparent header if B3 headers are absent, and injects both
B3 and W3C traceparent headers.
| + + #### ZipkinTracingProvider @@ -7152,6 +7167,7 @@ _Appears in:_ | --- | --- | --- | --- | --- | | `enable128BitTraceId` | _boolean_ | false | | Enable128BitTraceID determines whether a 128bit trace id will be used
when creating a new trace instance. If set to false, a 64bit trace
id will be used. | | `disableSharedSpanContext` | _boolean_ | false | | DisableSharedSpanContext determines whether the default Envoy behaviour of
client and server spans sharing the same span context should be disabled. | +| `traceContextOption` | _[ZipkinTraceContextOption](#zipkintracecontextoption)_ | false | | TraceContextOption determines which trace context headers are used to extract
the trace context from downstream requests and to inject it into upstream requests.
Defaults to UseB3. | #### ZoneAware diff --git a/test/helm/gateway-crds-helm/all.out.yaml b/test/helm/gateway-crds-helm/all.out.yaml index 9bbbca7790a..53f96c6cc92 100644 --- a/test/helm/gateway-crds-helm/all.out.yaml +++ b/test/helm/gateway-crds-helm/all.out.yaml @@ -53120,6 +53120,15 @@ spec: when creating a new trace instance. If set to false, a 64bit trace id will be used. type: boolean + traceContextOption: + description: |- + TraceContextOption determines which trace context headers are used to extract + the trace context from downstream requests and to inject it into upstream requests. + Defaults to UseB3. + enum: + - UseB3 + - UseB3WithW3CPropagation + type: string type: object required: - type diff --git a/test/helm/gateway-crds-helm/e2e.out.yaml b/test/helm/gateway-crds-helm/e2e.out.yaml index f0a2ca005c5..d7c0e0c3f92 100644 --- a/test/helm/gateway-crds-helm/e2e.out.yaml +++ b/test/helm/gateway-crds-helm/e2e.out.yaml @@ -29058,6 +29058,15 @@ spec: when creating a new trace instance. If set to false, a 64bit trace id will be used. type: boolean + traceContextOption: + description: |- + TraceContextOption determines which trace context headers are used to extract + the trace context from downstream requests and to inject it into upstream requests. + Defaults to UseB3. + enum: + - UseB3 + - UseB3WithW3CPropagation + type: string type: object required: - type diff --git a/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml b/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml index 18d92d27177..cb71e1ac998 100644 --- a/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml +++ b/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml @@ -29058,6 +29058,15 @@ spec: when creating a new trace instance. If set to false, a 64bit trace id will be used. type: boolean + traceContextOption: + description: |- + TraceContextOption determines which trace context headers are used to extract + the trace context from downstream requests and to inject it into upstream requests. + Defaults to UseB3. + enum: + - UseB3 + - UseB3WithW3CPropagation + type: string type: object required: - type