Enable kubeapilinter for GIE APIs (#1366)

* Enable kubeapilinter github action

* Fix findings on stable APIs

* Fix findings after rebase

Author: rikatz

.custom-gcl.yml

@@ -0,0 +1,6 @@
+version: v2.3.1
+name: golangci-kube-api-linter
+destination: ./bin
+plugins:
+- module: 'sigs.k8s.io/kube-api-linter'
+  version: 'v0.0.0-20250808120943-48643eb2563d' # Pin to a commit while there's no tag

.github/workflows/kal.yml

@@ -0,0 +1,28 @@
+name: PR golangci-lint
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+# Remove all permissions from GITHUB_TOKEN except metadata.
+permissions: {}
+
+jobs:
+  golangci:
+    name: kube-api-lint
+    runs-on: ubuntu-latest
+    strategy:
+      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
+        run: go install github.com/golangci/golangci-lint/v2/cmd/[email protected]
+      - name: Build KAL
+        run: golangci-lint custom
+      - name: run api linter
+        run: ./bin/golangci-kube-api-linter run -c ./.golangci-kal.yml ./...

.golangci-kal.yml

@@ -0,0 +1,46 @@
+version: "2"
+linters:
+  default: none
+  enable:
+    - kubeapilinter
+  settings:
+    custom:
+      kubeapilinter:
+        type: module
+        description: Kube API LInter lints Kube like APIs based on API conventions and best practices.
+        settings:
+          linters:
+            enable:
+              - "*"
+            disable:
+              - "commentstart"
+          lintersConfig:
+            conflictingmarkers:
+              conflicts:
+              - name: "default_vs_required"
+                sets:
+                  - ["default", "kubebuilder:default"]
+                  - ["required", "kubebuilder:validation:Required", "k8s:required"]
+                description: "A field with a default value cannot be required"
+            conditions:
+              isFirstField: Warn # Require conditions to be the first field in the status struct.
+              usePatchStrategy: Forbid # Forbid patchStrategy markers on the Conditions field.
+              useProtobuf: Forbid # We don't use protobuf, so protobuf tags are not required.
+            optionalfields:
+              pointers:
+                preference: WhenRequired # Always | WhenRequired # Whether to always require pointers, or only when required. Defaults to `Always`.
+                policy: SuggestFix # SuggestFix | Warn # The policy for pointers in optional fields. Defaults to `SuggestFix`. 
+              omitempty:
+                policy: SuggestFix # SuggestFix | Warn | Ignore # The policy for omitempty in optional fields. Defaults to `SuggestFix`.
+  exclusions:
+    generated: strict
+    paths:
+      - conformance/
+    paths-except:
+      - api/
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0
+run:
+  timeout: 5m
+  tests: false

api/v1/inferencepool_types.go

@@ -29,15 +29,19 @@ import (
 // +kubebuilder:storageversion
 // +genclient
 type InferencePool struct {
-	metav1.TypeMeta   `json:",inline"`
+	metav1.TypeMeta `json:",inline"`
+
+	// +optional
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec InferencePoolSpec `json:"spec,omitempty"`
+	// +required
+	Spec InferencePoolSpec `json:"spec,omitzero"`
 
 	// Status defines the observed state of InferencePool.
 	//
 	// +kubebuilder:default={parent: {{parentRef: {kind: "Status", name: "default"}, conditions: {{type: "Accepted", status: "Unknown", reason: "Pending", message: "Waiting for controller", lastTransitionTime: "1970-01-01T00:00:00Z"}}}}}
-	Status InferencePoolStatus `json:"status,omitempty"`
+	// +optional
+	Status InferencePoolStatus `json:"status,omitzero"`
 }
 
 // InferencePoolList contains a list of InferencePool.
@@ -59,19 +63,20 @@ type InferencePoolSpec struct {
 	// with Kubernetes Service selectors, as some implementations may translate
 	// this configuration into a Service resource.
 	//
-	// +kubebuilder:validation:Required
-	Selector LabelSelector `json:"selector"`
+	// +required
+	Selector LabelSelector `json:"selector,omitempty,omitzero"`
 
 	// TargetPortNumber defines the port number to access the selected model server Pods.
 	// The number must be in the range 1 to 65535.
 	//
 	// +kubebuilder:validation:Minimum=1
 	// +kubebuilder:validation:Maximum=65535
-	// +kubebuilder:validation:Required
-	TargetPortNumber int32 `json:"targetPortNumber"`
+	// +required
+	TargetPortNumber int32 `json:"targetPortNumber,omitempty"`
 
 	// Extension configures an endpoint picker as an extension service.
-	ExtensionRef *Extension `json:"extensionRef,omitempty"`
+	// +optional
+	ExtensionRef Extension `json:"extensionRef,omitempty,omitzero"`
 }
 
 // Extension specifies how to configure an extension that runs the endpoint picker.
@@ -95,26 +100,26 @@ type Extension struct {
 	//
 	// +optional
 	// +kubebuilder:default=Service
-	Kind *Kind `json:"kind,omitempty"`
+	Kind Kind `json:"kind,omitempty"`
 
 	// Name is the name of the referent.
 	//
-	// +kubebuilder:validation:Required
-	Name ObjectName `json:"name"`
+	// +required
+	Name ObjectName `json:"name,omitempty"`
 
 	// The port number on the service running the extension. When unspecified,
 	// implementations SHOULD infer a default value of 9002 when the Kind is
 	// Service.
 	//
 	// +optional
-	PortNumber *PortNumber `json:"portNumber,omitempty"`
+	PortNumber PortNumber `json:"portNumber,omitempty"`
 
 	// Configures how the gateway handles the case when the extension is not responsive.
 	// Defaults to failClose.
 	//
 	// +optional
 	// +kubebuilder:default="FailClose"
-	FailureMode *ExtensionFailureMode `json:"failureMode"`
+	FailureMode ExtensionFailureMode `json:"failureMode,omitempty"`
 }
 
 // ExtensionFailureMode defines the options for how the gateway handles the case when the extension is not
@@ -130,6 +135,7 @@ const (
 )
 
 // InferencePoolStatus defines the observed state of InferencePool.
+// +kubebuilder:validation:MinProperties=1
 type InferencePoolStatus struct {
 	// Parents is a list of parent resources (usually Gateways) that are
 	// associated with the InferencePool, and the status of the InferencePool with respect to
@@ -144,14 +150,13 @@ type InferencePoolStatus struct {
 	//    and no other parents exist.
 	//
 	// +kubebuilder:validation:MaxItems=32
+	// +optional
+	// +listType=atomic
 	Parents []PoolStatus `json:"parent,omitempty"`
 }
 
 // PoolStatus defines the observed state of InferencePool from a Gateway.
 type PoolStatus struct {
-	// GatewayRef indicates the gateway that observed state of InferencePool.
-	GatewayRef ParentGatewayReference `json:"parentRef"`
-
 	// Conditions track the state of the InferencePool.
 	//
 	// Known condition types are:
@@ -165,6 +170,10 @@ type PoolStatus struct {
 	// +kubebuilder:validation:MaxItems=8
 	// +kubebuilder:default={{type: "Accepted", status: "Unknown", reason:"Pending", message:"Waiting for controller", lastTransitionTime: "1970-01-01T00:00:00Z"}}
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
+
+	// GatewayRef indicates the gateway that observed state of InferencePool.
+	// +required
+	GatewayRef ParentGatewayReference `json:"parentRef,omitzero"`
 }
 
 // InferencePoolConditionType is a type of condition for the InferencePool
@@ -246,21 +255,22 @@ type ParentGatewayReference struct {
 	//
 	// +optional
 	// +kubebuilder:default="gateway.networking.k8s.io"
-	Group *Group `json:"group"`
+	Group *Group `json:"group,omitempty"`
 
 	// Kind is kind of the referent. For example "Gateway".
 	//
 	// +optional
 	// +kubebuilder:default=Gateway
-	Kind *Kind `json:"kind"`
+	Kind Kind `json:"kind,omitempty"`
 
 	// Name is the name of the referent.
-	Name ObjectName `json:"name"`
+	// +required
+	Name ObjectName `json:"name,omitempty"`
 
 	// Namespace is the namespace of the referent.  If not present,
 	// the namespace of the referent is assumed to be the same as
 	// the namespace of the referring object.
 	//
 	// +optional
-	Namespace *Namespace `json:"namespace,omitempty"`
+	Namespace Namespace `json:"namespace,omitempty"`
 }

api/v1/shared_types.go

@@ -32,6 +32,7 @@ package v1
 //
 // * "example.com/bar" - "/" is an invalid character
 //
+// +kubebuilder:validation:MinLength=0
 // +kubebuilder:validation:MaxLength=253
 // +kubebuilder:validation:Pattern=`^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`
 type Group string
@@ -135,7 +136,7 @@ type LabelSelector struct {
 	// An object must match every label in this map to be selected.
 	// The matching logic is an AND operation on all entries.
 	//
-	// +kubebuilder:validation:Required
+	// +required
 	// +kubebuilder:validation:MaxItems=64
 	MatchLabels map[LabelKey]LabelValue `json:"matchLabels,omitempty" protobuf:"bytes,1,rep,name=matchLabels"`
 }

api/v1/zz_generated.deepcopy.go

@@ -58,7 +58,7 @@ func (dst *InferencePool) ConvertFrom(src *v1.InferencePool) error {
 	if src == nil {
 		return errors.New("src cannot be nil")
 	}
-	extensionRef, err := convertExtensionRefFromV1(src.Spec.ExtensionRef)
+	extensionRef, err := convertExtensionRefFromV1(&src.Spec.ExtensionRef)
 	if err != nil {
 		return err
 	}
@@ -102,15 +102,19 @@ func convertStatusFromV1(src *v1.InferencePoolStatus) (*InferencePoolStatus, err
 	return convert[InferencePoolStatus](u)
 }
 
-func convertExtensionRefToV1(src *Extension) (*v1.Extension, error) {
+func convertExtensionRefToV1(src *Extension) (v1.Extension, error) {
 	if src == nil {
-		return nil, nil
+		return v1.Extension{}, nil
 	}
 	u, err := toUnstructured(src)
 	if err != nil {
-		return nil, err
+		return v1.Extension{}, err
+	}
+	out, err := convert[v1.Extension](u)
+	if err != nil {
+		return v1.Extension{}, err
 	}
-	return convert[v1.Extension](u)
+	return *out, nil
 }
 
 func convertExtensionRefFromV1(src *v1.Extension) (*Extension, error) {

apix/v1alpha2/inferencepool_conversion.go

@@ -100,12 +100,12 @@ func TestInferencePoolConvertTo(t *testing.T) {
 						},
 					},
 					TargetPortNumber: 8080,
-					ExtensionRef: &v1.Extension{
+					ExtensionRef: v1.Extension{
 						Group:       &v1Group,
-						Kind:        &v1Kind,
+						Kind:        v1Kind,
 						Name:        "my-epp-service",
-						PortNumber:  &v1PortNumber,
-						FailureMode: &v1FailureMode,
+						PortNumber:  v1PortNumber,
+						FailureMode: v1FailureMode,
 					},
 				},
 				Status: v1.InferencePoolStatus{
@@ -235,12 +235,12 @@ func TestInferencePoolConvertFrom(t *testing.T) {
 						},
 					},
 					TargetPortNumber: 8080,
-					ExtensionRef: &v1.Extension{
+					ExtensionRef: v1.Extension{
 						Group:       &v1Group,
-						Kind:        &v1Kind,
+						Kind:        v1Kind,
 						Name:        "my-epp-service",
-						PortNumber:  &v1PortNumber,
-						FailureMode: &v1FailureMode,
+						PortNumber:  v1PortNumber,
+						FailureMode: v1FailureMode,
 					},
 				},
 				Status: v1.InferencePoolStatus{
@@ -348,6 +348,7 @@ func TestInferencePoolConvertFrom(t *testing.T) {
 						"app": "my-model-server",
 					},
 					TargetPortNumber: 8080,
+					ExtensionRef:     &Extension{},
 				},
 				Status: InferencePoolStatus{
 					Parents: []PoolStatus{