Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add new BackendTLSPolicy configuration options to documentation #3563

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add new BackendTLSPolicy configuration options to documentation #3563

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 40 additions & 2 deletions site-src/api-types/backendtlspolicy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,16 @@ 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 enables specification of client certificates that the Gateway should use when establishing TLS connections with backends. The configuration includes:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To clarify, if this field is set, then ALL connections from Gateway to backend will require certificate verification?

And specifying a BackendTLSPolicy for a Service should use that configuration instead of the Gateway BackendTLS certificate?


- [BackendTLS][backendTLS] - Defines the TLS configuration for Gateway-to-backend connections
- [ClientCertificateRef][clientCertificateRef] - References an object containing a Client Certificate and its associated private key

## Spec

The specification of a [BackendTLSPolicy][backendtlspolicy] consists of:
Expand All @@ -36,19 +46,21 @@ 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.
- [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 each implementation, similar to the TLS options field on Gateway Listeners.

The following chart outlines the object definitions and relationship:
```mermaid
flowchart LR
backendTLSPolicy[["<b>backendTLSPolicy</b> <hr><align=left>BackendTLSPolicySpec: spec<br>PolicyStatus: status</align>"]]
spec[["<b>spec</b><hr>PolicyTargetReferenceWithSectionName: targetRefs <br> BackendTLSPolicyValidation: tls"]]
spec[["<b>spec</b><hr>PolicyTargetReferenceWithSectionName: targetRefs <br> BackendTLSPolicyValidation: tls<br>map[string]string: options"]]
status[["<b>status</b><hr>[ ]PolicyAncestorStatus: ancestors"]]
validation[["<b>tls</b><hr>LocalObjectReference: caCertificateRefs<br>wellKnownCACertificatesType: wellKnownCACertificates/<br>PreciseHostname: hostname"]]
validation[["<b>tls</b><hr>LocalObjectReference: caCertificateRefs<br>wellKnownCACertificatesType: wellKnownCACertificates/<br>PreciseHostname: hostname<br>[]SubjectAltName: subjectAltNames"]]
ancestorStatus[["<b>ancestors</b><hr>AncestorRef: parentReference<br>GatewayController: controllerName<br>[]Condition: conditions"]]
targetRefs[[<b>targetRefs</b><hr>]]
service["<b>service</>"]
Expand Down Expand Up @@ -111,6 +123,30 @@ 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 separation between the SNI (specified by hostname) and certificate identity validation. When 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 can be of two types:

- 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, similar to the TLS options field on Gateway Listeners. This can include:

- Vendor-specific mTLS automation configuration
- Minimum supported TLS version restrictions
- Supported cipher suite configurations

Implementation-specific definitions must use domain-prefixed names (e.g., example.com/my-custom-option) to avoid ambiguity. Un-prefixed names are reserved for key names defined by Gateway API.

#### Certificates

The BackendTLSPolicyValidation must contain a certificate reference of some kind, and contains two ways to configure the
Expand Down Expand Up @@ -146,3 +182,5 @@ uses `PolicyAncestorStatus` to allow you to know which parentReference set that
[hostname]: /references/spec/#gateway.networking.k8s.io/v1.PreciseHostname
[rfc-3986]: https://tools.ietf.org/html/rfc3986
[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