XBackend

gateway.networking.x-k8s.io/v1alpha1

Gateway API Versionv1.6.2

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.

Warning

XBackend is an experimental Gateway API resource (API group gateway.networking.x-k8s.io).
Experimental resources may change in backwards incompatible ways or be removed entirely in future Gateway API releases.

​
---
config:
  theme: base
  themeVariables:
    secondaryColor: '#ffffff'
---
block
  columns 7

  classDef al_space_box fill:#00000000,stroke:#00000000;
  classDef al_ref_box fill:#F2F2F2,stroke:#555;
  classDef al_mgw_box fill:#70991F,stroke:#555;
  classDef al_gwapi_box fill:#326CE5,stroke:#555;
  classDef al_std_box fill:#808B8F,stroke:#555;
  classDef al_self_box fill:#326CE5,stroke:#777,stroke-width:5px; 

  
  
  block:RefBy:1
    columns 1
    HTTPRoute["<a href='../../../gateway-api/http-route/v1/'>&nbsp;&nbsp;HTTPRoute&nbsp;&nbsp;</a>"]
    ReferenceGrant["<a href='../../../gateway-api/reference-grant/v1/'>&nbsp;&nbsp;ReferenceGrant&nbsp;&nbsp;</a>"]
    class HTTPRoute,ReferenceGrant al_gwapi_box
  end
  class RefBy al_ref_box
  space:2
  
  
  XBackend["<a href='../../../gateway-api/x-backend/v1alpha1/'>&nbsp;&nbsp;<b>XBackend</b>&nbsp;&nbsp;</a>"]
  class XBackend al_self_box
  
  space:2
  block:Space0:1
    space
  end
  class Space0 al_space_box
  

  RefBy -- "&nbsp<i>references</i>&nbsp" --> XBackend
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

apiVersion: gateway.networking.x-k8s.io/v1alpha1
kind: XBackend
metadata:
  name: backend-example
spec:
  type: ExternalHostname
  externalHostname:
    hostname: backend.example.com
  port:
    port: 443
  protocol: HTTP
  tls:
    mode: ServerOnly
    validation:
      hostname: backend.example.com
      caCertificateRefs:
        - group: ""
          kind: ConfigMap
          name: example-ca

XBackend

Field Description Type Required Default Allowed Values
metadata defines the resource’s metadata ObjectMeta yes
spec defines the desired state of XBackend. object yes
status defines the current state of XBackend. object no

XBackend.spec

Field Description Type Required Default Allowed Values
externalHostname specifies the configuration for an ExternalHostname backend. This field must be set when type is ExternalHostname and must be unset otherwise. object no
port defines the port that the implementation should use when connecting to this backend. object yes
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.		 enum no H2C, HTTP11, HTTP2, HTTP
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.		 object no
type defines the backend type. enum yes ExternalHostname

XBackend.spec.externalHostname

Field Description Type Required Default Allowed Values
hostname specifies the FQDN used to reach this backend.
IP addresses are not allowed in this field.		 string yes

XBackend.spec.port

Field Description Type Required Default Allowed Values
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). string no
port represents the port number of the endpoint. int32 yes [1, 65535]

XBackend.spec.tls

Field Description Type Required Default Allowed Values
clientCertificateRef

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.

Supported kinds: Secret

object no
mode defines the TLS mode for the backend connection. enum yes ClientAndServer, None, ServerOnly
validation contains TLS validation configuration for the backend connection. object no

XBackend.spec.tls.clientCertificateRef

Field Description Type Required Default Allowed Values
group

Group is the group of the referent. For example, “gateway.networking.k8s.io”.
When unspecified or empty string, core API group is inferred.

Supported groups: ""

string no ""
kind

Kind is kind of the referent. For example “Secret”.

Supported kinds: Secret

string no Secret
name is the name of the referent. string yes
namespace is the namespace of the referenced object. When unspecified, the local namespace is inferred.

Note that when a namespace different than the local namespace is specified, a ReferenceGrant object is required in the referent namespace to allow that namespace’s owner to accept the reference. See the ReferenceGrant documentation for details.		 string no

XBackend.spec.tls.validation

Field Description Type Required Default Allowed Values
caCertificateRefs

CACertificateRefs contains one or more references to Kubernetes objects that contain a PEM-encoded TLS CA certificate bundle, which is used to validate a TLS handshake between the Gateway and backend Pod.

If CACertificateRefs is empty or unspecified, then WellKnownCACertificates must be specified. Only one of CACertificateRefs or WellKnownCACertificates may be specified, not both. If CACertificateRefs is empty or unspecified, the configuration for WellKnownCACertificates MUST be honored instead if supported by the implementation.

A CACertificateRef is invalid if:

  • It refers to a resource that cannot be resolved (e.g., the referenced resource does not exist) or is misconfigured (e.g., a ConfigMap does not contain a key named ca.crt). In this case, the Reason must be set to InvalidCACertificateRef and the Message of the Condition must indicate which reference is invalid and why.
  • It refers to an unknown or unsupported kind of resource. In this case, the Reason must be set to InvalidKind and the Message of the Condition must explain which kind of resource is unknown or unsupported.
  • It refers to a resource in another namespace. This may change in future spec updates.
Implementations MAY choose to perform further validation of the certificate content (e.g., checking expiry or enforcing specific formats).

Note: Airlock Microgateway performs the following additional validations:
  • Each referenced Secret or ConfigMap must contain CA certificate(s) in PEM format.
In all cases, the implementation MUST ensure the ResolvedRefs Condition on the BackendTLSPolicy is set to status: False, with a Reason and Message that indicate the cause of the error. Connections using an invalid CACertificateRef MUST fail, and the client MUST receive an HTTP 5xx error response. If ALL CACertificateRefs are invalid, the implementation MUST also ensure the Accepted Condition on the BackendTLSPolicy is set to status: False, with a Reason NoValidCACertificate.

A single CACertificateRef to a Kubernetes ConfigMap kind has “Core” support.
Implementations MAY choose to support attaching multiple certificates to a backend, but this behavior is implementation-specific.

Note: Airlock Microgateway supports multiple references and each reference may include multiple concatenated certificates separated with newlines within the ca.crt key.

Supported kinds: ConfigMap, Secret

object[] no
hostname is used for two purposes in the connection between Gateways and backends:
  1. Hostname MUST be used as the SNI to connect to the backend (RFC 6066).
  2. Hostname MUST be used for authentication and MUST match the certificate served by the matching backend, unless SubjectAltNames is specified.
  3. If SubjectAltNames are specified, Hostname can be used for certificate selection but MUST NOT be used for authentication. If you want to use the value of the Hostname field for authentication, you MUST add it to the SubjectAltNames list.
string yes
subjectAltNames contains one or more Subject Alternative Names.
When specified the certificate served from the backend MUST have at least one Subject Alternate Name matching one of the specified SubjectAltNames.		 object[] no
wellKnownCACertificates

WellKnownCACertificates specifies whether a well-known set of CA certificates may be used in the TLS handshake between the gateway and backend pod.

If WellKnownCACertificates is unspecified or empty (""), then CACertificateRefs must be specified with at least one entry for a valid configuration. Only one of CACertificateRefs or WellKnownCACertificates may be specified, not both.
If an implementation does not support the WellKnownCACertificates field, or the supplied value is not recognized, the implementation MUST ensure the Accepted Condition on the BackendTLSPolicy is set to status: False, with a Reason Invalid.

Valid values include:

  • “System” - indicates that well-known system CA certificates should be used.
Implementations MAY define their own sets of CA certificates. Such definitions MUST use an implementation-specific, prefixed name, such as mycompany.com/my-custom-ca-certificates.

Supported values:

  • System: indicates that well known system CA certificates should be used.
  • microgateway.airlock.com/openShiftServiceCA: indicates that well known service ca certificates from OpenShift should be used. Only applicable on OpenShift clusters.

string no

XBackend.spec.tls.validation.caCertificateRefs[]

Field Description Type Required Default Allowed Values
group

Group is the group of the referent. For example, “gateway.networking.k8s.io”.
When unspecified or empty string, core API group is inferred.

Supported groups: ""

string yes
kind

Kind is kind of the referent. For example “HTTPRoute” or “Service”.

Supported kinds: ConfigMap, Secret

string yes
name is the name of the referent. string yes

XBackend.spec.tls.validation.subjectAltNames[]

Field Description Type Required Default Allowed Values
hostname contains Subject Alternative Name specified in DNS name format.
Required when Type is set to Hostname, ignored otherwise.		 string no
type determines the format of the Subject Alternative Name. Always required. enum yes Hostname, URI
uri contains Subject Alternative Name specified in a full URI format.
It MUST include both a scheme (e.g., “http” or “ftp”) and a scheme-specific-part.
Common values include SPIFFE IDs like “spiffe://mycluster.example.com/ns/myns/sa/svc1sa”.
Required when Type is set to URI, ignored otherwise.		 string no

XBackend.status

Field Description Type
parents 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.		 object[]

XBackend.status.parents[]

Field Description Type
conditions 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.		 Condition[]
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).		 string
parentRef AncestorRef identifies the parent resource that this status is associated with. object

XBackend.status.parents[].parentRef

Field Description Type
group is the group of the referent.
When unspecified, “gateway.networking.k8s.io” is inferred.
To set the core API group (such as for a “Service” kind referent), Group must be explicitly set to "" (empty string).		 string
kind is kind of the referent.

There are two kinds of parent resources with “Core” support:
Support for other resources is Implementation-Specific.		 string
name is the name of the referent. string
namespace is the namespace of the referent. When unspecified, this refers to the local namespace of the Route.

Note that there are specific rules for ParentRefs which cross namespace boundaries. Cross-namespace references are only valid if they are explicitly allowed by something in the namespace they are referring to. For example:
Gateway has the AllowedRoutes field, and ReferenceGrant provides a generic way to enable any other kind of cross-namespace reference.
Note: This section only applies to the Gateway API experimental channel

ParentRefs from a Route to a Service in the same namespace are “producer” routes, which apply default routing rules to inbound connections from any namespace to the Service.

ParentRefs from a Route to a Service in a different namespace are “consumer” routes, and these routing rules are only applied to outbound connections originating from the same namespace as the Route, for which the intended destination of the connections are a Service targeted as a ParentRef of the Route.
string
port is the network port this Route targets. It can be interpreted differently based on the type of parent resource.

When the parent resource is a Gateway, this targets all listeners listening on the specified port that also support this kind of Route(and select this Route). It’s not recommended to set Port unless the networking behaviors specified in a Route must apply to a specific port as opposed to a listener(s) whose port(s) may be changed. When both Port and SectionName are specified, the name and port of the selected listener must match both specified values.
Note: This section only applies to the Gateway API experimental channel

When the parent resource is a Service, this targets a specific port in the Service spec. When both Port (experimental) and SectionName are specified, the name and port of the selected port must match both specified values.
Implementations MAY choose to support other parent resources.
Implementations supporting other types of parent resources MUST clearly document how/if Port is interpreted.

For the purpose of status, an attachment is considered successful as long as the parent resource accepts it partially. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway.		 int32
sectionName is the name of a section within the target resource. In the following resources, SectionName is interpreted as the following:
  • Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values.
  • Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values.
Implementations MAY choose to support attaching Routes to other resources.
If that is the case, they MUST clearly document how SectionName is interpreted.

When unspecified (empty string), this will reference the entire resource.
For the purpose of status, an attachment is considered successful if at least one section in the parent resource accepts it. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway.		 string