feat: add kube-api-linter checker

Makefile

@@ -1,5 +1,5 @@
 .PHONY: all
-all: fix-go-generate build lint-go test-unit toc-verify
+all: fix-go-generate build lint-go lint-api test-unit toc-verify
 
 .PHONY: fix-go-generate
 fix-go-generate:
@@ -52,6 +52,10 @@ test-e2e-benchmarks:
 lint-go:
 	./dev/tools/lint-go
 
+.PHONY: lint-api
+lint-api:
+	./dev/tools/lint-api
+
 # Location of your local k8s.io repo (can be overridden: make release-promote TAG=v0.1.0 K8S_IO_DIR=../other/k8s.io)
 K8S_IO_DIR ?= ../../kubernetes/k8s.io
 
@@ -97,4 +101,9 @@ toc-update:
 
 .PHONY: toc-verify
 toc-verify:
-	./dev/tools/verify-toc
+	./dev/tools/verify-toc
+
+.PHONY: clean
+clean:
+	rm -rf dev/tools/tmp
+	rm -rf bin/manager

api/v1alpha1/sandbox_types.go

@@ -33,14 +33,14 @@ const (
 )
 
 type PodMetadata struct {
-	// Map of string keys and values that can be used to organize and categorize
+	// labels defines the map of string keys and values that can be used to organize and categorize
 	// (scope and select) objects. May match selectors of replication controllers
 	// and services.
 	// More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
 	// +optional
 	Labels map[string]string `json:"labels,omitempty" protobuf:"bytes,1,rep,name=labels"`
 
-	// Annotations is an unstructured key value map stored with a resource that may be
+	// annotations is an unstructured key value map stored with a resource that may be
 	// set by external tools to store and retrieve arbitrary metadata. They are not
 	// queryable and should be preserved when modifying objects.
 	// More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations
@@ -49,7 +49,7 @@ type PodMetadata struct {
 }
 
 type EmbeddedObjectMetadata struct {
-	// Name must be unique within a namespace. Is required when creating resources, although
+	// name must be unique within a namespace. Is required when creating resources, although
 	// some resources may allow a client to request the generation of an appropriate name
 	// automatically. Name is primarily intended for creation idempotence and configuration
 	// definition.
@@ -58,14 +58,14 @@ type EmbeddedObjectMetadata struct {
 	// +optional
 	Name string `json:"name,omitempty" protobuf:"bytes,1,opt,name=name"`
 
-	// Map of string keys and values that can be used to organize and categorize
+	// labels defines the map of string keys and values that can be used to organize and categorize
 	// (scope and select) objects. May match selectors of replication controllers
 	// and services.
 	// More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
 	// +optional
 	Labels map[string]string `json:"labels,omitempty" protobuf:"bytes,1,rep,name=labels"`
 
-	// Annotations is an unstructured key value map stored with a resource that may be
+	// annotations is an unstructured key value map stored with a resource that may be
 	// set by external tools to store and retrieve arbitrary metadata. They are not
 	// queryable and should be preserved when modifying objects.
 	// More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations
@@ -74,22 +74,22 @@ type EmbeddedObjectMetadata struct {
 }
 
 type PodTemplate struct {
-	// Spec is the Pod's spec
-	// +kubebuilder:validation:Required
+	// spec is the Pod's spec
+	// +required
 	Spec corev1.PodSpec `json:"spec" protobuf:"bytes,3,opt,name=spec"`
 
-	// Metadata is the Pod's metadata. Only labels and annotations are used.
-	// +kubebuilder:validation:Optional
+	// metadata is the Pod's metadata. Only labels and annotations are used.
+	// +optional
 	ObjectMeta PodMetadata `json:"metadata" protobuf:"bytes,3,opt,name=metadata"`
 }
 
 type PersistentVolumeClaimTemplate struct {
-	// Metadata is the PVC's metadata.
-	// +kubebuilder:validation:Optional
+	// metadata is the PVC's metadata.
+	// +optional
 	EmbeddedObjectMetadata `json:"metadata" protobuf:"bytes,3,opt,name=metadata"`
 
-	// Spec is the PVC's spec
-	// +kubebuilder:validation:Required
+	// spec is the PVC's spec
+	// +required
 	Spec corev1.PersistentVolumeClaimSpec `json:"spec" protobuf:"bytes,3,opt,name=spec"`
 }
 
@@ -98,21 +98,20 @@ type SandboxSpec struct {
 	// The following markers will use OpenAPI v3 schema to validate the value
 	// More info: https://book.kubebuilder.io/reference/markers/crd-validation.html
 
-	// PodTemplate describes the pod spec that will be used to create an agent sandbox.
-	// +kubebuilder:validation:Required
+	// podTemplate describes the pod spec that will be used to create an agent sandbox.
+	// +required
 	PodTemplate PodTemplate `json:"podTemplate" protobuf:"bytes,3,opt,name=podTemplate"`
 
-	// VolumeClaimTemplates is a list of claims that the sandbox pod is allowed to reference.
+	// volumeClaimTemplates is a list of claims that the sandbox pod is allowed to reference.
 	// Every claim in this list must have at least one matching access mode with a provisioner volume.
 	// +optional
-	// +kubebuilder:validation:Optional
 	VolumeClaimTemplates []PersistentVolumeClaimTemplate `json:"volumeClaimTemplates,omitempty" protobuf:"bytes,4,rep,name=volumeClaimTemplates"`
 
 	// Lifecycle defines when and how the sandbox should be shut down.
 	// +optional
 	Lifecycle `json:",inline"`
 
-	// Replicas is the number of desired replicas.
+	// replicas is the number of desired replicas.
 	// The only allowed values are 0 and 1.
 	// Defaults to 1.
 	// +kubebuilder:validation:Minimum=0
@@ -135,12 +134,12 @@ const (
 
 // Lifecycle defines the lifecycle management for the Sandbox.
 type Lifecycle struct {
-	// ShutdownTime is the absolute time when the sandbox expires.
+	// shutdownTime is the absolute time when the sandbox expires.
 	// +kubebuilder:validation:Format="date-time"
 	// +optional
 	ShutdownTime *metav1.Time `json:"shutdownTime,omitempty"`
 
-	// ShutdownPolicy determines if the Sandbox resource itself should be deleted when it expires.
+	// shutdownPolicy determines if the Sandbox resource itself should be deleted when it expires.
 	// Underlying resources(Pods, Services) are always deleted on expiry.
 	// +kubebuilder:default=Retain
 	// +optional
@@ -149,21 +148,26 @@ type Lifecycle struct {
 
 // SandboxStatus defines the observed state of Sandbox.
 type SandboxStatus struct {
-	// FQDN that is valid for default cluster settings
+	// serviceFQDN that is valid for default cluster settings
 	// Limitation: Hardcoded to the domain .cluster.local
 	// e.g. sandbox-example.default.svc.cluster.local
+	// +optional
 	ServiceFQDN string `json:"serviceFQDN,omitempty"`
 
-	// e.g. sandbox-example
+	// service is a sandbox-example
+	// +optional
 	Service string `json:"service,omitempty"`
 
-	// status conditions array
+	// conditions defines the status conditions array
+	// +optional
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
-	// Replicas is the number of actual replicas.
-	Replicas int32 `json:"replicas"`
+	// replicas is the number of actual replicas.
+	// +kubebuilder:validation:Minimum=0
+	// +optional
+	Replicas int32 `json:"replicas,omitempty"`
 
-	// LabelSelector is the label selector for pods.
+	// selector is the label selector for pods.
 	// +optional
 	LabelSelector string `json:"selector,omitempty"`
 }

dev/ci/presubmits/lint-api

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+# Copyright 2025 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import sys
+
+from shared import utils
+
+
+def main():
+    """ invokes go kube api linter """
+    return utils.run_dev_tool("lint-api")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dev/ci/presubmits/lint-go

@@ -25,3 +25,4 @@ def main():
 
 if __name__ == "__main__":
     sys.exit(main())
+

dev/tools/.custom-gcl.yaml

@@ -0,0 +1,6 @@
+version: v2.10.1
+name: golangci-kube-api-linter
+destination: ./tmp/bin/
+plugins:
+- module: 'sigs.k8s.io/kube-api-linter'
+  version: v0.0.0-20260206102632-39e3d06a2850

dev/tools/.golangci-kal.yml

@@ -0,0 +1,69 @@
+# This file holds the Kube-API-Linter (KAL) configuration.
+# KAL ensures that our Custom Resource Definitions meet the Kubernetes API
+# conventions (as much as possible).
+#
+# The linters documentation is at
+# https://github.com/kubernetes-sigs/kube-api-linter/blob/main/docs/linters.md
+version: "2"
+run:
+  go: "1.26"
+  allow-parallel-runners: true
+linters:
+  default: none
+  enable:
+    - kubeapilinter
+  settings:
+    custom:
+      kubeapilinter:
+        type: module
+        description: KAL is the Kube-API-Linter and lints Custom Resource Definitions (CRDs) based on API conventions and best practices.
+        settings:
+          linters:
+            # We configure the list of enabled linters explicitly.
+            # Whenever a new linter is added, it should not break the backward
+            # compatibility of existing APIs (at least for v1 APIs).
+            enable:
+              - "nobools"
+              - "commentstart"
+              - "conflictingmarkers"
+              - "duplicatemarkers"
+              - "nofloats"
+              - "optionalorrequired"
+              - "statussubresource"
+              - "uniquemarkers"
+              - "jsontags"
+              - "statusoptional"
+              - "nophase"
+              - "nonullable"
+              - "forbiddenmarkers"
+              - "nomaps"
+            disable:
+              - "*"
+          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"
+            forbiddenmarkers:
+              markers:
+                - identifier: "+kubebuilder:pruning:PreserveUnknownFields"
+                - identifier: "+kubebuilder:validation:XPreserveUnknownFields"
+                - identifier: "+kubebuilder:validation:items:XPreserveUnknownFields"
+                - identifier: "+kubebuilder:validation:EmbeddedResource"
+                - identifier: "+kubebuilder:validation:XEmbeddedResource"
+                - identifier: "+kubebuilder:validation:items:XEmbeddedResource"
+  exclusions:
+    generated: strict
+    paths:
+      # Exclude test files and generated code.
+      - _test\.go
+      - zz_generated.*\.go$
+    rules:
+    # KAL only validates the API folders for CRD client generation.
+    - path-except: "api/.*"
+      linters:
+        - kubeapilinter
+

dev/tools/build-kal

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Copyright 2025 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o nounset
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OUTPUT_DIR="${SCRIPT_DIR}/tmp/bin"
+OUTPUT_BINARY="${OUTPUT_DIR}/golangci-kube-api-linter"
+
+mkdir -p "${OUTPUT_DIR}"
+
+echo "Building golangci-kube-api-linter..."
+(cd "${SCRIPT_DIR}" && go tool -modfile "${SCRIPT_DIR}/go.mod" golangci-lint custom)
+
+if [ -f "${OUTPUT_BINARY}" ]; then
+    echo "Build complete. Binary: ${OUTPUT_BINARY}"
+else
+    echo "Build failed: binary not found at ${OUTPUT_BINARY}"
+    exit 1
+fi
+
+echo "Build complete. Run with:"
+echo "  ${OUTPUT_BINARY} run --config=${SCRIPT_DIR}/.golangci-kal.yml"