Skip to content

Add new BackendTLSPolicy configuration options to documentation #3563

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+41 −3
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
44 changes: 41 additions & 3 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
Copy link
Contributor

@candita candita Jul 21, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

@08volt This actually belongs under the Gateway "API Types" reference more than the BackendTLSPolicy "API Types" reference. If you decide to keep it in both places, make sure to point out that this Gateway field can be overriden by any BackendTLSPolicy in effect. See https://github.com/kubernetes-sigs/gateway-api/blob/main/apis/v1/gateway_types.go#L507


??? 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?

Copy link
Contributor

@candita candita Jul 21, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

@08volt can you answer question 1? Question 2 is answered by https://github.com/kubernetes-sigs/gateway-api/blob/main/apis/v1/gateway_types.go#L507 as noted in https://github.com/kubernetes-sigs/gateway-api/pull/3563/files#r2219923354

Also:

Suggested change
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:
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 may use when establishing TLS connections with backends. The configuration includes:


- [BackendTLS][backendTLS] - Defines the TLS configuration for Gateway-to-backend connections
Copy link
Contributor

Choose a reason for hiding this comment

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

nit: Since the only field in backendTLS is clientCertificateRef then I don't think we need to list them both as separate objects.

- [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.
Copy link
Contributor

Choose a reason for hiding this comment

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

It's worth mentioning:

Suggested change
- [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.
- [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 each implementation, similar to the TLS options field on Gateway Listeners.
Copy link
Contributor

Choose a reason for hiding this comment

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

Don't include Options unless you specify that this is completely implementation-dependent and users have to consult their implementation's documentation to use this. Don't compare it to TLS options on the Gateway Listeners, that could be confusing.

Suggested change
- [Options][options] - A map of key/value pairs enabling extended TLS configuration for each implementation, similar to the TLS options field on Gateway Listeners.
- [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
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"]]
Copy link
Contributor

Choose a reason for hiding this comment

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

I'd prefer to not add options, since it is an implementation-dependent field not available in all implementations.

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"]]
Copy link
Contributor

Choose a reason for hiding this comment

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

Could you also fix this typo while you're here? Thanks!

Suggested change
validation[["<b>tls</b><hr>LocalObjectReference: caCertificateRefs<br>wellKnownCACertificatesType: wellKnownCACertificates/<br>PreciseHostname: hostname<br>[]SubjectAltName: subjectAltNames"]]
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.
Copy link
Contributor

@candita candita Jul 21, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Can you clarify here what this means: "enable separation between the SNI ... and certificate identity validation"?
According to GEP-3155, the reason SAN was added was for basic mutual TLS configuration between Gateways and Backends, and to enable the optional use of SPIFFE for Backend mutual TLS. So it would be a good idea to mention both use cases.

Suggested change
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.
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 can be of two types:
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
Subject Alternative Names can be of two types:
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, similar to the TLS options field on Gateway Listeners. This can include:
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
The options field allows specification of implementation-specific TLS configurations, similar to the TLS options field on Gateway Listeners. This can include:
The options field allows specification of implementation-specific TLS configurations. This can include:


- Vendor-specific mTLS automation configuration
Copy link
Contributor

Choose a reason for hiding this comment

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

Spell out mutual TLS here and elsewhere:

Suggested change
- Vendor-specific mTLS automation configuration
- Vendor-specific mutual TLS 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.
Copy link
Contributor

Choose a reason for hiding this comment

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

The average user doesn't need to know this, it's an implementation detail. But you can say:

Suggested change
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.
Check your implementation documentation for details.


#### Certificates

The BackendTLSPolicyValidation must contain a certificate reference of some kind, and contains two ways to configure the
Expand Down Expand Up @@ -145,4 +181,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