API Reference

gateway.networking.x-k8s.io/v1alpha1

Package v1alpha1 contains API Schema definitions for the gateway.networking.k8s-x.io API group.

Resource Types

BackendAncestorStatus

BackendAncestorStatus describes the status of a Backend with respect to a specific parent resource (typically a Gateway).

Appears in:

Field Description Default Validation
controllerName GatewayController 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).
parentRef ParentReference AncestorRef identifies the parent resource that this status is associated with.
conditions Condition array 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 accepteed by the controller
The status of each condition is one of True, False, or Unknown.

BackendPort

BackendPort describes the port the implementation should use when connecting to a Backend. Inspired by discoveryv1.EndpointPort.

Appears in:

Field Description Default Validation
name string Name represents the name of this port. All ports in a Backend must have
a unique name. Name must either be an empty string or pass DNS_LABEL
validation (lowercase alphanumeric or ‘-’, starting and ending with an
alphanumeric character, at most 63 characters).		 MaxLength: 63
port PortNumber Port represents the port number of the endpoint. Maximum: 65535
Minimum: 1

BackendProtocol

Underlying type: string

BackendProtocol defines the protocol used when connecting to a backend.

Validation:

  • Enum: [TCP HTTP HTTP2 HTTP11 H2C MCP]

Appears in:

Field Description
MCP BackendProtocolMCP indicates the Model Context Protocol.
Support: Extended
TCP BackendProtocolTCP indicates plain TCP.
Support: Extended
HTTP BackendProtocolHTTP indicates HTTP (version negotiated via ALPN or
implementation default).
Support: Core
HTTP2 BackendProtocolHTTP2 indicates HTTP/2.
Support: Core
HTTP11 BackendProtocolHTTP11 indicates HTTP/1.1.
Support: Core
H2C BackendProtocolH2C indicates HTTP/2 over cleartext (h2c).
Support: Core
GRPC BackendProtocolGRPC indicates gRPC
Support: Extended

BackendSpec

BackendSpec defines the desired state of a Backend.

Appears in:

Field Description Default Validation
type BackendType Type defines the backend type. Enum: [ExternalHostname]
port BackendPort Port defines the port that the implementation should use when connecting
to this backend.
externalHostname ExternalHostnameBackend ExternalHostname specifies the configuration for an ExternalHostname
backend. This field must be set when type is ExternalHostname and must
be unset otherwise.
Support: Extended
protocol BackendProtocol 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
 Enum: [TCP HTTP HTTP2 HTTP11 H2C MCP]
tls BackendTLS 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: Extended

BackendStatus

BackendStatus defines the observed state of a Backend.

Appears in:

Field Description Default Validation
parents BackendAncestorStatus array Ancestors is a list of parent resources associated with this Backend,
and the status of the Backend with respect to each parent.
A maximum of 32 parents will be represented in this list. An empty list
indicates that the Backend is not associated with any parents.
 MaxItems: 32

BackendTLS

BackendTLS defines TLS configuration for connecting to a backend.

Appears in:

Field Description Default Validation
mode BackendTLSMode Mode defines the TLS mode for the backend connection. Enum: [None ServerOnly ClientAndServer]
clientCertificateRef SecretObjectReference 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.
validation BackendTLSPolicyValidation Validation contains TLS validation configuration for the backend connection.

BackendTLSMode

Underlying type: string

BackendTLSMode defines the TLS mode for backend connections.

Validation:

  • Enum: [None ServerOnly ClientAndServer]

Appears in:

Field Description
None BackendTLSModeNone disables TLS when connecting to the backend.
ServerOnly BackendTLSModeServerOnly enables TLS with server certificate verification.
ClientAndServer BackendTLSModeClientAndServer enables mutual TLS (mTLS).

BackendTrafficPolicySpec

BackendTrafficPolicySpec define the desired state of BackendTrafficPolicy Note: there is no Override or Default policy configuration.

Appears in:

Field Description Default Validation
targetRefs LocalPolicyTargetReference array 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.		 MaxItems: 16
MinItems: 1
retryConstraint RetryConstraint
:warning: Experimental		 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
sessionPersistence SessionPersistence SessionPersistence defines and configures session persistence
for the backend.
Support: Extended

BackendType

Underlying type: string

BackendType defines the type of backend destination.

Validation:

  • Enum: [ExternalHostname]

Appears in:

Field Description
ExternalHostname BackendTypeExternalHostname indicates that the backend is an external
hostname destination. This type provides first-class support for external
FQDNs, replacing the need for synthetic ExternalName Services.
Support: Extended

BudgetDetails

BudgetDetails specifies the details of the budget configuration, like the percentage of requests in the budget, and the interval between checks.

Appears in:

Field Description Default Validation
percent integer Percent defines the maximum percentage of active requests that may
be made up of retries.
Support: Extended		 20 Maximum: 100
Minimum: 0
interval Duration Interval defines the duration in which requests will be considered
for calculating the budget for retries.
Support: Extended		 10s

ExternalHostnameBackend

ExternalHostnameBackend specifies the configuration for a backend that represents an external hostname destination.

Appears in:

Field Description Default Validation
hostname PreciseHostname Hostname specifies the FQDN used to reach this backend.
IP addresses are not allowed in this field.

MeshSpec

MeshSpec defines the desired state of an XMesh.

Appears in:

Field Description Default Validation
controllerName GatewayController 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
parametersRef ParametersReference 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
description string Description optionally provides a human-readable description of a Mesh. MaxLength: 64

MeshStatus

MeshStatus is the current status for the Mesh.

Appears in:

Field Description Default Validation
conditions Condition array 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.		 [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]] MaxItems: 8
supportedFeatures SupportedFeature array SupportedFeatures is the set of features the Mesh support.
It MUST be sorted in ascending alphabetical order by the Name key.		 MaxItems: 64

PortNumber

Underlying type: integer

PortNumber defines a network port.

Validation:

  • Maximum: 65535
  • Minimum: 1

Appears in:

RequestRate

RequestRate expresses a rate of requests over a given period of time.

Appears in:

Field Description Default Validation
count integer Count specifies the number of requests per time interval.
Support: Extended		 Maximum: 1e+06
Minimum: 1
interval Duration Interval specifies the divisor of the rate of requests, the amount of
time during which the given count of requests occur.
Support: Extended

RetryConstraint

RetryConstraint defines the configuration for when to retry a request.

Appears in:

Field Description Default Validation
budget BudgetDetails Budget holds the details of the retry budget configuration. { interval:10s percent:20 }
minRetryRate RequestRate 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		 { count:10 interval:1s }

XBackend

XBackend is a Gateway API resource that represents a backend destination for routing traffic. It serves as a Gateway-native way to define where and how a Gateway should connect to a backend.

Support: Extended

Field Description Default Validation
apiVersion string gateway.networking.x-k8s.io/v1alpha1
kind string XBackend
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec BackendSpec Spec defines the desired state of XBackend.
status BackendStatus Status defines the current state of XBackend.

XBackendTrafficPolicy

XBackendTrafficPolicy defines the configuration for how traffic to a target backend should be handled.

Field Description Default Validation
apiVersion string gateway.networking.x-k8s.io/v1alpha1
kind string XBackendTrafficPolicy
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec BackendTrafficPolicySpec Spec defines the desired state of BackendTrafficPolicy.
status PolicyStatus Status defines the current state of BackendTrafficPolicy.

XMesh

XMesh defines mesh-wide characteristics of a GAMMA-compliant service mesh.

Field Description Default Validation
apiVersion string gateway.networking.x-k8s.io/v1alpha1
kind string XMesh
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec MeshSpec Spec defines the desired state of XMesh.
status MeshStatus Status defines the current state of XMesh.
 { conditions:[map[lastTransitionTime:1970-01-01T00:00:00Z message:Waiting for controller reason:Pending status:Unknown type:Accepted]] }