(go/v4,deploy-image/alpha-v1) feat: integrate kube-api-linter and fix scaffolds

- Add support for kube-api-linter to validate Kubernetes API definitions
  More info: https://github.com/kubernetes-sigs/kube-api-linter
- Fix all tutorials (getting-started, cronjob, multiversion) to comply with lint rules
- Update all plugins scaffolds to according to rules
- Adjust GitHub Actions to build and run the new custom linter in CI

Author: camilamacedo86

.github/workflows/lint-sample.yml

@@ -12,6 +12,7 @@ jobs:
   lint-samples:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
         folder: [
           "testdata/project-v4",
@@ -32,6 +33,11 @@ jobs:
       - name: Prepare ${{ matrix.folder }}
         working-directory: ${{ matrix.folder }}
         run: go mod tidy
+      - name: Build kubeapilinter
+        working-directory: ${{ matrix.folder }}
+        run: make kube-api-linter
+        env:
+          CGO_ENABLED: 1
       - name: Check linter configuration
         working-directory: ${{ matrix.folder }}
         run: make lint-config
@@ -40,7 +46,7 @@ jobs:
         with:
           version: v2.1.6
           working-directory: ${{ matrix.folder }}
-          args: --config .golangci.yml ./...
+          install-mode: goinstall
       - name: Run linter via makefile target
         working-directory: ${{ matrix.folder }}
         run: make lint

docs/book/src/cronjob-tutorial/testdata/project/.github/workflows/lint.yml

@@ -21,3 +21,4 @@ jobs:
         uses: golangci/golangci-lint-action@v8
         with:
           version: v2.1.6
+          install-mode: goinstall

docs/book/src/cronjob-tutorial/testdata/project/.golangci.yml

@@ -21,11 +21,20 @@ linters:
     - unconvert
     - unparam
     - unused
+    - kubeapilinter
   settings:
     revive:
       rules:
         - name: comment-spacings
         - name: import-shadowing
+    custom:
+      kubeapilinter:
+        path: "./bin/kube-api-linter.so"
+        description: "Kube API Linter plugin"
+        original-url: "sigs.k8s.io/kube-api-linter"
+        settings:
+          linters: { }
+          lintersConfig: { }
   exclusions:
     generated: lax
     rules:
@@ -36,6 +45,9 @@ linters:
           - dupl
           - lll
         path: internal/*
+      - path-except: "^api/"
+        linters:
+          - kubeapilinter
     paths:
       - third_party$
       - builtin$

docs/book/src/cronjob-tutorial/testdata/project/Makefile

@@ -89,7 +89,7 @@ cleanup-test-e2e: ## Tear down the Kind cluster used for e2e tests
 	@$(KIND) delete cluster --name $(KIND_CLUSTER)
 
 .PHONY: lint
-lint: golangci-lint ## Run golangci-lint linter
+lint: golangci-lint kube-api-linter ## Run golangci-lint linter
 	$(GOLANGCI_LINT) run
 
 .PHONY: lint-fix
@@ -219,6 +219,23 @@ golangci-lint: $(GOLANGCI_LINT) ## Download golangci-lint locally if necessary.
 $(GOLANGCI_LINT): $(LOCALBIN)
 	$(call go-install-tool,$(GOLANGCI_LINT),github.com/golangci/golangci-lint/v2/cmd/golangci-lint,$(GOLANGCI_LINT_VERSION))
 
+# To lint Kubernetes API definitions.
+# More info: https://github.com/kubernetes-sigs/kube-api-linter
+KUBE_API_LINTER_PLUGIN := $(LOCALBIN)/kube-api-linter.so
+KUBE_API_LINTER_BUILD_DIR := ./hack/kube-api-linter
+
+.PHONY: kube-api-linter
+kube-api-linter: $(KUBE_API_LINTER_PLUGIN) ## Build the kube-api-linter plugin
+$(KUBE_API_LINTER_PLUGIN): $(KUBE_API_LINTER_BUILD_DIR)/go.mod
+	cd $(KUBE_API_LINTER_BUILD_DIR) && \
+	go build -buildmode=plugin -o "$(abspath $(KUBE_API_LINTER_PLUGIN))" sigs.k8s.io/kube-api-linter/pkg/plugin
+$(KUBE_API_LINTER_BUILD_DIR)/go.mod:
+	@echo "Setting up local module for kube-api-linter plugin..."
+	mkdir -p $(KUBE_API_LINTER_BUILD_DIR)
+	cd $(KUBE_API_LINTER_BUILD_DIR) && \
+	go mod init local-kube-api-linter && \
+	go get sigs.k8s.io/kube-api-linter@latest
+
 # go-install-tool will 'go install' any package with custom target and name of binary, if it doesn't exist
 # $1 - target path with name of binary
 # $2 - package url which can be installed

docs/book/src/cronjob-tutorial/testdata/project/api/v1/cronjob_types.go

@@ -64,46 +64,45 @@ import (
 
 // CronJobSpec defines the desired state of CronJob.
 type CronJobSpec struct {
+	// schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
 	// +kubebuilder:validation:MinLength=0
-
-	// The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
+	// +required
 	Schedule string `json:"schedule"`
 
-	// +kubebuilder:validation:Minimum=0
-
-	// Optional deadline in seconds for starting the job if it misses scheduled
+	// startingDeadlineSeconds defines in seconds for starting the job if it misses scheduled
 	// time for any reason.  Missed jobs executions will be counted as failed ones.
 	// +optional
+	// +kubebuilder:validation:Minimum=0
 	StartingDeadlineSeconds *int64 `json:"startingDeadlineSeconds,omitempty"`
 
-	// Specifies how to treat concurrent executions of a Job.
+	// concurrencyPolicy specifies how to treat concurrent executions of a Job.
 	// Valid values are:
 	// - "Allow" (default): allows CronJobs to run concurrently;
 	// - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet;
 	// - "Replace": cancels currently running job and replaces it with a new one
 	// +optional
-	ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`
+	// +kubebuilder:default:=Allow
+	ConcurrencyPolicy *ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`
 
-	// This flag tells the controller to suspend subsequent executions, it does
+	// suspend tells the controller to suspend subsequent executions, it does
 	// not apply to already started executions.  Defaults to false.
 	// +optional
 	Suspend *bool `json:"suspend,omitempty"`
 
-	// Specifies the job that will be created when executing a CronJob.
+	// jobTemplate defines the job that will be created when executing a CronJob.
+	// +required
 	JobTemplate batchv1.JobTemplateSpec `json:"jobTemplate"`
 
-	// +kubebuilder:validation:Minimum=0
-
-	// The number of successful finished jobs to retain.
+	// successfulJobsHistoryLimit defines the number of successful finished jobs to retain.
 	// This is a pointer to distinguish between explicit zero and not specified.
 	// +optional
-	SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`
-
 	// +kubebuilder:validation:Minimum=0
+	SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`
 
-	// The number of failed finished jobs to retain.
+	// failedJobsHistoryLimit defines the number of failed finished jobs to retain.
 	// This is a pointer to distinguish between explicit zero and not specified.
 	// +optional
+	// +kubebuilder:validation:Minimum=0
 	FailedJobsHistoryLimit *int32 `json:"failedJobsHistoryLimit,omitempty"`
 }
 
@@ -147,11 +146,11 @@ type CronJobStatus struct {
 	// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
 	// Important: Run "make" to regenerate code after modifying this file
 
-	// A list of pointers to currently running jobs.
+	// active defines a list of pointers to currently running jobs.
 	// +optional
 	Active []corev1.ObjectReference `json:"active,omitempty"`
 
-	// Information when was the last time the job was successfully scheduled.
+	// lastScheduleTime defines the when was the last time the job was successfully scheduled.
 	// +optional
 	LastScheduleTime *metav1.Time `json:"lastScheduleTime,omitempty"`
 }
@@ -169,11 +168,19 @@ type CronJobStatus struct {
 type CronJob struct {
 	/*
 	 */
-	metav1.TypeMeta   `json:",inline"`
+	metav1.TypeMeta `json:",inline"`
+
+	// metadata is a standard object metadata.
+	// +optional
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec   CronJobSpec   `json:"spec,omitempty"`
-	Status CronJobStatus `json:"status,omitempty"`
+	// spec defines the desired state of CronJob.
+	// +required
+	Spec CronJobSpec `json:"spec"`
+
+	// status defines the observed state of CronJob.
+	// +optional
+	Status *CronJobStatus `json:"status,omitempty"`
 }
 
 // +kubebuilder:object:root=true

docs/book/src/cronjob-tutorial/testdata/project/api/v1/zz_generated.deepcopy.go

@@ -27,6 +27,7 @@ spec:
           spec:
             properties:
               concurrencyPolicy:
+                default: Allow
                 enum:
                 - Allow
                 - Forbid
@@ -3840,6 +3841,8 @@ spec:
                 format: date-time
                 type: string
             type: object
+        required:
+        - spec
         type: object
     served: true
     storage: true

docs/book/src/cronjob-tutorial/testdata/project/config/crd/bases/batch.tutorial.kubebuilder.io_cronjobs.yaml

@@ -33,6 +33,7 @@ spec:
           spec:
             properties:
               concurrencyPolicy:
+                default: Allow
                 enum:
                 - Allow
                 - Forbid
@@ -3846,6 +3847,8 @@ spec:
                 format: date-time
                 type: string
             type: object
+        required:
+        - spec
         type: object
     served: true
     storage: true

docs/book/src/cronjob-tutorial/testdata/project/dist/chart/templates/crd/batch.tutorial.kubebuilder.io_cronjobs.yaml

@@ -35,6 +35,7 @@ spec:
           spec:
             properties:
               concurrencyPolicy:
+                default: Allow
                 enum:
                 - Allow
                 - Forbid
@@ -3848,6 +3849,8 @@ spec:
                 format: date-time
                 type: string
             type: object
+        required:
+        - spec
         type: object
     served: true
     storage: true

docs/book/src/cronjob-tutorial/testdata/project/dist/install.yaml

@@ -9,6 +9,7 @@ require (
 	k8s.io/api v0.33.0
 	k8s.io/apimachinery v0.33.0
 	k8s.io/client-go v0.33.0
+	k8s.io/utils v0.0.0-20241104100929-3ea5e8cea738
 	sigs.k8s.io/controller-runtime v0.21.0
 )
 
@@ -89,7 +90,6 @@ require (
 	k8s.io/component-base v0.33.0 // indirect
 	k8s.io/klog/v2 v2.130.1 // indirect
 	k8s.io/kube-openapi v0.0.0-20250318190949-c8a335a9a2ff // indirect
-	k8s.io/utils v0.0.0-20241104100929-3ea5e8cea738 // indirect
 	sigs.k8s.io/apiserver-network-proxy/konnectivity-client v0.31.2 // indirect
 	sigs.k8s.io/json v0.0.0-20241010143419-9aa6b5e7a4b3 // indirect
 	sigs.k8s.io/randfill v1.0.0 // indirect

docs/book/src/cronjob-tutorial/testdata/project/go.mod

@@ -441,13 +441,17 @@ func (r *CronJobReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ct
 	*/
 	// figure out how to run this job -- concurrency policy might forbid us from running
 	// multiple at the same time...
-	if cronJob.Spec.ConcurrencyPolicy == batchv1.ForbidConcurrent && len(activeJobs) > 0 {
+	policy := batchv1.AllowConcurrent
+	if cronJob.Spec.ConcurrencyPolicy != nil {
+		policy = *cronJob.Spec.ConcurrencyPolicy
+	}
+	if policy == batchv1.ForbidConcurrent && len(activeJobs) > 0 {
 		log.V(1).Info("concurrency policy blocks concurrent runs, skipping", "num active", len(activeJobs))
 		return scheduledResult, nil
 	}
 
 	// ...or instruct us to replace existing ones...
-	if cronJob.Spec.ConcurrencyPolicy == batchv1.ReplaceConcurrent {
+	if cronJob.Spec.ConcurrencyPolicy != nil && *cronJob.Spec.ConcurrencyPolicy == batchv1.ReplaceConcurrent {
 		for _, activeJob := range activeJobs {
 			// we don't care if the job was already deleted
 			if err := r.Delete(ctx, activeJob, client.PropagationPolicy(metav1.DeletePropagationBackground)); client.IgnoreNotFound(err) != nil {

docs/book/src/cronjob-tutorial/testdata/project/internal/controller/cronjob_controller.go

@@ -26,6 +26,7 @@ import (
 	"k8s.io/apimachinery/pkg/runtime/schema"
 	validationutils "k8s.io/apimachinery/pkg/util/validation"
 	"k8s.io/apimachinery/pkg/util/validation/field"
+	"k8s.io/utils/ptr"
 
 	"k8s.io/apimachinery/pkg/runtime"
 	ctrl "sigs.k8s.io/controller-runtime"
@@ -113,8 +114,8 @@ func (d *CronJobCustomDefaulter) Default(_ context.Context, obj runtime.Object)
 
 // applyDefaults applies default values to CronJob fields.
 func (d *CronJobCustomDefaulter) applyDefaults(cronJob *batchv1.CronJob) {
-	if cronJob.Spec.ConcurrencyPolicy == "" {
-		cronJob.Spec.ConcurrencyPolicy = d.DefaultConcurrencyPolicy
+	if cronJob.Spec.ConcurrencyPolicy == nil {
+		cronJob.Spec.ConcurrencyPolicy = ptr.To(d.DefaultConcurrencyPolicy)
 	}
 	if cronJob.Spec.Suspend == nil {
 		cronJob.Spec.Suspend = new(bool)

docs/book/src/cronjob-tutorial/testdata/project/internal/webhook/v1/cronjob_webhook.go

@@ -22,6 +22,7 @@ import (
 
 	batchv1 "tutorial.kubebuilder.io/project/api/v1"
 	// TODO (user): Add any additional imports if needed
+	"k8s.io/utils/ptr"
 )
 
 var _ = Describe("CronJob Webhook", func() {
@@ -39,9 +40,9 @@ var _ = Describe("CronJob Webhook", func() {
 		obj = &batchv1.CronJob{
 			Spec: batchv1.CronJobSpec{
 				Schedule:                   schedule,
-				ConcurrencyPolicy:          batchv1.AllowConcurrent,
-				SuccessfulJobsHistoryLimit: new(int32),
-				FailedJobsHistoryLimit:     new(int32),
+				ConcurrencyPolicy:          ptr.To(batchv1.AllowConcurrent),
+				SuccessfulJobsHistoryLimit: ptr.To(int32(3)),
+				FailedJobsHistoryLimit:     ptr.To(int32(1)),
 			},
 		}
 		*obj.Spec.SuccessfulJobsHistoryLimit = 3
@@ -50,9 +51,9 @@ var _ = Describe("CronJob Webhook", func() {
 		oldObj = &batchv1.CronJob{
 			Spec: batchv1.CronJobSpec{
 				Schedule:                   schedule,
-				ConcurrencyPolicy:          batchv1.AllowConcurrent,
-				SuccessfulJobsHistoryLimit: new(int32),
-				FailedJobsHistoryLimit:     new(int32),
+				ConcurrencyPolicy:          ptr.To(batchv1.AllowConcurrent),
+				SuccessfulJobsHistoryLimit: ptr.To(int32(3)),
+				FailedJobsHistoryLimit:     ptr.To(int32(1)),
 			},
 		}
 		*oldObj.Spec.SuccessfulJobsHistoryLimit = 3
@@ -77,7 +78,7 @@ var _ = Describe("CronJob Webhook", func() {
 	Context("When creating CronJob under Defaulting Webhook", func() {
 		It("Should apply defaults when a required field is empty", func() {
 			By("simulating a scenario where defaults should be applied")
-			obj.Spec.ConcurrencyPolicy = ""           // This should default to AllowConcurrent
+			obj.Spec.ConcurrencyPolicy = nil          // This should default to AllowConcurrent
 			obj.Spec.Suspend = nil                    // This should default to false
 			obj.Spec.SuccessfulJobsHistoryLimit = nil // This should default to 3
 			obj.Spec.FailedJobsHistoryLimit = nil     // This should default to 1
@@ -86,15 +87,15 @@ var _ = Describe("CronJob Webhook", func() {
 			_ = defaulter.Default(ctx, obj)
 
 			By("checking that the default values are set")
-			Expect(obj.Spec.ConcurrencyPolicy).To(Equal(batchv1.AllowConcurrent), "Expected ConcurrencyPolicy to default to AllowConcurrent")
+			Expect(obj.Spec.ConcurrencyPolicy).To(HaveValue(Equal(batchv1.AllowConcurrent)), "Expected ConcurrencyPolicy to default to AllowConcurrent")
 			Expect(*obj.Spec.Suspend).To(BeFalse(), "Expected Suspend to default to false")
 			Expect(*obj.Spec.SuccessfulJobsHistoryLimit).To(Equal(int32(3)), "Expected SuccessfulJobsHistoryLimit to default to 3")
 			Expect(*obj.Spec.FailedJobsHistoryLimit).To(Equal(int32(1)), "Expected FailedJobsHistoryLimit to default to 1")
 		})
 
 		It("Should not overwrite fields that are already set", func() {
 			By("setting fields that would normally get a default")
-			obj.Spec.ConcurrencyPolicy = batchv1.ForbidConcurrent
+			obj.Spec.ConcurrencyPolicy = ptr.To(batchv1.ForbidConcurrent)
 			obj.Spec.Suspend = new(bool)
 			*obj.Spec.Suspend = true
 			obj.Spec.SuccessfulJobsHistoryLimit = new(int32)
@@ -106,7 +107,7 @@ var _ = Describe("CronJob Webhook", func() {
 			_ = defaulter.Default(ctx, obj)
 
 			By("checking that the fields were not overwritten")
-			Expect(obj.Spec.ConcurrencyPolicy).To(Equal(batchv1.ForbidConcurrent), "Expected ConcurrencyPolicy to retain its set value")
+			Expect(obj.Spec.ConcurrencyPolicy).To(HaveValue(Equal(batchv1.ForbidConcurrent)), "Expected ConcurrencyPolicy to retain its set value")
 			Expect(*obj.Spec.Suspend).To(BeTrue(), "Expected Suspend to retain its set value")
 			Expect(*obj.Spec.SuccessfulJobsHistoryLimit).To(Equal(int32(5)), "Expected SuccessfulJobsHistoryLimit to retain its set value")
 			Expect(*obj.Spec.FailedJobsHistoryLimit).To(Equal(int32(2)), "Expected FailedJobsHistoryLimit to retain its set value")