Skip to content

gep: refine CACertificateRefs description for frontend TLS #4183

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
+50 −21
Open

gep: refine CACertificateRefs description for frontend TLS #4183

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
71 changes: 50 additions & 21 deletions geps/gep-91/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,21 +35,28 @@ This proposal adds the ability to validate the TLS certificate presented by the
These two validation mechanisms operate independently and can be used simultaneously.
* Introduce a `caCertificateRefs` field within `FrontendTLSValidation` that can be used to specify a list of CA Certificates that can be used as a trust anchor to validate the certificates presented by the client.
* Add a new `FrontendValidationModeType` enum within `FrontendTLSValidation` indicating how gateway should validate client certificates. As for now we support following values but it might change in the future:
1) `AllowValidOnly` (Core Support)
2) `AllowInsecureFallback` (Extended Support)
1. `AllowValidOnly` (Core Support)
2. `AllowInsecureFallback` (Extended Support)

`AllowInsecureFallback` mode indicates the gateway will accept connections even if the client certificate is not presented or fails verification.
`AllowInsecureFallback` mode indicates the gateway will accept connections even if the client certificate is not presented or fails verification.
This approach delegates client authorization to the backend and introduce a significant security risk. It should be used in testing environments or
on a temporary basis in non-testing environments.
When `FrontendValidationModeType` is changed from `AllowValidOnly` to `AllowInsecureFallback` the `InsecureFrontendValidationMode` condition MUST be set to `True` with Reason `ConfigurationChanged` on gateway.
This condition remains set to `True` even if `FrontendValidationModeType` is later changed back to `AllowValidOnly`.

* Introduce a `ObjectReference` structure that can be used to specify `caCertificateRefs` references.
* Invalid `caCertificateRefs` directly affect the `ResolvedRefs` and `Accepted` conditions of the targeted listeners.
Copy link
Contributor

@root30 root30 Oct 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Should we also discuss and specify how the Accepted and Programmed Condition of the Gateway are affected

Accepted:

  • if at least one listener is valid
  • all listeners are invalid
  • ...

Programmed:

  • e.g. no Listeners can be programmed due to validation issues (e.g., Mode = AllowValidOnly everywhere and all CA certificates are invalid).
  • ...

Copy link
Member Author

@snorwin snorwin Oct 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

The semantics describing how invalid listeners affect gateway's Accepted condition with the reason ListenersNotValid (https://github.com/kubernetes-sigs/gateway-api/blob/main/apis/v1/gateway_types.go#L1203) are already defined. Therefore, I omitted the indirect influence on the Gateway status here.

The Programmed condition may be affected if the data plane rejects the configuration, e.g., due to an invalid CA certificate. However, such behavior depends on implementation-specific validations performed by the data plane.

Copy link
Contributor

Choose a reason for hiding this comment

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

Is there a listener name or direct reference in this condition?

A listener is considered targeted if and only if it is serving HTTPS and either its port matches the port of the
Copy link
Contributor

Choose a reason for hiding this comment

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

Can you split this entry to default and per port? There are 2 distinct fields and it will be easier to explain which Listeners are impacted

per-port configuration, or it is using the default configuration. This behavior is important to ensure that when all
CA certificates are invalid, listeners do not implicitly fall back to skipping client
certificate verification.

### Impact on listeners

This proposal removes frontendTLSValidation from Listener's TLS configuration and introduces gateways level per port configuration. This is a breaking change for exisitng implementation which uses this feature from Experimental API.
Once gateway level TLS is configured (either by default or for a specific port), the TLS settings will apply to all existing and newly created Listeners serving HTTPS that match the configuration.

#### GO
#### Go

```go
// ObjectReference identifies an API object including its namespace.
Expand Down Expand Up @@ -142,27 +149,47 @@ type TLSPortConfig struct {
// FrontendTLSValidation holds configuration information that can be used to validate
// the frontend initiating the TLS connection
type FrontendTLSValidation struct {
// CACertificateRefs contains one or more references to
// Kubernetes objects that contain TLS certificates of
// the Certificate Authorities that can be used
// as a trust anchor to validate the certificates presented by the client.
// CACertificateRefs contains one or more references to Kubernetes
// objects that contain a PEM-encoded TLS CA certificate bundle, which
// is used as a trust anchor to validate the certificates presented by
// the client.
//
// A CACertificateRef is invalid if:
//
// * It refers to a resource that cannot be resolved (e.g., the
// referenced resource does not exist) or is misconfigured (e.g., a
// ConfigMap does not contain a key named `ca.crt`). In this case, the
Copy link
Contributor

Choose a reason for hiding this comment

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

In the improvement proposal for the backend TLS configuration #4123 you included a section about further validation of the referenced certificate, that should be implementation specific:

  // Implementations MAY choose to perform further validation of the certificate
  // content (e.g., checking expiry or enforcing specific formats). In such cases,
  // an implementation-specific Reason and Message MUST be set.

Should we include a similar section for the CA certificate content (e.g., non-empty, at least one valid PEM-encoded TLS CA certificate bundle, ...)? or should this validation be required?

Copy link
Contributor

Choose a reason for hiding this comment

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

there is an implementation specific behaviour that ConfigMap can contains 'More than one certificate in a ConfigMap with different keys or more than one reference, or other kinds of resources'. Can you include that?

// Reason must be set to `InvalidCACertificateRef` and the Message of
// the Condition must indicate which reference is invalid and why.
//
// A single CA certificate reference to a Kubernetes ConfigMap
// has "Core" support.
// Implementations MAY choose to support attaching multiple CA certificates to
// a Listener, but this behavior is implementation-specific.
// * It refers to an unknown or unsupported kind of resource. In this
// case, the Reason must be set to `InvalidKind` and the Message of
// the Condition must explain which kind of resource is unknown or
// unsupported.
//
// Support: Core - A single reference to a Kubernetes ConfigMap
// with the CA certificate in a key named `ca.crt`.
// * It refers to a resource in another namespace UNLESS there is a
// ReferenceGrant in the target namespace that allows the CA
// certificate to be attached. If a ReferenceGrant does not allow this
// reference, the `ResolvedRefs` condition MUST be set with
// the Reason `RefNotPermitted`.
//
// Support: Implementation-specific (More than one certificate in a ConfigMap with different keys or more than one reference, or other kinds of resources).
// In all cases, the implementation MUST ensure that the `ResolvedRefs`
// condition is set to `status: False` on all targeted listeners (i.e.,
// listeners serving HTTPS on a matching port). The condition MUST
// include a Reason and Message that indicate the cause of the error. If
// ALL CACertificateRefs are invalid, the implementation MUST also ensure
// the `Accepted` condition on the listener is set to `status: False`, with
// the Reason `NoValidCACertificate`.
// Implementations MAY choose to support attaching multiple CA certificates
// to a listener, but this behavior is implementation-specific.
//
// References to a resource in a different namespace are invalid UNLESS there
// is a ReferenceGrant in the target namespace that allows the certificate
// to be attached. If a ReferenceGrant does not allow this reference, the
// "ResolvedRefs" condition MUST be set to False for this listener with the
// "RefNotPermitted" reason.
// Support: Core - A single reference to a Kubernetes ConfigMap, with the
// CA certificate in a key named `ca.crt`.
//
// Support: Implementation-specific - More than one reference, other kinds
// of resources, or a single reference that includes multiple certificates.
//
// +listType=atomic
// +kubebuilder:validation:MaxItems=8
// +kubebuilder:validation:MinItems=1
CACertificateRefs []ObjectReference `json:"caCertificateRefs,omitempty"`
Expand All @@ -182,7 +209,9 @@ type FrontendTLSValidation struct {
//
// Defaults to AllowValidOnly.
//
// Support: Core
// Support: Core - AllowValidOnly
//
// Support: Extended - AllowInsecureFallback
//
// +optional
// +kubebuilder:default=AllowValidOnly
Expand Down