Merge pull request #1258 from youngnick/enum-details-update

Enum details update

apis/v1alpha2/gateway_types.go

@@ -351,6 +351,13 @@ type GatewayTLSConfig struct {
 
 // TLSModeType type defines how a Gateway handles TLS sessions.
 //
+// Note that values may be added to this enum, implementations
+// must ensure that unknown values will not cause a crash.
+//
+// Unknown values here must result in the implementation setting the
+// Ready Condition for the Listener to `status: False`, with a
+// Reason of `Invalid`.
+//
 // +kubebuilder:validation:Enum=Terminate;Passthrough
 type TLSModeType string
 
@@ -398,6 +405,13 @@ type AllowedRoutes struct {
 // FromNamespaces specifies namespace from which Routes may be attached to a
 // Gateway.
 //
+// Note that values may be added to this enum, implementations
+// must ensure that unknown values will not cause a crash.
+//
+// Unknown values here must result in the implementation setting the
+// Ready Condition for the Listener to `status: False`, with a
+// Reason of `Invalid`.
+//
 // +kubebuilder:validation:Enum=All;Selector;Same
 type FromNamespaces string
 

apis/v1alpha2/httproute_types.go

@@ -244,6 +244,13 @@ type HTTPRouteRule struct {
 // - Must begin with the `/` character
 // - Must not contain consecutive `/` characters (e.g. `/foo///`, `//`).
 //
+// Note that values may be added to this enum, implementations
+// must ensure that unknown values will not cause a crash.
+//
+// Unknown values here must result in the implementation setting the
+// Attached Condition for the Route to `status: False`, with a
+// Reason of `UnsupportedValue`.
+//
 // +kubebuilder:validation:Enum=Exact;PathPrefix;RegularExpression
 type PathMatchType string
 
@@ -299,6 +306,13 @@ type HTTPPathMatch struct {
 // * "Exact"
 // * "RegularExpression"
 //
+// Note that values may be added to this enum, implementations
+// must ensure that unknown values will not cause a crash.
+//
+// Unknown values here must result in the implementation setting the
+// Attached Condition for the Route to `status: False`, with a
+// Reason of `UnsupportedValue`.
+//
 // +kubebuilder:validation:Enum=Exact;RegularExpression
 type HeaderMatchType string
 
@@ -373,6 +387,13 @@ type HTTPHeaderMatch struct {
 // * "Exact"
 // * "RegularExpression"
 //
+// Note that values may be added to this enum, implementations
+// must ensure that unknown values will not cause a crash.
+//
+// Unknown values here must result in the implementation setting the
+// Attached Condition for the Route to `status: False`, with a
+// Reason of `UnsupportedValue`.
+//
 // +kubebuilder:validation:Enum=Exact;RegularExpression
 type QueryParamMatchType string
 
@@ -424,6 +445,14 @@ type HTTPQueryParamMatch struct {
 // [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-4) and
 // [RFC 5789](https://datatracker.ietf.org/doc/html/rfc5789#section-2).
 // The value is expected in upper case.
+//
+// Note that values may be added to this enum, implementations
+// must ensure that unknown values will not cause a crash.
+//
+// Unknown values here must result in the implementation setting the
+// Attached Condition for the Route to `status: False`, with a
+// Reason of `UnsupportedValue`.
+//
 // +kubebuilder:validation:Enum=GET;HEAD;POST;PUT;DELETE;CONNECT;OPTIONS;TRACE;PATCH
 type HTTPMethod string
 
@@ -524,6 +553,13 @@ type HTTPRouteFilter struct {
 	// MUST NOT be skipped. Instead, requests that would have been processed by
 	// that filter MUST receive a HTTP error response.
 	//
+	// Note that values may be added to this enum, implementations
+	// must ensure that unknown values will not cause a crash.
+	//
+	// Unknown values here must result in the implementation setting the
+	// Attached Condition for the Route to `status: False`, with a
+	// Reason of `UnsupportedValue`.
+	//
 	// +unionDiscriminator
 	// +kubebuilder:validation:Enum=RequestHeaderModifier;RequestMirror;RequestRedirect;ExtensionRef
 	// <gateway:experimental:validation:Enum=RequestHeaderModifier;RequestMirror;RequestRedirect;URLRewrite;ExtensionRef>
@@ -743,6 +779,13 @@ type HTTPPathModifier struct {
 	// Type defines the type of path modifier. Additional types may be
 	// added in a future release of the API.
 	//
+	// Note that values may be added to this enum, implementations
+	// must ensure that unknown values will not cause a crash.
+	//
+	// Unknown values here must result in the implementation setting the
+	// Attached Condition for the Route to `status: False`, with a
+	// Reason of `UnsupportedValue`.
+	//
 	// <gateway:experimental>
 	// +kubebuilder:validation:Enum=ReplaceFullPath;ReplacePrefixMatch
 	Type HTTPPathModifierType `json:"type"`
@@ -780,6 +823,13 @@ type HTTPRequestRedirectFilter struct {
 	//
 	// Support: Extended
 	//
+	// Note that values may be added to this enum, implementations
+	// must ensure that unknown values will not cause a crash.
+	//
+	// Unknown values here must result in the implementation setting the
+	// Attached Condition for the Route to `status: False`, with a
+	// Reason of `UnsupportedValue`.
+	//
 	// +optional
 	// +kubebuilder:validation:Enum=http;https
 	Scheme *string `json:"scheme,omitempty"`
@@ -816,6 +866,13 @@ type HTTPRequestRedirectFilter struct {
 	//
 	// Support: Core
 	//
+	// Note that values may be added to this enum, implementations
+	// must ensure that unknown values will not cause a crash.
+	//
+	// Unknown values here must result in the implementation setting the
+	// Attached Condition for the Route to `status: False`, with a
+	// Reason of `UnsupportedValue`.
+	//
 	// +optional
 	// +kubebuilder:default=302
 	// +kubebuilder:validation:Enum=301;302

apis/v1alpha2/shared_types.go

@@ -217,6 +217,10 @@ const (
 	// compatible Listeners whose Hostname matches the route
 	RouteReasonNoMatchingListenerHostname RouteConditionReason = "NoMatchingListenerHostname"
 
+	// This reason is used with the "Accepted" condition when a value for an Enum
+	// is not recognized.
+	RouteReasonUnsupportedValue RouteConditionReason = "UnsupportedValue"
+
 	// This condition indicates whether the controller was able to resolve all
 	// the object references for the Route.
 	//

apis/v1beta1/httproute_types.go

@@ -221,6 +221,7 @@ type HTTPRouteRule struct {
 	// recommended to return a 503 status code.
 	//
 	// Support: Core for Kubernetes Service
+	//
 	// Support: Custom for any other resource
 	//
 	// Support for weight: Core
@@ -242,6 +243,13 @@ type HTTPRouteRule struct {
 // - Must begin with the `/` character
 // - Must not contain consecutive `/` characters (e.g. `/foo///`, `//`).
 //
+// Note that values may be added to this enum, implementations
+// must ensure that unknown values will not cause a crash.
+//
+// Unknown values here must result in the implementation setting the
+// Attached Condition for the Route to `status: False`, with a
+// Reason of `UnsupportedValue`.
+//
 // +kubebuilder:validation:Enum=Exact;PathPrefix;RegularExpression
 type PathMatchType string
 
@@ -297,6 +305,13 @@ type HTTPPathMatch struct {
 // * "Exact"
 // * "RegularExpression"
 //
+// Note that values may be added to this enum, implementations
+// must ensure that unknown values will not cause a crash.
+//
+// Unknown values here must result in the implementation setting the
+// Attached Condition for the Route to `status: False`, with a
+// Reason of `UnsupportedValue`.
+//
 // +kubebuilder:validation:Enum=Exact;RegularExpression
 type HeaderMatchType string
 
@@ -371,6 +386,13 @@ type HTTPHeaderMatch struct {
 // * "Exact"
 // * "RegularExpression"
 //
+// Note that values may be added to this enum, implementations
+// must ensure that unknown values will not cause a crash.
+//
+// Unknown values here must result in the implementation setting the
+// Attached Condition for the Route to `status: False`, with a
+// Reason of `UnsupportedValue`.
+//
 // +kubebuilder:validation:Enum=Exact;RegularExpression
 type QueryParamMatchType string
 
@@ -422,6 +444,14 @@ type HTTPQueryParamMatch struct {
 // [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-4) and
 // [RFC 5789](https://datatracker.ietf.org/doc/html/rfc5789#section-2).
 // The value is expected in upper case.
+//
+// Note that values may be added to this enum, implementations
+// must ensure that unknown values will not cause a crash.
+//
+// Unknown values here must result in the implementation setting the
+// Attached Condition for the Route to `status: False`, with a
+// Reason of `UnsupportedValue`.
+//
 // +kubebuilder:validation:Enum=GET;HEAD;POST;PUT;DELETE;CONNECT;OPTIONS;TRACE;PATCH
 type HTTPMethod string
 
@@ -522,6 +552,13 @@ type HTTPRouteFilter struct {
 	// MUST NOT be skipped. Instead, requests that would have been processed by
 	// that filter MUST receive a HTTP error response.
 	//
+	// Note that values may be added to this enum, implementations
+	// must ensure that unknown values will not cause a crash.
+	//
+	// Unknown values here must result in the implementation setting the
+	// Attached Condition for the Route to `status: False`, with a
+	// Reason of `UnsupportedValue`.
+	//
 	// +unionDiscriminator
 	// +kubebuilder:validation:Enum=RequestHeaderModifier;RequestMirror;RequestRedirect;ExtensionRef
 	// <gateway:experimental:validation:Enum=RequestHeaderModifier;RequestMirror;RequestRedirect;URLRewrite;ExtensionRef>
@@ -741,6 +778,13 @@ type HTTPPathModifier struct {
 	// Type defines the type of path modifier. Additional types may be
 	// added in a future release of the API.
 	//
+	// Note that values may be added to this enum, implementations
+	// must ensure that unknown values will not cause a crash.
+	//
+	// Unknown values here must result in the implementation setting the
+	// Attached Condition for the Route to `status: False`, with a
+	// Reason of `UnsupportedValue`.
+	//
 	// <gateway:experimental>
 	// +kubebuilder:validation:Enum=ReplaceFullPath;ReplacePrefixMatch
 	Type HTTPPathModifierType `json:"type"`
@@ -778,6 +822,13 @@ type HTTPRequestRedirectFilter struct {
 	//
 	// Support: Extended
 	//
+	// Note that values may be added to this enum, implementations
+	// must ensure that unknown values will not cause a crash.
+	//
+	// Unknown values here must result in the implementation setting the
+	// Attached Condition for the Route to `status: False`, with a
+	// Reason of `UnsupportedValue`.
+	//
 	// +optional
 	// +kubebuilder:validation:Enum=http;https
 	Scheme *string `json:"scheme,omitempty"`
@@ -814,6 +865,13 @@ type HTTPRequestRedirectFilter struct {
 	//
 	// Support: Core
 	//
+	// Note that values may be added to this enum, implementations
+	// must ensure that unknown values will not cause a crash.
+	//
+	// Unknown values here must result in the implementation setting the
+	// Attached Condition for the Route to `status: False`, with a
+	// Reason of `UnsupportedValue`.
+	//
 	// +optional
 	// +kubebuilder:default=302
 	// +kubebuilder:validation:Enum=301;302

apis/v1beta1/shared_types.go

@@ -217,6 +217,10 @@ const (
 	// compatible Listeners whose Hostname matches the route
 	RouteReasonNoMatchingListenerHostname RouteConditionReason = "NoMatchingListenerHostname"
 
+	// This reason is used with the "Accepted" condition when a value for an Enum
+	// is not recognized.
+	RouteReasonUnsupportedValue RouteConditionReason = "UnsupportedValue"
+
 	// This condition indicates whether the controller was able to resolve all
 	// the object references for the Route.
 	//