Merge pull request #2384 from robscott/version-skew

Adding new SupportedVersion condition to GatewayClass

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

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.*