Skip to content
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

Adding new SupportedVersion condition to GatewayClass #2384

Merged
merged 1 commit into from
Sep 14, 2023
Merged

Adding new SupportedVersion condition to GatewayClass #2384

Show file tree
Hide file tree
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
44 changes: 44 additions & 0 deletions apis/v1beta1/gatewayclass_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
//
Expand Down Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

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

Since this condition "MUST be set", would it make sense to update the conformance tests too?

Copy link
Member Author

Choose a reason for hiding this comment

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

Yes, I think we'll want to have corresponding updates to the conformance tests. I'd initially thought those should be a separate PR, but they may be simple enough to combine here.

// 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
Expand Down
18 changes: 14 additions & 4 deletions site-src/concepts/guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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.*
Expand Down