Identity
| |
|---|
| Group | gateway.networking.k8s.io |
| Version | v1 |
| Kind | BackendTLSPolicy |
| Scope | Project |
Overview
A BackendTLSPolicy configures how a Gateway establishes a TLS connection to the backend it routes traffic to. It lets you secure the “last mile” between the Gateway and a backend Service by specifying which CA certificates to trust and which hostname the backend’s certificate must match.
Use it when you want traffic between the Gateway and your backend to be encrypted and authenticated — for example, connecting to a backend that serves its own TLS certificate. Each policy attaches to one or more target resources (typically a Service) through spec.targetRefs.
Spec fields
| Field | Type | Required | Description |
|---|
spec.targetRefs | []Object | Yes | Identifies the resources this policy applies to. Target references must be distinct by the combined group, kind, and name (or by sectionName within the same target). Services have Extended support; other kinds are implementation-specific. |
spec.targetRefs[].group | string | Yes | Group of the target resource. |
spec.targetRefs[].kind | string | Yes | Kind of the target resource. |
spec.targetRefs[].name | string | Yes | Name of the target resource. |
spec.targetRefs[].sectionName | string | No | Name of a section within the target (a Service port, a Gateway listener, or an HTTPRoute rule). When unset, the policy targets the entire resource. |
spec.validation | Object | Yes | Backend TLS validation configuration (see fields below). |
spec.validation.hostname | string | Yes | Hostname used as the SNI to connect to the backend and, unless subjectAltNames is set, to authenticate the certificate the backend serves. |
spec.validation.caCertificateRefs | []Object | No | One or more references to objects holding a PEM-encoded CA certificate bundle used to validate the TLS handshake with the backend. Exactly one of caCertificateRefs or wellKnownCACertificates must be set. |
spec.validation.subjectAltNames | []Object | No | One or more Subject Alternative Names; when set, the backend certificate must match at least one of them. |
spec.validation.wellKnownCACertificates | string | No | Set to System to allow system CA certificates in the handshake. Mutually exclusive with caCertificateRefs. |
spec.options | map[string]string | No | Key/value pairs enabling implementation-specific extended TLS configuration, such as a minimum TLS version or cipher suites. Implementation-specific keys must be domain-prefixed (e.g. example.com/my-custom-option). |
Status fields (read-only)
| Field | Type | Description |
|---|
status.ancestors | []Object | The ancestor resources (usually Gateways) associated with this policy, and the policy’s status with respect to each. A maximum of 16 ancestors is tracked; an empty list means the policy is not relevant to any ancestor. |
status.ancestors[].ancestorRef | Object | The parent reference this status entry describes. |
status.ancestors[].conditions | []Object | Tracks state such as Accepted and ResolvedRefs for the policy relative to the ancestor. |
status.ancestors[].controllerName | string | The controller that wrote this status entry, in domain/path form. |
Usage
apiVersion: gateway.networking.k8s.io/v1
kind: BackendTLSPolicy
metadata:
name: secure-backend
spec:
targetRefs:
- group: ""
kind: Service
name: my-backend
validation:
hostname: backend.example.com
wellKnownCACertificates: System
datumctl apply -f backendtlspolicy.yaml --project my-project
datumctl get backendtlspolicies --project my-project
datumctl describe backendtlspolicy secure-backend --project my-project
Run datumctl explain backendtlspolicies --recursive to see the full, live field tree for this resource.
