diff --git a/site-src/api-types/backendtlspolicy.md b/site-src/api-types/backendtlspolicy.md index ac57bd04ec..ac2db809bc 100644 --- a/site-src/api-types/backendtlspolicy.md +++ b/site-src/api-types/backendtlspolicy.md @@ -28,6 +28,17 @@ to prevent the complications involved with sharing trust across namespace bounda All Gateway API Routes that point to a referenced Service should respect a configured BackendTLSPolicy. +## Gateway Backend TLS Configuration + +??? example "Experimental Channel since v1.1.0" + + These fields were added to Gateway in `v1.1.0` +The Gateway specification now includes a new backendTLS field that allows configuration of TLS settings when the Gateway connects to backends. This provides a default configuration for all backend Services. It is important to note that if a BackendTLSPolicy is attached to a specific Service, it will override the backendTLS configuration on the Gateway. +This functionality enables the specification of client certificates that the Gateway should use when establishing TLS connections with backends. +The backendTLS configuration consists of a single field: + +- [ClientCertificateRef][clientCertificateRef] - References an object containing a Client Certificate and its associated private key + ## Spec The specification of a [BackendTLSPolicy][backendtlspolicy] consists of: @@ -36,11 +47,13 @@ The specification of a [BackendTLSPolicy][backendtlspolicy] consists of: - [Validation][validation] - Defines the configuration for TLS, including hostname, CACertificateRefs, and WellKnownCACertificates. - [Hostname][hostname] - Defines the Server Name Indication (SNI) that the Gateway uses to connect to the backend. +- [SubjectAltNames][subjectAltNames] - Specifies one or more Subject Alternative Names that the backend certificate must match. When specified, the certificate must have at least one matching SAN. This field enables separation between SNI (hostname) and certificate identity validation. A maximum of 5 SANs are allowed. - [CACertificateRefs][caCertificateRefs] - Defines one or more references to objects that contain PEM-encoded TLS certificates, which are used to establish a TLS handshake between the Gateway and backend Pod. Either CACertificateRefs or WellKnownCACertificates may be specified, but not both. - [WellKnownCACertificates][wellKnownCACertificates] - Specifies whether system CA certificates may be used in the TLS handshake between the Gateway and backend Pod. Either CACertificateRefs or WellKnownCACertificates may be specified, but not both. +- [Options][options] - A map of key/value pairs enabling extended TLS configuration for implementations that choose to provide support. Check your implementation's documentation for details. The following chart outlines the object definitions and relationship: ```mermaid @@ -48,7 +61,7 @@ flowchart LR backendTLSPolicy[["backendTLSPolicy
BackendTLSPolicySpec: spec
PolicyStatus: status"]] spec[["spec
PolicyTargetReferenceWithSectionName: targetRefs
BackendTLSPolicyValidation: tls"]] status[["status
[ ]PolicyAncestorStatus: ancestors"]] - validation[["tls
LocalObjectReference: caCertificateRefs
wellKnownCACertificatesType: wellKnownCACertificates/
PreciseHostname: hostname"]] + validation[["tls
LocalObjectReference: caCertificateRefs
wellKnownCACertificatesType: wellKnownCACertificates
PreciseHostname: hostname
[]SubjectAltName: subjectAltNames"]] ancestorStatus[["ancestors
AncestorRef: parentReference
GatewayController: controllerName
[]Condition: conditions"]] targetRefs[[targetRefs
]] service["service"] @@ -111,6 +124,34 @@ Also note: - Wildcard hostnames are not allowed. +#### Subject Alternative Names + +??? example "Experimental Channel since v1.2.0" + + This field was added to BackendTLSPolicy in `v1.2.0` +The subjectAltNames field enables basic mutual TLS configuration between Gateways and backends, as well as the optional use of SPIFFE. When subjectAltNames is specified, the certificate served by the backend must have at least one Subject Alternative Name matching one of the specified values. This is particularly useful for SPIFFE implementations where URI-based SANs may not be valid SNIs. +Subject Alternative Names may contain one of either a Hostname or URI field, and must contain a Type specifying whether Hostname or URI is chosen. + +!!! info "Restrictions" + + - IP addresses and wildcard hostnames are not allowed. (see the description for Hostname above for more details). + - Hostname: DNS name format + - URI: URI format (e.g., SPIFFE ID) + +#### TLS Options + +??? example "Experimental Channel since v1.2.0" + + This field was added to BackendTLSPolicy in `v1.2.0` +The options field allows specification of implementation-specific TLS configurations. This can include: + +- Vendor-specific mutual TLS automation configuration +- Minimum supported TLS version restrictions +- Supported cipher suite configurations + +Check your implementation documentation for details. + +### #### Certificates The BackendTLSPolicyValidation must contain a certificate reference of some kind, and contains two ways to configure the @@ -145,4 +186,6 @@ uses `PolicyAncestorStatus` to allow you to know which parentReference set that [wellKnownCACertificates]: ../reference/spec.md#gateway.networking.k8s.io/v1alpha3.BackendTLSPolicyValidation.WellKnownCACertificates [hostname]: ../reference/spec.md#gateway.networking.k8s.io/v1.PreciseHostname [rfc-3986]: https://tools.ietf.org/html/rfc3986 -[targetRefs]: ../reference/spec.md#gateway.networking.k8s.io/v1alpha2.PolicyTargetReference +[targetRefs]: ../references/spec/#gateway.networking.k8s.io/v1alpha2.PolicyTargetReference +[subjectAltNames]: ../references/spec/#gateway.networking.k8s.io/v1alpha3.BackendTLSPolicyValidation +[options]: ../references/spec/#gateway.networking.k8s.io/v1alpha3.GatewayTLSConfig