Lint required optional (#3929)

* Add missing required markers on gateway types

* Add missing required markers on grpcroute types

* Add missing required markers on httproute types

* Add missing required markers on obj_reference types

* Add missing required markers on shared types

* Add missing required markers on experimental types

* Add missing required markers on v1beta1 types

* Add missing required markers on v1alpha3 types

* Add missing required markers on v1alpha2 types

* Enable optionalorrequired linter

* Revert objectmeta field doc

* Revert minItems changes

Author: rikatz

.github/workflows/kal.yml

@@ -15,6 +15,9 @@ jobs:
       fail-fast: false
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # tag=v4.2.2
+        name: Checkout code
+        with:
+          persist-credentials: false
       - name: Set up Go
         uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # tag=v5.5.0
       - name: Install Golang CI Lint

.golangci-kal.yml

@@ -16,6 +16,7 @@ linters:
               - "nofloats" # Ensure floats are not used.
               - "nomaps" # Ensure maps are not used.
               - "nophase" # Phase fields are discouraged by the Kube API conventions, use conditions instead.
+              - "optionalorrequired" # Every field should be marked as `+optional` or `+required`.
               - "statussubresource" # All root objects that have a `status` field should have a status subresource.
               - "uniquemarkers" # Ensure that types and fields do not contain more than a single definition of a marker that should only be present once.
             disable:

apis/v1/gateway_types.go

@@ -33,15 +33,18 @@ import (
 // Gateway represents an instance of a service-traffic handling infrastructure
 // by binding Listeners to a set of IP addresses.
 type Gateway struct {
-	metav1.TypeMeta   `json:",inline"`
+	metav1.TypeMeta `json:",inline"`
+	// +optional
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
 	// Spec defines the desired state of Gateway.
+	// +required
 	Spec GatewaySpec `json:"spec"`
 
 	// Status defines the current state of Gateway.
 	//
 	// +kubebuilder:default={conditions: {{type: "Accepted", status: "Unknown", reason:"Pending", message:"Waiting for controller", lastTransitionTime: "1970-01-01T00:00:00Z"},{type: "Programmed", status: "Unknown", reason:"Pending", message:"Waiting for controller", lastTransitionTime: "1970-01-01T00:00:00Z"}}}
+	// +optional
 	Status GatewayStatus `json:"status,omitempty"`
 }
 
@@ -63,6 +66,7 @@ type GatewayList struct {
 type GatewaySpec struct {
 	// GatewayClassName used for this Gateway. This is the name of a
 	// GatewayClass resource.
+	// +required
 	GatewayClassName ObjectName `json:"gatewayClassName"`
 
 	// Listeners associated with this Gateway. Listeners define
@@ -236,6 +240,7 @@ type GatewaySpec struct {
 	// +kubebuilder:validation:XValidation:message="hostname must not be specified for protocols ['TCP', 'UDP']",rule="self.all(l, l.protocol in ['TCP', 'UDP']  ? (!has(l.hostname) || l.hostname == '') : true)"
 	// +kubebuilder:validation:XValidation:message="Listener name must be unique within the Gateway",rule="self.all(l1, self.exists_one(l2, l1.name == l2.name))"
 	// +kubebuilder:validation:XValidation:message="Combination of port, protocol and hostname must be unique for each listener",rule="self.all(l1, self.exists_one(l2, l1.port == l2.port && l1.protocol == l2.protocol && (has(l1.hostname) && has(l2.hostname) ? l1.hostname == l2.hostname : !has(l1.hostname) && !has(l2.hostname))))"
+	// +required
 	Listeners []Listener `json:"listeners"`
 
 	// Addresses requested for this Gateway. This is optional and behavior can
@@ -333,6 +338,7 @@ type Listener struct {
 	// Gateway.
 	//
 	// Support: Core
+	// +required
 	Name SectionName `json:"name"`
 
 	// Hostname specifies the virtual hostname to match for protocol types that
@@ -390,11 +396,13 @@ type Listener struct {
 	// same port, subject to the Listener compatibility rules.
 	//
 	// Support: Core
+	// +required
 	Port PortNumber `json:"port"`
 
 	// Protocol specifies the network protocol this listener expects to receive.
 	//
 	// Support: Core
+	// +required
 	Protocol ProtocolType `json:"protocol"`
 
 	// TLS is the TLS configuration for the Listener. This field is required if
@@ -637,6 +645,7 @@ type FrontendTLSValidation struct {
 	//
 	// +kubebuilder:validation:MaxItems=8
 	// +kubebuilder:validation:MinItems=1
+	// +required
 	CACertificateRefs []ObjectReference `json:"caCertificateRefs,omitempty"`
 }
 
@@ -721,6 +730,7 @@ type RouteGroupKind struct {
 	Group *Group `json:"group,omitempty"`
 
 	// Kind is the kind of the Route.
+	// +required
 	Kind Kind `json:"kind"`
 }
 
@@ -764,6 +774,7 @@ type GatewayStatusAddress struct {
 	//
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=253
+	// +required
 	Value string `json:"value"`
 }
 
@@ -873,15 +884,18 @@ type GatewayInfrastructure struct {
 // configuration resource within the namespace.
 type LocalParametersReference struct {
 	// Group is the group of the referent.
+	// +required
 	Group Group `json:"group"`
 
 	// Kind is kind of the referent.
+	// +required
 	Kind Kind `json:"kind"`
 
 	// Name is the name of the referent.
 	//
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=253
+	// +required
 	Name string `json:"name"`
 }
 
@@ -1096,6 +1110,7 @@ const (
 // ListenerStatus is the status associated with a Listener.
 type ListenerStatus struct {
 	// Name is the name of the Listener that this status corresponds to.
+	// +required
 	Name SectionName `json:"name"`
 
 	// SupportedKinds is the list indicating the Kinds supported by this
@@ -1109,6 +1124,7 @@ type ListenerStatus struct {
 	// reference the valid Route kinds that have been specified.
 	//
 	// +kubebuilder:validation:MaxItems=8
+	// +required
 	SupportedKinds []RouteGroupKind `json:"supportedKinds"`
 
 	// AttachedRoutes represents the total number of Routes that have been
@@ -1128,13 +1144,15 @@ type ListenerStatus struct {
 	//
 	// Uses for this field include troubleshooting Route attachment and
 	// measuring blast radius/impact of changes to a Listener.
+	// +required
 	AttachedRoutes int32 `json:"attachedRoutes"`
 
 	// Conditions describe the current condition of this listener.
 	//
 	// +listType=map
 	// +listMapKey=type
 	// +kubebuilder:validation:MaxItems=8
+	// +required
 	Conditions []metav1.Condition `json:"conditions"`
 }
 

apis/v1/gatewayclass_types.go

@@ -49,10 +49,12 @@ import (
 //
 // GatewayClass is a Cluster level resource.
 type GatewayClass struct {
-	metav1.TypeMeta   `json:",inline"`
+	metav1.TypeMeta `json:",inline"`
+	// +optional
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
 	// Spec defines the desired state of GatewayClass.
+	// +required
 	Spec GatewayClassSpec `json:"spec"`
 
 	// Status defines the current state of GatewayClass.
@@ -61,6 +63,7 @@ type GatewayClass struct {
 	// specify their controller name.
 	//
 	// +kubebuilder:default={conditions: {{type: "Accepted", status: "Unknown", message: "Waiting for controller", reason: "Pending", lastTransitionTime: "1970-01-01T00:00:00Z"}}}
+	// +optional
 	Status GatewayClassStatus `json:"status,omitempty"`
 }
 
@@ -83,6 +86,7 @@ type GatewayClassSpec struct {
 	// Support: Core
 	//
 	// +kubebuilder:validation:XValidation:message="Value is immutable",rule="self == oldSelf"
+	// +required
 	ControllerName GatewayController `json:"controllerName"`
 
 	// ParametersRef is a reference to a resource that contains the configuration
@@ -118,15 +122,18 @@ type GatewayClassSpec struct {
 // configuration resource within the cluster.
 type ParametersReference struct {
 	// Group is the group of the referent.
+	// +required
 	Group Group `json:"group"`
 
 	// Kind is kind of the referent.
+	// +required
 	Kind Kind `json:"kind"`
 
 	// Name is the name of the referent.
 	//
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=253
+	// +required
 	Name string `json:"name"`
 
 	// Namespace is the namespace of the referent.
@@ -287,5 +294,6 @@ type GatewayClassList struct {
 type FeatureName string
 
 type SupportedFeature struct {
+	// +required
 	Name FeatureName `json:"name"`
 }

apis/v1/gatewayclass_types_overrides.go

@@ -51,6 +51,7 @@ func (s *SupportedFeature) UnmarshalJSON(data []byte) error {
 // This is solely for the purpose of ensuring backward compatibility and
 // SHOULD NOT be used elsewhere.
 type supportedFeatureInternal struct {
+	// +required
 	Name FeatureName `json:"name"`
 }
 

apis/v1/grpcroute_types.go

@@ -56,14 +56,16 @@ import (
 // Implementations MAY also accept HTTP/2 connections with an upgrade from
 // HTTP/1, i.e. without prior knowledge.
 type GRPCRoute struct {
-	metav1.TypeMeta   `json:",inline"`
+	metav1.TypeMeta `json:",inline"`
+	// +optional
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
 	// Spec defines the desired state of GRPCRoute.
 	// +required
 	Spec GRPCRouteSpec `json:"spec,omitempty"`
 
 	// Status defines the current state of GRPCRoute.
+	// +optional
 	Status GRPCRouteStatus `json:"status,omitempty"`
 }
 
@@ -405,12 +407,14 @@ type GRPCHeaderMatch struct {
 	// entries with an equivalent header name MUST be ignored. Due to the
 	// case-insensitivity of header names, "foo" and "Foo" are considered
 	// equivalent.
+	// +required
 	Name GRPCHeaderName `json:"name"`
 
 	// Value is the value of the gRPC Header to be matched.
 	//
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=4096
+	// +required
 	Value string `json:"value"`
 }
 
@@ -521,6 +525,7 @@ type GRPCRouteFilter struct {
 	// +unionDiscriminator
 	// +kubebuilder:validation:Enum=ResponseHeaderModifier;RequestHeaderModifier;RequestMirror;ExtensionRef
 	// <gateway:experimental:validation:Enum=ResponseHeaderModifier;RequestHeaderModifier;RequestMirror;ExtensionRef>
+	// +required
 	Type GRPCRouteFilterType `json:"type"`
 
 	// RequestHeaderModifier defines a schema for a filter that modifies request

apis/v1/httproute_types.go

@@ -33,13 +33,16 @@ import (
 // used to specify additional processing steps. Backends specify where matching
 // requests should be routed.
 type HTTPRoute struct {
-	metav1.TypeMeta   `json:",inline"`
+	metav1.TypeMeta `json:",inline"`
+	// +optional
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
 	// Spec defines the desired state of HTTPRoute.
+	// +required
 	Spec HTTPRouteSpec `json:"spec"`
 
 	// Status defines the current state of HTTPRoute.
+	// +optional
 	Status HTTPRouteStatus `json:"status,omitempty"`
 }
 
@@ -608,12 +611,14 @@ type HTTPHeaderMatch struct {
 	// Generally, proxies should follow the guidance from the RFC:
 	// https://www.rfc-editor.org/rfc/rfc7230.html#section-3.2.2 regarding
 	// processing a repeated header, with special handling for "Set-Cookie".
+	// +required
 	Name HTTPHeaderName `json:"name"`
 
 	// Value is the value of HTTP Header to be matched.
 	//
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=4096
+	// +required
 	Value string `json:"value"`
 }
 
@@ -675,12 +680,14 @@ type HTTPQueryParamMatch struct {
 	//
 	// Users SHOULD NOT route traffic based on repeated query params to guard
 	// themselves against potential differences in the implementations.
+	// +required
 	Name HTTPHeaderName `json:"name"`
 
 	// Value is the value of HTTP query param to be matched.
 	//
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=1024
+	// +required
 	Value string `json:"value"`
 }
 
@@ -830,6 +837,7 @@ type HTTPRouteFilter struct {
 	// +unionDiscriminator
 	// +kubebuilder:validation:Enum=RequestHeaderModifier;ResponseHeaderModifier;RequestMirror;RequestRedirect;URLRewrite;ExtensionRef
 	// <gateway:experimental:validation:Enum=RequestHeaderModifier;ResponseHeaderModifier;RequestMirror;RequestRedirect;URLRewrite;ExtensionRef;CORS>
+	// +required
 	Type HTTPRouteFilterType `json:"type"`
 
 	// RequestHeaderModifier defines a schema for a filter that modifies request
@@ -977,12 +985,14 @@ type HTTPHeader struct {
 	// with an equivalent header name MUST be ignored. Due to the
 	// case-insensitivity of header names, "foo" and "Foo" are considered
 	// equivalent.
+	// +required
 	Name HTTPHeaderName `json:"name"`
 
 	// Value is the value of HTTP Header to be matched.
 	//
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=4096
+	// +required
 	Value string `json:"value"`
 }
 
@@ -1101,6 +1111,7 @@ type HTTPPathModifier struct {
 	// Reason of `UnsupportedValue`.
 	//
 	// +kubebuilder:validation:Enum=ReplaceFullPath;ReplacePrefixMatch
+	// +required
 	Type HTTPPathModifierType `json:"type"`
 
 	// ReplaceFullPath specifies the value with which to replace the full path
@@ -1274,6 +1285,7 @@ type HTTPRequestMirrorFilter struct {
 	// Support: Extended for Kubernetes Service
 	//
 	// Support: Implementation-specific for any other resource
+	// +required
 	BackendRef BackendObjectReference `json:"backendRef"`
 
 	// Percent represents the percentage of requests that should be
@@ -1356,6 +1368,7 @@ type HTTPCORSFilter struct {
 	// Support: Extended
 	// +listType=set
 	// +kubebuilder:validation:MaxItems=64
+	// +optional
 	AllowOrigins []AbsoluteURI `json:"allowOrigins,omitempty"`
 
 	// AllowCredentials indicates whether the actual cross-origin request allows
@@ -1417,6 +1430,7 @@ type HTTPCORSFilter struct {
 	// +listType=set
 	// +kubebuilder:validation:MaxItems=9
 	// +kubebuilder:validation:XValidation:message="AllowMethods cannot contain '*' alongside other methods",rule="!('*' in self && self.size() > 1)"
+	// +optional
 	AllowMethods []HTTPMethodWithWildcard `json:"allowMethods,omitempty"`
 
 	// AllowHeaders indicates which HTTP request headers are supported for
@@ -1458,6 +1472,7 @@ type HTTPCORSFilter struct {
 	//
 	// +listType=set
 	// +kubebuilder:validation:MaxItems=64
+	// +optional
 	AllowHeaders []HTTPHeaderName `json:"allowHeaders,omitempty"`
 
 	// ExposeHeaders indicates which HTTP response headers can be exposed