From b2490350821b7029237a57ed1bfdc10aa80f369f Mon Sep 17 00:00:00 2001 From: Rob Scott Date: Sat, 9 Sep 2023 00:43:06 +0000 Subject: [PATCH] Adding new SupportedVersion condition to GatewayClass --- apis/v1beta1/gatewayclass_types.go | 44 ++++++++++++++++++++++++++++++ site-src/concepts/guidelines.md | 18 +++++++++--- 2 files changed, 58 insertions(+), 4 deletions(-) diff --git a/apis/v1beta1/gatewayclass_types.go b/apis/v1beta1/gatewayclass_types.go index 9d166700d0..c2df77f90e 100644 --- a/apis/v1beta1/gatewayclass_types.go +++ b/apis/v1beta1/gatewayclass_types.go @@ -158,6 +158,7 @@ const ( // Possible reasons for this condition to be False are: // // * "InvalidParameters" + // * "UnsupportedVersion" // // Possible reasons for this condition to be Unknown are: // @@ -186,6 +187,49 @@ const ( GatewayClassReasonWaiting GatewayClassConditionReason = "Waiting" ) +const ( + // This condition indicates whether the GatewayClass supports the version(s) + // of Gateway API CRDs present in the cluster. This condition MUST be set by + // a controller when it marks a GatewayClass "Accepted". + // + // The version of a Gateway API CRD is defined by the + // gateway.networking.k8s.io/bundle-version annotation on the CRD. If + // implementations detect any Gateway API CRDs that either do not have this + // annotation set, or have it set to a version that is not recognized or + // supported by the implementation, this condition MUST be set to false. + // + // Implementations MAY choose to either provide "best effort" support when + // an unrecognized CRD version is present. This would be communicated by + // setting the "Accepted" condition to true and the "SupportedVersion" + // condition to false. + // + // Alternatively, implementations MAY choose not to support CRDs with + // unrecognized versions. This would be communicated by setting the + // "Accepted" condition to false with the reason "UnsupportedVersions". + // + // Possible reasons for this condition to be true are: + // + // * "SupportedVersion" + // + // Possible reasons for this condition to be False are: + // + // * "UnsupportedVersion" + // + // Controllers should prefer to use the values of GatewayClassConditionReason + // for the corresponding Reason, where appropriate. + GatewayClassConditionStatusSupportedVersion GatewayClassConditionType = "SupportedVersion" + + // This reason is used with the "SupportedVersion" condition when the + // condition is true. + GatewayClassReasonSupportedVersion GatewayClassConditionReason = "SupportedVersion" + + // This reason is used with the "SupportedVersion" or "Accepted" condition + // when the condition is false. A message SHOULD be included in this + // condition that includes the detected CRD version(s) present in the + // cluster and the CRD version(s) that are supported by the GatewayClass. + GatewayClassReasonUnsupportedVersion GatewayClassConditionReason = "UnsupportedVersion" +) + // GatewayClassStatus is the current status for the GatewayClass. type GatewayClassStatus struct { // Conditions is the current status from the controller for diff --git a/site-src/concepts/guidelines.md b/site-src/concepts/guidelines.md index e282f88523..dd7dfb068c 100644 --- a/site-src/concepts/guidelines.md +++ b/site-src/concepts/guidelines.md @@ -49,14 +49,24 @@ An important consideration when implementing this API is how it might change in the future. Similar to the Ingress API before it, this API is designed to be implemented by a variety of different products within the same cluster. That means that the API version your implementation was developed with may be -different than the API version it is used with. At a minimum, the following -requirements must be met to ensure future versions of the API do not break your -implementation: +different than the API version it is used with. + +At a minimum, the following requirements must be met to ensure future versions +of the API do not break your implementation: * Handle fields with loosened validation without crashing * Handle fields that have transitioned from required to optional without crashing +### Supported API Versions + +The version of Gateway API CRDs that is installed in a cluster can be determined +by looking at the `gateway.networking.k8s.io/bundle-version` annotation on each +CRD. Each implementation MUST compare that with the list of versions that it +recognizes and supports. Implementations with a GatewayClass MUST publish the +`SupportedVersion` condition on the GatewayClass to indicate whether the CRDs +installed in the cluster are supported. + ## Limitations of CRD and Webhook Validation CRD and webhook validation is not the final validation i.e. webhook is "nice UX" @@ -68,7 +78,7 @@ fully reliable because it: * May not be deployed correctly. * May be loosened in future API releases. (Fields may contain values with less - restrictive validation in newer versions of the API). + restrictive validation in newer versions of the API). *Note: These limitations are not unique to Gateway API and apply more broadly to any Kubernetes CRDs and webhooks.*