gep-4768: add TelemetryPolicy API proposal by gkhom · Pull Request #4872 · kubernetes-sigs/gateway-api

gkhom · 2026-05-17T01:19:57Z

What type of PR is this?

/kind gep

What this PR does / why we need it:

Added an initial proposal for the TelemetryPolicy API (gep-4768). This includes an example, the Go structs, and comparison with prior art. (See: #4768)

Does this PR introduce a user-facing change?:

NONE

Added an initial proposal for the TelemetryPolicy API. This includes an example, the Go structs, and comparison with prior art.

k8s-ci-robot · 2026-05-17T01:20:05Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: gkhom
Once this PR has been reviewed and has the lgtm label, please assign youngnick for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

geps/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

k8s-ci-robot · 2026-05-17T01:20:07Z

Hi @gkhom. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

LiorLieberman · 2026-05-18T14:19:16Z

/ok-to-test
/cc @rikatz
/cc

rikatz · 2026-05-18T14:51:11Z

+
+  # 1. Tracing Configuration
+  tracing:
+    mode: "On"


the mode here is kind of a weird value. Usually we avoid to have bools or "wana be bools" (On/Off, True/False) and instead make them more explicit on Behavior (Disabled, PartiallyEnabled, FullyEnabled)

If we can only have On/Off, wouldn't it make more sense to say "if tracing is null, tracing should be disabled" instead?

(btw this applies to every "Mode" defined here)

rikatz · 2026-05-18T14:55:14Z

+  # 3. Access Logs Configuration
+  accessLogs:
+    mode: "Off" # Explicitly disabled while keeping the configuration intact
+    matches: "response.code >= 500" # Conditional logging, CEL filtering for errors


honest question here: is CEL matching for logs something usually supported by OTEL exporters, or is this something specific from Istio that we are carrying?

rikatz · 2026-05-18T14:55:56Z

+
+The following are the Go structs modeling the proposed specification.
+
+```Go


Suggested change

```Go

```go

the case here makes difference for markdown rendering :)

rikatz · 2026-05-18T14:57:13Z

+  metav1.TypeMeta   `json:",inline"`
+  metav1.ObjectMeta `json:"metadata,omitempty"`
+
+  Spec TelemetryPolicySpec `json:"spec"`


to avoid previous mistakes, can we make it explicit this is required?

Suggested change

Spec TelemetryPolicySpec `json:"spec"`

// Spec defines the desired state of TLSRoute.

// +required

Spec TelemetryPolicySpec `json:"spec"`

nit: you mean "the desired state of TelemetryPolicy" probably

sjberman · 2026-05-18T15:40:47Z

If it helps with some of this API design, here is the ObservabilityPolicy API used by NGINX Gateway Fabric to configure the nginx-otel module. It attaches to a Route.

NGINX supports setting span names and trace context as well, which I don't see in the proposed API.

In addition, we configure the exporter settings at the Gateway level in our NginxProxy API, which includes things like service.name attribute, export interval, batch size, and batch count.

Since we already support all of these fields, the new TelemetryPolicy would need to support them as well in some form before we would be able to migrate to it.

sjberman · 2026-05-18T15:34:41Z

+  Mode TelemetryMode `json:"mode,omitempty"`
+
+  // The sampling rate to apply when the parent span decision is used.
+  SamplingRate *Fraction `json:"samplingRate,omitempty"`


Why is this sampling rate needed? If we're already inheriting from the parent, isn't that making the decision on whether or not to sample?

Is the samplingRate in this context treated as a fallback strategy when no sampling decision has been propagated from the parent?

rikatz · 2026-05-18T16:14:09Z

+
+const (
+  // CustomAttributeTypeHeader extracts the value from an HTTP header.
+  CustomAttributeTypeHeader CustomAttributeType = "Header"


can we be explicit of what can be added or not? I would expect that we are careful with things like "Authorization" headers and other sensitive headers.

rikatz · 2026-05-18T16:18:04Z

+const (
+  // CustomAttributeTypeHeader extracts the value from an HTTP header.
+  CustomAttributeTypeHeader CustomAttributeType = "Header"
+  // CustomAttributeTypeMetadata extracts the value from proxy metadata or context.


so, Metadata is a bit of a confusing concept in this context. I am worried we are making it very "Envoy" centric (unless @sjberman tells me he gets the concept of "metadata" here out of Nginx)

As we are leaning towards OTEL, I think it would be good to be more explicit on what each attribute means (eg.: https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/ ) and use some OTEL references here

No concept of metadata in nginx.

rikatz · 2026-05-18T16:32:12Z

+}
+
+type TelemetryPolicySpec struct {
+  // Identifies the target gateways to which this policy attaches (GEP-713).


we must be specific here that at least one target is required

rikatz · 2026-05-18T16:40:14Z

+  // Identifies the target gateways to which this policy attaches (GEP-713).
+  TargetRefs []NamespacedPolicyTargetReference `json:"targetRefs"`
+
+  // Configuration for distributed tracing options.


The comment must be more complete. Think on users using this API. We must write here what is tracing, what Gateway users will get from it.

This applies for every comment on every struct, I would recommend taking a look into https://gateway-api.sigs.k8s.io/reference/api-spec/main/spec/#backendtlspolicy

Each API field must contain:

What is the field

What happens when a user configure that field (or in the absence of that field)

Are there specific conflicting options?

Anything else that may help users to use

Also, given this is a field documentation for implementations, you must consider:

What an implementation must know when considering that field? (does setting it has any caveat? Does the implementation needs to consider some condition status?)

What the permutation of possible values can cause that the implementation must care? (think on conformance tests)

Think on https://gateway-api.sigs.k8s.io/guides/api-design/. The documentation must be separated between user facing and implementation facing (when writing implementation/developers facing, use the tag <gateway:util:excludeFromCRD></gateway:util:excludeFromCRD>)

Also, when defining fields you must define what kind of support you expect for it. Eg.:

core - means that the field is required to be recognized by the implementation for this feature to work. eg.: targetRefs

extended - means that the feature/field should be implemented by implementations that claim its support, but are not mandatory for the whole feature. eg.: a telemetryPolicy may support tracing, or metrics, or accessLogs, but doesn't require all of them to work

implementationSpecific - We don't do conformance test, and a user using it knows they will not have portability between implementations. We should avoid this kind of support, and use only if strictly required on new apis. An example is my question about the cel matching for logs, as I don't think every implementation supports it

+1 defining support levels at this stage is very important. Also worth keeping in mind, everything in core and extended should be covered by conformance tests, otherwise it risks becoming implementation-specific anyway.

howardjohn · 2026-05-18T16:19:35Z

+  tracing:
+    mode: "On"
+    provider:
+      endpoint: "otel-collector.monitoring.svc:4317"


should probably use backendRef style API to align with other APIs

+1 otherwise we have to discuss again how to specify TLS, ... (as also mentioned in https://github.com/kubernetes-sigs/gateway-api/pull/4872/changes/BASE..084523a5d6aa69293ca1b9577fabdab8487ba0da#r3260666205)

howardjohn · 2026-05-18T16:47:24Z

+  // Mode explicitly controls if metric generation is enabled. Valid values are "On" or "Off".
+  // +kubebuilder:validation:Enum=On;Off
+  // +kubebuilder:default=On
+  Mode TelemetryMode `json:"mode,omitempty"`


For all the modes, what happens if I do not set the field? is it explicitly OFF or can it be "default for the proxy"?

What if I do not attach a TelemetryPolicy at all?

howardjohn · 2026-05-18T16:47:47Z

+// --- Metrics Types ---
+
+type MetricsConfig struct {
+  // Mode explicitly controls if metric generation is enabled. Valid values are "On" or "Off".


What does it mean to turn off metrics generation? It does not seem reasonable to entirely disable all metrics for an application

howardjohn · 2026-05-18T16:48:37Z

+  Mode TelemetryMode `json:"mode,omitempty"`
+
+  // List of configurations to customize specific metric families.
+  Overrides []MetricOverride `json:"overrides,omitempty"`


What does this actually do? Is it customizing an existing metric? adding a new one?

howardjohn · 2026-05-18T16:49:33Z

+  MetricAttributeTypeLiteral MetricAttributeType = "Literal"
+)
+
+type MetricAttribute struct { 


So we can add fields only right, not remove them?

howardjohn · 2026-05-18T16:49:54Z

+  // A list of specific fields or headers to include in the logs.
+  Fields []string `json:"fields,omitempty"`
+
+  // A list of specific fields to include in the logs, specifying their source.
+  Fields []LogField `json:"fields,omitempty"`


dupe field?

howardjohn · 2026-05-18T16:50:23Z

+  // This is required if Type is "Literal".
+  LiteralValue *string `json:"literalValue,omitempty"`
+
+  // StandardValue specifies a standard log property (e.g., "RequestStartTime", "Duration").


Are these defined? or implementation specific?

howardjohn · 2026-05-18T16:52:31Z

+}
+```
+
+## Comparison with Prior Art


This API seems to basically just be directly Istio's API. It doesn't seem like we really explored prior art beyond that even though there was substantial feedback on the original agentic-networking exploring alternative approaches. Can we get some of that context here? Even if its 'ideas considered but rejected' its still useful

sjberman · 2026-05-18T17:03:12Z

+}
+
+type TracingProvider struct {
+  Endpoint string `json:"endpoint,omitempty"`


How about TLS options and custom headers, per #4775 (comment)

snorwin · 2026-05-19T07:10:13Z

+  LogFieldTypeStandard LogFieldType = "Standard"
+)
+
+type LogField struct {


It's not clear to me what the fields LogField in the log represents, is it a JSON field for specifying additional key-value pairs?

How do you plan to support customization of nested JSON structures? These are commonly used in access logs, e.g., in the Airlock Microgateway we use the Elastic Common Schema (ECS).

Since access logs tend to be highly implementation-specific, IMO a format string or an extension point is probably the best approach here.

snorwin · 2026-05-19T07:21:39Z

+  Mode TelemetryMode `json:"mode,omitempty"`
+
+  // The sampling rate to apply when the parent span decision is used.
+  SamplingRate *Fraction `json:"samplingRate,omitempty"`


Is the samplingRate in this context treated as a fallback strategy when no sampling decision has been propagated from the parent?

snorwin · 2026-05-19T07:25:54Z

+  // Identifies the target gateways to which this policy attaches (GEP-713).
+  TargetRefs []NamespacedPolicyTargetReference `json:"targetRefs"`
+
+  // Configuration for distributed tracing options.


+1 defining support levels at this stage is very important. Also worth keeping in mind, everything in core and extended should be covered by conformance tests, otherwise it risks becoming implementation-specific anyway.

snorwin · 2026-05-19T07:28:22Z

+}
+```
+
+## Comparison with Prior Art


Could you also include the Airlock Microgateway Telemetry CR and the NGINX Tracing API as prior art?

david-martin · 2026-05-25T16:35:16Z

+    name: my-gateway
+
+  # 1. Tracing Configuration
+  tracing:


should enabling of tracing imply that 'traceparent' header propagation also happens?

gep-4768: add TelemetryPolicy API proposal

084523a

Added an initial proposal for the TelemetryPolicy API. This includes an example, the Go structs, and comparison with prior art.

k8s-ci-robot added release-note-none Denotes a PR that doesn't merit a release note. kind/gep PRs related to Gateway Enhancement Proposal(GEP) do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. labels May 17, 2026

k8s-ci-robot requested review from davidjumani and mikemorris May 17, 2026 01:20

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels May 17, 2026

k8s-ci-robot requested a review from LiorLieberman May 18, 2026 14:19

k8s-ci-robot added the ok-to-test Indicates a non-member PR verified by an org member that is safe to test. label May 18, 2026

k8s-ci-robot requested a review from rikatz May 18, 2026 14:19

k8s-ci-robot removed the needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. label May 18, 2026

rikatz reviewed May 18, 2026

View reviewed changes

sjberman reviewed May 18, 2026

View reviewed changes

rikatz reviewed May 18, 2026

View reviewed changes

howardjohn reviewed May 18, 2026

View reviewed changes

sjberman reviewed May 18, 2026

View reviewed changes

snorwin reviewed May 19, 2026

View reviewed changes

david-martin mentioned this pull request May 19, 2026

TelemetryPolicy proposal kubernetes-sigs/kube-agentic-networking#69

Open

david-martin reviewed May 25, 2026

View reviewed changes


		The following are the Go structs modeling the proposed specification.

		```Go

Conversation

gkhom commented May 17, 2026

Uh oh!

k8s-ci-robot commented May 17, 2026

Uh oh!

k8s-ci-robot commented May 17, 2026

Uh oh!

LiorLieberman commented May 18, 2026

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!

LiorLieberman May 19, 2026 • 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!

sjberman commented May 18, 2026

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!

rikatz May 18, 2026 • 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!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

LiorLieberman May 19, 2026 •

edited

Loading

rikatz May 18, 2026 •

edited

Loading