From f14b4356cfc82e0fd8c89a5f35573c14407e6024 Mon Sep 17 00:00:00 2001 From: Norwin Schnyder Date: Fri, 11 Jul 2025 08:37:47 +0000 Subject: [PATCH 1/6] gep: standardizing behavior for invalid BackendTLSPolicy Signed-off-by: Norwin Schnyder --- geps/gep-1897/index.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/geps/gep-1897/index.md b/geps/gep-1897/index.md index 4571c70335..f5f5d0f845 100644 --- a/geps/gep-1897/index.md +++ b/geps/gep-1897/index.md @@ -214,6 +214,8 @@ configuration. CACertificateRefs is an implementation-specific slice of named object references, each containing a single cert. We originally proposed to follow the convention established by the [CertificateRefs field on Gateway](https://github.com/kubernetes-sigs/gateway-api/blob/18e79909f7310aafc625ba7c862dfcc67b385250/apis/v1beta1/gateway_types.go#L340) , but the CertificateRef requires both a tls.key and tls.crt and a certificate reference only requires the tls.crt. +If the CertificateRef cannot be resolved or does not include a certificate (tls.crt), the BackendTLSPolicy is considered invalid. + WellKnownCACertificates is an optional enum that allows users to specify whether to use the set of CA certificates trusted by the Gateway (WellKnownCACertificates specified as "System"), or to use the existing CACertificateRefs (WellKnownCACertificates specified as ""). The use and definition of system certificates is implementation-dependent, and the intent is that @@ -223,7 +225,11 @@ between the gateway and backend pod. References to a resource in a different nam If ClientCertificateRefs is unspecified, then WellKnownCACertificates must be set to "System" for a valid configuration. If WellKnownCACertificates is unspecified, then CACertificateRefs must be specified with at least one entry for a valid configuration. If WellKnownCACertificates is set to "System" and there are no system trusted certificates or the implementation doesn't define system -trusted certificates, then the associated TLS connection must fail. +trusted certificates, the BackendTLSPolicy is considered invalid. + +For an invalid BackendTLSPolicy, implementations MUST NOT fall back to unencrypted (plaintext) connections. +Instead, the corresponding TLS connection MUST fail, and the client MUST receive an HTTP error response. +Additionally, the `Accepted` status condition of the BackendTLSPolicy MUST be set to `False` with the reason `Invalid`. The `Hostname` field is required and is to be used to configure the SNI the Gateway should use to connect to the backend. Implementations must validate that at least one name in the certificate served by the backend matches this field. From 49457d6574cf1cf134e8a71a99cfe75f684837a2 Mon Sep 17 00:00:00 2001 From: Norwin Schnyder Date: Tue, 22 Jul 2025 17:50:14 +0000 Subject: [PATCH 2/6] Apply PR feedback Signed-off-by: Norwin Schnyder --- geps/gep-1897/index.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/geps/gep-1897/index.md b/geps/gep-1897/index.md index f5f5d0f845..4d5ebbc913 100644 --- a/geps/gep-1897/index.md +++ b/geps/gep-1897/index.md @@ -214,7 +214,7 @@ configuration. CACertificateRefs is an implementation-specific slice of named object references, each containing a single cert. We originally proposed to follow the convention established by the [CertificateRefs field on Gateway](https://github.com/kubernetes-sigs/gateway-api/blob/18e79909f7310aafc625ba7c862dfcc67b385250/apis/v1beta1/gateway_types.go#L340) , but the CertificateRef requires both a tls.key and tls.crt and a certificate reference only requires the tls.crt. -If the CertificateRef cannot be resolved or does not include a certificate (tls.crt), the BackendTLSPolicy is considered invalid. +If any of the CACertificateRefs cannot be resolved or is misconfigured, the BackendTLSPolicy is considered invalid. WellKnownCACertificates is an optional enum that allows users to specify whether to use the set of CA certificates trusted by the Gateway (WellKnownCACertificates specified as "System"), or to use the existing CACertificateRefs (WellKnownCACertificates @@ -224,8 +224,7 @@ references to Kubernetes objects that contain PEM-encoded TLS certificates, whic between the gateway and backend pod. References to a resource in a different namespace are invalid. If ClientCertificateRefs is unspecified, then WellKnownCACertificates must be set to "System" for a valid configuration. If WellKnownCACertificates is unspecified, then CACertificateRefs must be specified with at least one entry for a valid configuration. -If WellKnownCACertificates is set to "System" and there are no system trusted certificates or the implementation doesn't define system -trusted certificates, the BackendTLSPolicy is considered invalid. +If an implementation does not support the WellKnownCACertificates, or the provided value is unsupported,the BackendTLSPolicy is considered invalid. For an invalid BackendTLSPolicy, implementations MUST NOT fall back to unencrypted (plaintext) connections. Instead, the corresponding TLS connection MUST fail, and the client MUST receive an HTTP error response. From 5b96eb354152b72eeda10f158f37689b4cfac2c4 Mon Sep 17 00:00:00 2001 From: Norwin Schnyder Date: Thu, 7 Aug 2025 06:46:41 +0000 Subject: [PATCH 3/6] Incorporate feedback from various discussions Signed-off-by: Norwin Schnyder --- geps/gep-1897/index.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/geps/gep-1897/index.md b/geps/gep-1897/index.md index 4d5ebbc913..1d5445999a 100644 --- a/geps/gep-1897/index.md +++ b/geps/gep-1897/index.md @@ -214,7 +214,8 @@ configuration. CACertificateRefs is an implementation-specific slice of named object references, each containing a single cert. We originally proposed to follow the convention established by the [CertificateRefs field on Gateway](https://github.com/kubernetes-sigs/gateway-api/blob/18e79909f7310aafc625ba7c862dfcc67b385250/apis/v1beta1/gateway_types.go#L340) , but the CertificateRef requires both a tls.key and tls.crt and a certificate reference only requires the tls.crt. -If any of the CACertificateRefs cannot be resolved or is misconfigured, the BackendTLSPolicy is considered invalid. +If any of the CACertificateRefs cannot be resolved (e.g., the referenced resource does not exist) or is misconfigured (e.g., ConfigMap does not contain a key named `ca.crt`), the BackendTLSPolicy is considered invalid. +Any further validation of the certificate content (i.e., checking expiry or enforcing specific formats) is implementation-specific. WellKnownCACertificates is an optional enum that allows users to specify whether to use the set of CA certificates trusted by the Gateway (WellKnownCACertificates specified as "System"), or to use the existing CACertificateRefs (WellKnownCACertificates @@ -227,8 +228,10 @@ If WellKnownCACertificates is unspecified, then CACertificateRefs must be specif If an implementation does not support the WellKnownCACertificates, or the provided value is unsupported,the BackendTLSPolicy is considered invalid. For an invalid BackendTLSPolicy, implementations MUST NOT fall back to unencrypted (plaintext) connections. -Instead, the corresponding TLS connection MUST fail, and the client MUST receive an HTTP error response. -Additionally, the `Accepted` status condition of the BackendTLSPolicy MUST be set to `False` with the reason `Invalid`. +Instead, the corresponding TLS connection MUST fail, and the client MUST receive an HTTP 5xx error response. +Additionally, the `Accepted` status condition of the BackendTLSPolicy MUST be set to `False` with `Reason: Invalid`. + +Implementations MUST NOT modify any status other than their own. Ownership of a status is determined by the `controllerName`, which identifies the responsible controller. The `Hostname` field is required and is to be used to configure the SNI the Gateway should use to connect to the backend. Implementations must validate that at least one name in the certificate served by the backend matches this field. From 9a41d1f67fece2d222e7abb6316c3d96cfd228eb Mon Sep 17 00:00:00 2001 From: Norwin Schnyder Date: Fri, 8 Aug 2025 06:55:08 +0000 Subject: [PATCH 4/6] Introduce ResolvedRefs status condition for BackendTLSPolicy --- geps/gep-1897/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/geps/gep-1897/index.md b/geps/gep-1897/index.md index 1d5445999a..7da3b07313 100644 --- a/geps/gep-1897/index.md +++ b/geps/gep-1897/index.md @@ -214,9 +214,11 @@ configuration. CACertificateRefs is an implementation-specific slice of named object references, each containing a single cert. We originally proposed to follow the convention established by the [CertificateRefs field on Gateway](https://github.com/kubernetes-sigs/gateway-api/blob/18e79909f7310aafc625ba7c862dfcc67b385250/apis/v1beta1/gateway_types.go#L340) , but the CertificateRef requires both a tls.key and tls.crt and a certificate reference only requires the tls.crt. -If any of the CACertificateRefs cannot be resolved (e.g., the referenced resource does not exist) or is misconfigured (e.g., ConfigMap does not contain a key named `ca.crt`), the BackendTLSPolicy is considered invalid. +If any of the CACertificateRefs cannot be resolved (e.g., the referenced resource does not exist) or is misconfigured (e.g., ConfigMap does not contain a key named `ca.crt`), the `ResolvedRefs` status condition MUST be set to `False` with `Reason: InvalidCACertificateRef` and a connection using that CACertificateRef MUST fail, and the client MUST receive an HTTP 5xx error response. Any further validation of the certificate content (i.e., checking expiry or enforcing specific formats) is implementation-specific. +If all CertificateRefs cannot be resolved, the BackendTLSPolicy is considered invalid. + WellKnownCACertificates is an optional enum that allows users to specify whether to use the set of CA certificates trusted by the Gateway (WellKnownCACertificates specified as "System"), or to use the existing CACertificateRefs (WellKnownCACertificates specified as ""). The use and definition of system certificates is implementation-dependent, and the intent is that From 3e426ad174140f0eb96acb15a20cb51aadae2dd2 Mon Sep 17 00:00:00 2001 From: Norwin Schnyder Date: Mon, 11 Aug 2025 07:52:40 +0000 Subject: [PATCH 5/6] Apply PR suggestions and feedback Signed-off-by: Norwin Schnyder --- geps/gep-1897/index.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/geps/gep-1897/index.md b/geps/gep-1897/index.md index 7da3b07313..bc4400e991 100644 --- a/geps/gep-1897/index.md +++ b/geps/gep-1897/index.md @@ -214,10 +214,12 @@ configuration. CACertificateRefs is an implementation-specific slice of named object references, each containing a single cert. We originally proposed to follow the convention established by the [CertificateRefs field on Gateway](https://github.com/kubernetes-sigs/gateway-api/blob/18e79909f7310aafc625ba7c862dfcc67b385250/apis/v1beta1/gateway_types.go#L340) , but the CertificateRef requires both a tls.key and tls.crt and a certificate reference only requires the tls.crt. -If any of the CACertificateRefs cannot be resolved (e.g., the referenced resource does not exist) or is misconfigured (e.g., ConfigMap does not contain a key named `ca.crt`), the `ResolvedRefs` status condition MUST be set to `False` with `Reason: InvalidCACertificateRef` and a connection using that CACertificateRef MUST fail, and the client MUST receive an HTTP 5xx error response. -Any further validation of the certificate content (i.e., checking expiry or enforcing specific formats) is implementation-specific. +If any of the CACertificateRefs cannot be resolved (e.g., the referenced resource does not exist) or is misconfigured (e.g., ConfigMap does not contain a key named `ca.crt`), the `ResolvedRefs` status condition MUST be set to `False` with `Reason: InvalidCACertificateRef`. Connections using that CACertificateRef MUST fail, and the client MUST receive an HTTP 5xx error response. +References to objects with an unsupported Group and Kind are not valid, and MUST be rejected by the implementation with the `ResolvedRefs` status condition set to `False` and `Reason: UnsupportedFeature`. +Implemenmtations MAY perform further validation of the certificate content (i.e., checking expiry or enforcing specific formats). If they do, they MUST ensure that the `ResolvedRefs` Condition is `False` and use an implementation-specific `Reason`, like `ExpiredCertificate` or similar. +If `ResolvedRefs` Condtion is `False` implmentations SHOULD include a message specifying which references are invalid and explaining why. -If all CertificateRefs cannot be resolved, the BackendTLSPolicy is considered invalid. +If all CertificateRefs cannot be resolved, the BackendTLSPolicy is considered invalid and the implementation MUST set the `Accepted` Condition to `False`, with a reason of `NoCACertificates` and a message explaining this. WellKnownCACertificates is an optional enum that allows users to specify whether to use the set of CA certificates trusted by the Gateway (WellKnownCACertificates specified as "System"), or to use the existing CACertificateRefs (WellKnownCACertificates @@ -227,11 +229,10 @@ references to Kubernetes objects that contain PEM-encoded TLS certificates, whic between the gateway and backend pod. References to a resource in a different namespace are invalid. If ClientCertificateRefs is unspecified, then WellKnownCACertificates must be set to "System" for a valid configuration. If WellKnownCACertificates is unspecified, then CACertificateRefs must be specified with at least one entry for a valid configuration. -If an implementation does not support the WellKnownCACertificates, or the provided value is unsupported,the BackendTLSPolicy is considered invalid. +If an implementation does not support the WellKnownCACertificates, or the provided value is unsupported,the BackendTLSPolicy is considered invalid, and the implementation MUST set the `Accepted` Condition to `False`, with a reason of `UnsupportedFeature` and a message explaining this. For an invalid BackendTLSPolicy, implementations MUST NOT fall back to unencrypted (plaintext) connections. Instead, the corresponding TLS connection MUST fail, and the client MUST receive an HTTP 5xx error response. -Additionally, the `Accepted` status condition of the BackendTLSPolicy MUST be set to `False` with `Reason: Invalid`. Implementations MUST NOT modify any status other than their own. Ownership of a status is determined by the `controllerName`, which identifies the responsible controller. From fd86e0a1a6b206f860ddc56f2841995f904a8feb Mon Sep 17 00:00:00 2001 From: Norwin Schnyder Date: Tue, 12 Aug 2025 20:55:43 +0000 Subject: [PATCH 6/6] Fix typos Signed-off-by: Norwin Schnyder --- geps/gep-1897/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/geps/gep-1897/index.md b/geps/gep-1897/index.md index bc4400e991..8e24b8bf09 100644 --- a/geps/gep-1897/index.md +++ b/geps/gep-1897/index.md @@ -216,8 +216,8 @@ named object references, each containing a single cert. We originally proposed t , but the CertificateRef requires both a tls.key and tls.crt and a certificate reference only requires the tls.crt. If any of the CACertificateRefs cannot be resolved (e.g., the referenced resource does not exist) or is misconfigured (e.g., ConfigMap does not contain a key named `ca.crt`), the `ResolvedRefs` status condition MUST be set to `False` with `Reason: InvalidCACertificateRef`. Connections using that CACertificateRef MUST fail, and the client MUST receive an HTTP 5xx error response. References to objects with an unsupported Group and Kind are not valid, and MUST be rejected by the implementation with the `ResolvedRefs` status condition set to `False` and `Reason: UnsupportedFeature`. -Implemenmtations MAY perform further validation of the certificate content (i.e., checking expiry or enforcing specific formats). If they do, they MUST ensure that the `ResolvedRefs` Condition is `False` and use an implementation-specific `Reason`, like `ExpiredCertificate` or similar. -If `ResolvedRefs` Condtion is `False` implmentations SHOULD include a message specifying which references are invalid and explaining why. +Implementations MAY perform further validation of the certificate content (i.e., checking expiry or enforcing specific formats). If they do, they MUST ensure that the `ResolvedRefs` Condition is `False` and use an implementation-specific `Reason`, like `ExpiredCertificate` or similar. +If `ResolvedRefs` Condition is `False` implementations SHOULD include a message specifying which references are invalid and explaining why. If all CertificateRefs cannot be resolved, the BackendTLSPolicy is considered invalid and the implementation MUST set the `Accepted` Condition to `False`, with a reason of `NoCACertificates` and a message explaining this.