Add new BackendTLSPolicy configuration options to documentation #3563
Conversation
k8s-ci-robot
added
release-note-none
08volt
changed the title
k8s-ci-robot
added
the
cncf-cla: yes
|
Welcome @08volt! |
k8s-ci-robot
added
size/M
|
Hi @08volt. Thanks for your PR. I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: 08volt, robscott The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
k8s-ci-robot
added
the
approved
|
/ok-to-test |
k8s-ci-robot
added
ok-to-test
k8s-ci-robot
added
the
needs-rebase
| @@ -28,6 +28,12 @@ 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 | |||
| 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: | |||
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
@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:
| 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: |
08volt
force-pushed
the
doc-combine
branch
2 times, most recently
from
be9a8dc to
f1b863d
Compare
k8s-ci-robot
removed
the
needs-rebase
|
The Kubernetes project currently lacks enough contributors to adequately respond to all PRs. This bot triages PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /lifecycle stale |
k8s-ci-robot
added
lifecycle/stale
|
cc @candita Could you take a look here please and let us know your thoughts? |
shaneutt
added
the
v1.4-release/subtask
- Gateway backendTLS field - subjectAltNames field - options field The documentation includes descriptions of each new field along with their purpose, usage constraints and reference links.
k8s-ci-robot
removed
the
needs-rebase
| @@ -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 | |||
There was a problem hiding this comment.
@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
| 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: | ||
|
|
||
| - [BackendTLS][backendTLS] - Defines the TLS configuration for Gateway-to-backend connections |
There was a problem hiding this comment.
nit: Since the only field in backendTLS is clientCertificateRef then I don't think we need to list them both as separate objects.
| @@ -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. | |||
There was a problem hiding this comment.
It's worth mentioning:
| - [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. |
There was a problem hiding this comment.
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.
| - [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"]] |
There was a problem hiding this comment.
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"]] |
There was a problem hiding this comment.
Could you also fix this typo while you're here? Thanks!
| 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"]] |
| ??? 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. |
There was a problem hiding this comment.
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.
| 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. |
|
|
||
| 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: |
There was a problem hiding this comment.
| 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). |
| ??? 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: |
There was a problem hiding this comment.
| 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: |
| 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 |
There was a problem hiding this comment.
Spell out mutual TLS here and elsewhere:
| - 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. |
There was a problem hiding this comment.
The average user doesn't need to know this, it's an implementation detail. But you can say:
| 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. |
/kind documentation
What this PR does / why we need it:
Updated documentation page regarding BackendTLSPolicy with the following fields:
The documentation includes descriptions of each new field along with their purpose, usage constraints and reference links.
Fixes #
Does this PR introduce a user-facing change?: