API Reference

Validations:
MaxLength: 256
MinLength: 1
Pattern: ^[a-zA-Z0-9_.:/-]+$
Required

Name is the key of the attribute as it will appear in the output (i.e., as a span tag).

Validations:
Enum: [Header Literal Attribute]
Required

SourceType specifies where the attribute value comes from. Valid values are "Header", "Literal", or "Attribute".

Validations:
MaxLength: 256
MinLength: 1
Pattern: ^[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$
Optional

HeaderName specifies the HTTP header to extract the value from. This is required if SourceType is "Header".

Validations:
MaxLength: 1024
MinLength: 1
Optional

LiteralValue specifies a static string value to attach. This is required if SourceType is "Literal".

Validations:
MaxLength: 256
MinLength: 1
Pattern: ^[a-z0-9_.-]+$
Optional

AttributeKey refers to a standard OpenTelemetry attribute. For example: "http.response.status_code" or "http.request.method". This is required if SourceType is "Attribute". See: https://opentelemetry.io/docs/specs/semconv/

Validations:
Required

ControllerName is a domain/path string that indicates the name of the controller that manages the Backend.

Example: "example.net/gateway-controller".

The format of this field is DOMAIN "/" PATH, where DOMAIN and PATH are valid Kubernetes names (https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names).

Validations:
Required

AncestorRef identifies the ancestor resource that this status is associated with.

Validations:
Optional

For Kubernetes API conventions, see: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties conditions represent the current state of the Backend resource. Each condition has a unique type and reflects the status of a specific aspect of the resource.

Defined condition types include:

• "Accepted": the resource has been acknowledged and accepted by the controller

The status of each condition is one of True, False, or Unknown.

Validations:
Maximum: 65535
Minimum: 1
Optional

Number represents the port number of the destination.

Validations:
Enum: [ExternalHostname EndpointSelector]
Required

Type defines the backend type.

Validations:
MinProperties: 1
Required

Port defines the port to connect to on this backend. For ExternalHostname, this is the port on the external host. For EndpointSelector, this specifies which endpoint port to connect to.

Validations:
Optional

ExternalHostname specifies the configuration for an ExternalHostname backend. This field must be set when type is ExternalHostname and must be unset otherwise.

Support: Extended

Validations:
Optional

EndpointSelector specifies the configuration for an EndpointSelector backend. This field must be set when type is EndpointSelector and must be unset otherwise.

Validations:
Optional

SessionPersistence defines and configures session persistence across the endpoints selected by this backend.

This field can only be configured when type is EndpointSelector.

Support: Extended

Validations:
Enum: [TCP HTTP HTTP2 HTTP11 H2C MCP GRPC WSS]
Optional

Protocol defines the protocol for backend communication.

In the common case, the underlying transport protocol for the proxied traffic will already have been determined and processed by the dataplane at the routing step. Where this field is useful is either for higher level protocols or asymmetrical protocol configurations (e.g. version upgrades or h2c).

When set, the implementation uses the specified protocol when connecting to this backend. When not set, the implementation will use the protocol determined by the route or listener configuration.

Support: Core - HTTP, HTTP2, H2C, and HTTP11

Support: Extended - GRPC, MCP, TCP, WSS

Default: { mode:None }

Validations:
Optional

TLS defines the TLS configuration that the implementation should use when connecting to the backend.

ExternalHostname backends SHOULD have TLS configured; the lack of TLS for external hostnames should be considered insecure and a security risk.

Support: Core - for TLS mode None

Support: Extended - for TLS mode ServerOnly and ClientAndServer

Validations:
MaxItems: 32
Optional

Ancestors is a list of ancestor resources (usually Gateways) that are associated with this Backend, and the status of the Backend with respect to each ancestor.

A maximum of 32 ancestors will be represented in this list. An empty list indicates that the Backend is not associated with any ancestors.

Validations:
Enum: [None ServerOnly ClientAndServer]
Required

Mode defines the TLS mode for the backend connection.

Support: Core - None

Support: Extended - ServerOnly, ClientAndServer

Validations:
Optional

ClientCertificateRef is a reference to a Secret containing the client TLS certificate and private key for mutual TLS. This field is required when mode is ClientAndServer and must be unset otherwise.

Validations:
Optional

Validation contains TLS validation configuration for the backend connection.

Validations:
MaxItems: 16
MinItems: 1
Required

TargetRefs identifies API object(s) to apply this policy to. Currently, Backends (A grouping of like endpoints such as Service, ServiceImport, or any implementation-specific backendRef) are the only valid API target references.

Currently, a TargetRef cannot be scoped to a specific port on a Service.

Validations:
Optional

RetryConstraint defines the configuration for when to allow or prevent further retries to a target backend, by dynamically calculating a ‘retry budget’. This budget is calculated based on the percentage of incoming traffic composed of retries over a given time interval. Once the budget is exceeded, additional retries will be rejected.

For example, if the retry budget interval is 10 seconds, there have been 1000 active requests in the past 10 seconds, and the allowed percentage of requests that can be retried is 20% (the default), then 200 of those requests may be composed of retries. Active requests will only be considered for the duration of the interval when calculating the retry budget. Retrying the same original request multiple times within the retry budget interval will lead to each retry being counted towards calculating the budget.

Configuring a RetryConstraint in BackendTrafficPolicy is compatible with HTTPRoute Retry settings for each HTTPRouteRule that targets the same backend. While the HTTPRouteRule Retry stanza can specify whether a request will be retried, and the number of retry attempts each client may perform, RetryConstraint helps prevent cascading failures such as retry storms during periods of consistent failures.

After the retry budget has been exceeded, additional retries to the backend MUST return a 503 response to the client.

Additional configurations for defining a constraint on retries MAY be defined in the future.

Support: Extended

gateway:experimental

Validations:
Optional

Deprecated: use the Backend resource for session persistence (GEP-4894).

SessionPersistence defines and configures session persistence for the backend.

Support: Extended

Default: 20

Validations:
Maximum: 100
Minimum: 0
Optional

Percent defines the maximum percentage of active requests that may be made up of retries.

Support: Extended

Default: 10s

Validations:
Optional

Interval defines the duration in which requests will be considered for calculating the budget for retries.

Support: Extended

Validations:
MaxProperties: 64
MinProperties: 1
Required

MatchLabels contains a set of required {key,value} pairs. An object must match every label in this map to be selected. The matching logic is an AND operation on all entries.

Validations:
Required

Hostname specifies the FQDN used to reach this backend. IP addresses are not allowed in this field.

Validations:
MaxProperties: 64
MinProperties: 1
Required

MatchLabels contains a set of required {key,value} pairs. An object must match every label in this map to be selected. The matching logic is an AND operation on all entries.

Validations:
Required

ControllerName is the name of a controller that is managing Gateway API resources for mesh traffic management. The value of this field MUST be a domain prefixed path.

Example: "example.com/awesome-mesh".

This field is not mutable and cannot be empty.

Support: Core

Validations:
Optional

ParametersRef is an optional reference to a resource that contains implementation-specific configuration for this Mesh. If no implementation-specific parameters are needed, this field MUST be omitted.

ParametersRef can reference a standard Kubernetes resource, i.e. ConfigMap, or an implementation-specific custom resource. The resource can be cluster-scoped or namespace-scoped.

If the referent cannot be found, refers to an unsupported kind, or when the data within that resource is malformed, the Mesh MUST be rejected with the "Accepted" status condition set to "False" and an "InvalidParameters" reason.

Support: Implementation-specific

Validations:
MaxLength: 64
Optional

Description optionally provides a human-readable description of a Mesh.

Default: [map[lastTransitionTime:1970-01-01T00:00:00Z message:Waiting for controller reason:Pending status:Unknown type:Accepted] map[lastTransitionTime:1970-01-01T00:00:00Z message:Waiting for controller reason:Pending status:Unknown type:Programmed]]

Validations:
MaxItems: 8
Optional

Conditions is the current status from the controller for this Mesh.

Controllers should prefer to publish conditions using values of MeshConditionType for the type of each Condition.

Validations:
MaxItems: 64
Optional

SupportedFeatures is the set of features the Mesh support. It MUST be sorted in ascending alphabetical order by the Name key.

Default: ImplementationDefault

Validations:
Enum: [Enabled Disabled ImplementationDefault]
Optional

Mode explicitly controls if parent-based sampling is enabled. Valid values are "Enabled", "Disabled", "ImplementationDefault".

In the absence of this field, it defaults to "ImplementationDefault".

Support: Extended

Default: { denominator:100 numerator:100 }

Validations:
Optional

SamplingRate is the sampling rate to apply when parent-based sampling is active.

This acts as a downsampling governor. It allows an operator to say: "I want to respect the parent’s decision, but only for 50% of those requests". Even if a parent is already marked as "Sampled", this allows the Gateway to apply a secondary filter so that it can respect the parent’s intent while still controlling the volume of spans reported.

In the absence of this field, it defaults to 100% ({numerator: 100}).

Support: Extended

Validations:
Maximum: 1e+06
Minimum: 1
Optional

Count specifies the number of requests per time interval.

Support: Extended

Validations:
Optional

Interval specifies the divisor of the rate of requests, the amount of time during which the given count of requests occur.

Support: Extended

Default: { interval:10s percent:20 }

Validations:
Optional

Budget holds the details of the retry budget configuration.

Default: { count:10 interval:1s }

Validations:
Optional

MinRetryRate defines the minimum rate of retries that will be allowable over a specified duration of time.

The effective overall minimum rate of retries targeting the backend service may be much higher, as there can be any number of clients which are applying this setting locally.

This ensures that requests can still be retried during periods of low traffic, where the budget for retries may be calculated as a very low value.

Support: Extended

Validations:
MaxItems: 16
MinItems: 1
Required

TargetRefs identifies the gateways to which this policy applies (GEP-713).

When configured, the telemetry settings defined in this policy are applied uniformly to the referenced resources. In the absence of targetRefs, the policy is invalid and will not be accepted.

TargetRefs must be distinct.

Support: Core for Gateway

Validations:
Optional

Tracing defines the configuration for distributed tracing.

When configured, distributed tracing spans are generated and exported. In the absence of this configuration, tracing behavior is determined by implementation defaults.

Support: Extended

Feature Name: TelemetryPolicyTracing

Validations:
MaxItems: 16
Required

For Policy Status API conventions, see: https://gateway-api.sigs.k8s.io/geps/gep-713/#the-status-stanza-of-policy-objects

Ancestors is a list of ancestor resources (specifically Gateway resources) that are associated with the policy, and the status of the policy with respect to each ancestor. When this policy attaches to a parent, the controller that manages the parent and the ancestors MUST add an entry to this list when the controller first sees the policy and SHOULD update the entry as appropriate when the relevant ancestor is modified.

For TelemetryPolicy, the ancestor MUST be the Gateway resource referenced in spec.targetRefs.

Note also that implementations MUST ONLY populate ancestor status for the Ancestor resources they are responsible for. Implementations MUST use the ControllerName field to uniquely identify the entries in this list that they are responsible for.

Note that to achieve this, the list of PolicyAncestorStatus structs MUST be treated as a map with a composite key, made up of the AncestorRef and ControllerName fields combined.

A maximum of 16 ancestors will be represented in this list. An empty list means the Policy is not relevant for any ancestors.

If this slice is full, implementations MUST NOT add further entries. Instead they MUST consider the policy unimplementable and signal that on any related resources such as the ancestor that would be referenced here.

Default: ImplementationDefault

Validations:
Enum: [Enabled Disabled ImplementationDefault]
Optional

Mode explicitly controls if tracing is enabled. Valid values are "Enabled", "Disabled", "ImplementationDefault".

In the absence of this field, it defaults to "ImplementationDefault".

Support: Core (within TelemetryPolicy feature)

Validations:
Optional

Provider specifies the tracing collector or backend endpoint receiving OTLP spans.

When configured, spans generated by the Gateway proxy are exported to this destination. In the absence of this field, spans are exported to an implementation-defined default sink.

Support: Core (within Tracing feature)

Validations:
Optional

SamplingRate specifies the base probability of sampling new traces.

The sampling probability is represented as a fraction.

For example, a Numerator of 5 and Denominator of 100 represents a 5% sampling rate.

• If configured, only the specified percentage of new traces will be initiated.
• In the absence of this field, an implementation-defined default is used.

Support: Extended

Validations:
Optional

ParentBasedSampling configures whether to respect the sampling decision of the parent span.

• When Mode is "Enabled", the proxy will respect the upstream trace parent’s sampling decision.
• When Mode is "Disabled" or absent, the proxy applies its own local sampling rate decision.

Support: Extended

Feature Name: TelemetryPolicyParentBasedSampling

Validations:
MaxLength: 253
MinLength: 1
Pattern: ^(\*\.)?[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
Optional

ServiceName is the "service.name" attribute of the OpenTelemetry resource. If absent, the implementation’s default service name will be used.

Support: Extended

Validations:
MaxLength: 256
MinLength: 1
Optional

SpanName defines a custom name for the OTel span. By default, the name is implementation-specific.

Support: Extended

Validations:
Optional

Attributes is a list of custom key-value pairs (or variables) attached to every span.

When configured, these attributes are injected into every generated tracing span. In the absence of attributes, only standard proxy-defined attributes are emitted.

Support: Extended

Validations:
Required

BackendRef is a reference to a Kubernetes Service or other supported backend that receives OTLP traces.

When configured, tracing data is exported to the referenced backend. If the reference is invalid (e.g., the Service does not exist), the implementation should update the policy’s status conditions to indicate an unresolved reference.

TLS configuration for the connection to the backend is managed by the referenced object. For example, if the BackendRef points to a Service, a BackendTLSPolicy can be attached to configure TLS. Alternatively, the referenced backend could be a custom resource (e.g., XBackend) that natively manages TLS.

Support: Core

Validations:
MaxItems: 16
Optional

Headers specifies a list of custom headers to be added to the telemetry export requests (e.g., for authentication).

Support: Extended

Validations:
Optional

Validations:
Required

Spec defines the desired state of XBackend.

Validations:
Optional

Status defines the current state of XBackend.

Validations:
Optional

Validations:
Required

Spec defines the desired state of BackendTrafficPolicy.

Validations:
Optional

Status defines the current state of BackendTrafficPolicy.

Validations:
Optional

Validations:
Required

Spec defines the desired state of XMesh.

Default: { conditions:[map[lastTransitionTime:1970-01-01T00:00:00Z message:Waiting for controller reason:Pending status:Unknown type:Accepted]] }

Validations:
Optional

Status defines the current state of XMesh.

Validations:
Optional

Validations:
AtLeastOneOf: [tracing]
Required

Spec defines the desired state of TelemetryPolicy.

Validations:
Optional

Status defines the observed state of TelemetryPolicy.