From bc1e8802e8459e87d1c9dac895ee9fa16e56078c Mon Sep 17 00:00:00 2001 From: Norwin Schnyder Date: Wed, 22 Oct 2025 18:03:44 +0000 Subject: [PATCH 1/2] api: experimental ResolvedRefs condition for Gateway Signed-off-by: Norwin Schnyder --- apis/v1/gateway_types.go | 82 +++++++++++++++---- .../gateway.networking.k8s.io_gateways.yaml | 74 +++++++++++------ pkg/generated/openapi/zz_generated.openapi.go | 2 +- 3 files changed, 117 insertions(+), 41 deletions(-) diff --git a/apis/v1/gateway_types.go b/apis/v1/gateway_types.go index 3b856a1567..13705ff5e0 100644 --- a/apis/v1/gateway_types.go +++ b/apis/v1/gateway_types.go @@ -526,20 +526,30 @@ const ( // GatewayBackendTLS describes backend TLS configuration for gateway. type GatewayBackendTLS struct { - // ClientCertificateRef is a reference to an object that contains a Client - // Certificate and the associated private key. - // - // References to a resource in 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. - // - // ClientCertificateRef can reference to standard Kubernetes resources, i.e. - // Secret, or implementation-specific custom resources. - // - // Support: Core - // + // ClientCertificateRef references an object that contains a client certificate + // and its associated private key. It can reference standard Kubernetes resources, + // i.e., Secret, or implementation-specific custom resources. + // + // A ClientCertificateRef is considered 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 Secret does not contain the keys + // named `tls.crt` and `tls.key`). In this case, the `ResolvedRefs` condition + // on the Gateway MUST be set to False with the Reason `InvalidClientCertificateRef` + // and the Message of the Condition MUST indicate why the reference is invalid. + // + // * It refers to a resource in another namespace 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 + // on the Gateway MUST be set to False with the Reason `RefNotPermitted`. + // + // 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. + // + // Support: Core - Reference to a Kubernetes TLS Secret (with the type `kubernetes.io/tls`). + // Support: Implementation-specific - Other resource kinds or Secrets with a + // different type (e.g., `Opaque`). // +optional // ClientCertificateRef *SecretObjectReference `json:"clientCertificateRef,omitempty"` @@ -1237,6 +1247,50 @@ const ( GatewayReasonNotReconciled GatewayConditionReason = "NotReconciled" ) +const ( + // This condition indicates whether the controller was able to resolve all + // the object references for the Gateway that are not part of a specific + // Listener configuration. + // + // Possible reasons for this condition to be True are: + // + // * "ResolvedRefs" + // + // Possible reasons for this condition to be False are: + // + // * "RefNotPermitted" + // * "InvalidClientCertificateRef" + // + // Controllers may raise this condition with other reasons, but should + // prefer to use the reasons listed above to improve interoperability. + // + // Note: This condition is considered Experimental and may change in future + // releases of the API. + GatewayConditionResolvedRefs GatewayConditionType = "ResolvedRefs" + + // This reason is used with the "ResolvedRefs" condition when the condition + // is true. + GatewayReasonResolvedRefs GatewayConditionReason = "ResolvedRefs" + + // This reason is used with the "ResolvedRefs" condition when the Gateway + // has an invalid ClientCertificateRef in its backend TLS configuration. + // A ClientCertificateRef is considered invalid when it refers to a + // nonexistent or unsupported resource or kind, or when the data within + // that resource is malformed. + // This reason must be used only when the reference is allowed, either by + // referencing an object in the same namespace as the Gateway, or when + // a cross-namespace reference has been explicitly allowed by a ReferenceGrant. + // If the reference is not allowed, the reason RefNotPermitted must be used + // instead. + GatewayReasonInvalidClientCertificateRef GatewayConditionReason = "InvalidClientCertificateRef" + + // This reason is used with the "ResolvedRefs" condition when the Gateway + // has a top-level backend TLS configuration that references an object in + // another namespace, where the object in the other namespace does not have + // a ReferenceGrant explicitly allowing the reference. + GatewayReasonRefNotPermitted GatewayConditionReason = "RefNotPermitted" +) + const ( // "Ready" is a condition type reserved for future use. It should not be used by implementations. // diff --git a/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml b/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml index 1d27104859..b4aafdeb40 100644 --- a/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml +++ b/config/crd/experimental/gateway.networking.k8s.io_gateways.yaml @@ -947,19 +947,30 @@ spec: properties: clientCertificateRef: description: |- - ClientCertificateRef is a reference to an object that contains a Client - Certificate and the associated private key. - - References to a resource in 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. - - ClientCertificateRef can reference to standard Kubernetes resources, i.e. - Secret, or implementation-specific custom resources. - - Support: Core + ClientCertificateRef references an object that contains a client certificate + and its associated private key. It can reference standard Kubernetes resources, + i.e., Secret, or implementation-specific custom resources. + + A ClientCertificateRef is considered 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 Secret does not contain the keys + named `tls.crt` and `tls.key`). In this case, the `ResolvedRefs` condition + on the Gateway MUST be set to False with the Reason `InvalidClientCertificateRef` + and the Message of the Condition MUST indicate why the reference is invalid. + + * It refers to a resource in another namespace 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 + on the Gateway MUST be set to False with the Reason `RefNotPermitted`. + + 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. + + Support: Core - Reference to a Kubernetes TLS Secret (with the type `kubernetes.io/tls`). + Support: Implementation-specific - Other resource kinds or Secrets with a + different type (e.g., `Opaque`). properties: group: default: "" @@ -2524,19 +2535,30 @@ spec: properties: clientCertificateRef: description: |- - ClientCertificateRef is a reference to an object that contains a Client - Certificate and the associated private key. - - References to a resource in 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. - - ClientCertificateRef can reference to standard Kubernetes resources, i.e. - Secret, or implementation-specific custom resources. - - Support: Core + ClientCertificateRef references an object that contains a client certificate + and its associated private key. It can reference standard Kubernetes resources, + i.e., Secret, or implementation-specific custom resources. + + A ClientCertificateRef is considered 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 Secret does not contain the keys + named `tls.crt` and `tls.key`). In this case, the `ResolvedRefs` condition + on the Gateway MUST be set to False with the Reason `InvalidClientCertificateRef` + and the Message of the Condition MUST indicate why the reference is invalid. + + * It refers to a resource in another namespace 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 + on the Gateway MUST be set to False with the Reason `RefNotPermitted`. + + 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. + + Support: Core - Reference to a Kubernetes TLS Secret (with the type `kubernetes.io/tls`). + Support: Implementation-specific - Other resource kinds or Secrets with a + different type (e.g., `Opaque`). properties: group: default: "" diff --git a/pkg/generated/openapi/zz_generated.openapi.go b/pkg/generated/openapi/zz_generated.openapi.go index 0968ead79a..be1218475d 100644 --- a/pkg/generated/openapi/zz_generated.openapi.go +++ b/pkg/generated/openapi/zz_generated.openapi.go @@ -4072,7 +4072,7 @@ func schema_sigsk8sio_gateway_api_apis_v1_GatewayBackendTLS(ref common.Reference Properties: map[string]spec.Schema{ "clientCertificateRef": { SchemaProps: spec.SchemaProps{ - Description: "ClientCertificateRef is a reference to an object that contains a Client Certificate and the associated private key.\n\nReferences to a resource in 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.\n\nClientCertificateRef can reference to standard Kubernetes resources, i.e. Secret, or implementation-specific custom resources.\n\nSupport: Core\n\n", + Description: "ClientCertificateRef references an object that contains a client certificate and its associated private key. It can reference standard Kubernetes resources, i.e., Secret, or implementation-specific custom resources.\n\nA ClientCertificateRef is considered invalid if:\n\n* It refers to a resource that cannot be resolved (e.g., the referenced resource\n does not exist) or is misconfigured (e.g., a Secret does not contain the keys\n named `tls.crt` and `tls.key`). In this case, the `ResolvedRefs` condition\n on the Gateway MUST be set to False with the Reason `InvalidClientCertificateRef`\n and the Message of the Condition MUST indicate why the reference is invalid.\n\n* It refers to a resource in another namespace UNLESS there is a ReferenceGrant\n in the target namespace that allows the certificate to be attached.\n If a ReferenceGrant does not allow this reference, the `ResolvedRefs` condition\n on the Gateway MUST be set to False with the Reason `RefNotPermitted`.\n\nImplementations 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.\n\nSupport: Core - Reference to a Kubernetes TLS Secret (with the type `kubernetes.io/tls`). Support: Implementation-specific - Other resource kinds or Secrets with a different type (e.g., `Opaque`). ", Ref: ref("sigs.k8s.io/gateway-api/apis/v1.SecretObjectReference"), }, }, From 425d50144e6ba8e56a4d71a32c65cb9d4c7f7958 Mon Sep 17 00:00:00 2001 From: Norwin Schnyder Date: Sat, 8 Nov 2025 08:40:02 +0000 Subject: [PATCH 2/2] add reason ListenersNotResolved Signed-off-by: Norwin Schnyder --- apis/v1/gateway_types.go | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/apis/v1/gateway_types.go b/apis/v1/gateway_types.go index 13705ff5e0..b054c8ee5e 100644 --- a/apis/v1/gateway_types.go +++ b/apis/v1/gateway_types.go @@ -1250,7 +1250,8 @@ const ( const ( // This condition indicates whether the controller was able to resolve all // the object references for the Gateway that are not part of a specific - // Listener configuration. + // Listener configuration, and also provides a positive-polarity summary of + // the Listener's "ResolvedRefs" condition. // // Possible reasons for this condition to be True are: // @@ -1260,6 +1261,7 @@ const ( // // * "RefNotPermitted" // * "InvalidClientCertificateRef" + // * "ListenersNotResolved" // // Controllers may raise this condition with other reasons, but should // prefer to use the reasons listed above to improve interoperability. @@ -1289,6 +1291,10 @@ const ( // another namespace, where the object in the other namespace does not have // a ReferenceGrant explicitly allowing the reference. GatewayReasonRefNotPermitted GatewayConditionReason = "RefNotPermitted" + + // This reason is used with the "ResolvedRefs" condition when one or more + // Listeners have their "ResolvedRefs" condition set to false in their status. + GatewayReasonListenersNotResolved GatewayConditionReason = "ListenersNotResolved" ) const (