(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

@@ -32,6 +32,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,6 +45,7 @@ jobs:
         with:
           version: v2.1.6
           working-directory: ${{ matrix.folder }}
+          install-mode: goinstall
           args: --config .golangci.yml ./...
       - name: Run linter via makefile target
         working-directory: ${{ matrix.folder }}

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

@@ -43,11 +43,7 @@ help: ## Display this help.
 
 .PHONY: manifests
 manifests: controller-gen ## Generate WebhookConfiguration, ClusterRole and CustomResourceDefinition objects.
-	# Note that the option maxDescLen=0 was added in the default scaffold in order to sort out the issue
-	# Too long: must have at most 262144 bytes. By using kubectl apply to create / update resources an annotation
-	# is created by K8s API to store the latest version of the resource ( kubectl.kubernetes.io/last-applied-configuration).
-	# However, it has a size limit and if the CRD is too big with so many long descriptions as this one it will cause the failure.
-	$(CONTROLLER_GEN) rbac:roleName=manager-role crd:maxDescLen=0 webhook paths="./..." output:crd:artifacts:config=config/crd/bases
+	$(CONTROLLER_GEN) rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
 
 .PHONY: generate
 generate: controller-gen ## Generate code containing DeepCopy, DeepCopyInto, and DeepCopyObject method implementations.
@@ -89,7 +85,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 +215,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

@@ -65,8 +65,9 @@ import (
 // CronJobSpec defines the desired state of CronJob.
 type CronJobSpec struct {
 	// +kubebuilder:validation:MinLength=0
+	// +kubebuilder:validation:Required
 
-	// The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
+	// schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
 	Schedule string `json:"schedule"`
 
 	// +kubebuilder:validation:Minimum=0
@@ -82,14 +83,17 @@ type CronJobSpec struct {
 	// - "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.
+	// +kubebuilder:validation:Required
+
+	// jobTemplate defines the job that will be created when executing a CronJob.
 	JobTemplate batchv1.JobTemplateSpec `json:"jobTemplate"`
 
 	// +kubebuilder:validation:Minimum=0
@@ -169,11 +173,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.
+	// +optional
+	Spec *CronJobSpec `json:"spec,omitempty"`
+
+	// status defines the observed state of CronJob.
+	// +optional
+	Status *CronJobStatus `json:"status,omitempty"`
 }
 
 // +kubebuilder:object:root=true