Skip to content

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

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
⚠ 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
sessionPersistence SessionPersistence SessionPersistence defines and configures session persistence
for the backend.
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

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

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 }

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]] }