kubernetes-sigs · camilamacedo86 · Jul 20, 2025
diff --git a/Makefile b/Makefile
@@ -131,8 +131,18 @@ yamllint:
     	docker run --rm $$(tty -s && echo "-it" || echo) -v $(PWD):/data cytopia/yamllint:latest $$files -d "{extends: relaxed, rules: {line-length: {max: 120}}}" --no-warnings
 
 .PHONY: golangci-lint
-golangci-lint:
-	$(call go-install-tool,$(GOLANGCI_LINT),github.com/golangci/golangci-lint/v2/cmd/golangci-lint,${GOLANGCI_LINT_VERSION})
+golangci-lint: $(GOLANGCI_LINT)
+
+$(GOLANGCI_LINT_BASE): $(LOCALBIN)
+	$(call go-install-tool,$(GOLANGCI_LINT_BASE),github.com/golangci/golangci-lint/v2/cmd/golangci-lint,${GOLANGCI_LINT_VERSION})
+
+$(GOLANGCI_LINT): $(GOLANGCI_LINT_BASE) .custom-gcl.yml
+	@echo "Installing custom golangci-lint plugins..."
+	@$(GOLANGCI_LINT_BASE) custom || { \
+		echo "golangci-lint custom failed. Cleaning up..."; \
+		rm -f $(GOLANGCI_LINT_BASE); \
+		exit 1; \
+	}
 
 .PHONY: apidiff
 apidiff: go-apidiff ## Run the go-apidiff to verify any API differences compared with origin/master
@@ -229,7 +239,8 @@ update-k8s-version: ## Update Kubernetes API version in version.go and .goreleas
 
 ## Tool Binaries
 GO_APIDIFF ?= $(LOCALBIN)/go-apidiff
-GOLANGCI_LINT ?= $(LOCALBIN)/golangci-lint
+GOLANGCI_LINT_BASE ?= $(LOCALBIN)/golangci-lint
+GOLANGCI_LINT ?= $(LOCALBIN)/golangci-lint-kube-api
 
 ## Tool Versions
 GO_APIDIFF_VERSION ?= v0.6.1

diff --git a/docs/book/src/cronjob-tutorial/testdata/project/.custom-gcl.yml b/docs/book/src/cronjob-tutorial/testdata/project/.custom-gcl.yml
@@ -0,0 +1,7 @@
+version: v2.5.0
+name: golangci-lint-kube-api
+destination: ./bin
+
+plugins:
+  - module: sigs.k8s.io/kube-api-linter
+    version: latest
diff --git a/docs/book/src/cronjob-tutorial/testdata/project/.github/workflows/lint.yml b/docs/book/src/cronjob-tutorial/testdata/project/.github/workflows/lint.yml
@@ -17,7 +17,13 @@ jobs:
         with:
           go-version-file: go.mod
 
+      - name: Check linter configuration
+        run: make lint-config
+
       - name: Run linter
         uses: golangci/golangci-lint-action@v8
         with:
           version: v2.5.0
+
+      - name: Run lint target
+        run: make lint
diff --git a/docs/book/src/cronjob-tutorial/testdata/project/.golangci.yml b/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:
+        type: module
+        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$

diff --git a/docs/book/src/cronjob-tutorial/testdata/project/Makefile b/docs/book/src/cronjob-tutorial/testdata/project/Makefile
@@ -188,7 +188,8 @@ KIND ?= kind
 KUSTOMIZE ?= $(LOCALBIN)/kustomize
 CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
 ENVTEST ?= $(LOCALBIN)/setup-envtest
-GOLANGCI_LINT = $(LOCALBIN)/golangci-lint
+GOLANGCI_LINT_BASE = $(LOCALBIN)/golangci-lint
+GOLANGCI_LINT = $(LOCALBIN)/golangci-lint-kube-api
 
 ## Tool Versions
 KUSTOMIZE_VERSION ?= v5.7.1
@@ -230,8 +231,17 @@ $(ENVTEST): $(LOCALBIN)
 
 .PHONY: golangci-lint
 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))
+
+$(GOLANGCI_LINT_BASE): $(LOCALBIN)
+	$(call go-install-tool,$(GOLANGCI_LINT_BASE),github.com/golangci/golangci-lint/v2/cmd/golangci-lint,$(GOLANGCI_LINT_VERSION))
+
+$(GOLANGCI_LINT): $(GOLANGCI_LINT_BASE) .custom-gcl.yml
+	@echo "Running golangci-lint custom..."
+	@$(GOLANGCI_LINT_BASE) custom || { \
+		echo "golangci-lint failed. Cleaning up..."; \
+		rm -f $(GOLANGCI_LINT_BASE); \
+		exit 1; \
+	}
 
 # 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

diff --git a/docs/book/src/getting-started/testdata/project/.custom-gcl.yml b/docs/book/src/getting-started/testdata/project/.custom-gcl.yml
@@ -0,0 +1,7 @@
+version: v2.5.0
+name: golangci-lint-kube-api
+destination: ./bin
+
+plugins:
+  - module: sigs.k8s.io/kube-api-linter
+    version: latest
diff --git a/docs/book/src/getting-started/testdata/project/.github/workflows/lint.yml b/docs/book/src/getting-started/testdata/project/.github/workflows/lint.yml
@@ -17,7 +17,13 @@ jobs:
         with:
           go-version-file: go.mod
 
+      - name: Check linter configuration
+        run: make lint-config
+
       - name: Run linter
         uses: golangci/golangci-lint-action@v8
         with:
           version: v2.5.0
+
+      - name: Run lint target
+        run: make lint
diff --git a/docs/book/src/getting-started/testdata/project/.golangci.yml b/docs/book/src/getting-started/testdata/project/.golangci.yml
@@ -21,11 +21,20 @@ linters:
     - unconvert
     - unparam
     - unused
+    - kubeapilinter
   settings:
     revive:
       rules:
         - name: comment-spacings
         - name: import-shadowing
+    custom:
+      kubeapilinter:
+        type: module
+        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$

diff --git a/docs/book/src/getting-started/testdata/project/Makefile b/docs/book/src/getting-started/testdata/project/Makefile
@@ -184,7 +184,8 @@ KIND ?= kind
 KUSTOMIZE ?= $(LOCALBIN)/kustomize
 CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
 ENVTEST ?= $(LOCALBIN)/setup-envtest
-GOLANGCI_LINT = $(LOCALBIN)/golangci-lint
+GOLANGCI_LINT_BASE = $(LOCALBIN)/golangci-lint
+GOLANGCI_LINT = $(LOCALBIN)/golangci-lint-kube-api
 
 ## Tool Versions
 KUSTOMIZE_VERSION ?= v5.7.1
@@ -226,8 +227,17 @@ $(ENVTEST): $(LOCALBIN)
 
 .PHONY: golangci-lint
 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))
+
+$(GOLANGCI_LINT_BASE): $(LOCALBIN)
+	$(call go-install-tool,$(GOLANGCI_LINT_BASE),github.com/golangci/golangci-lint/v2/cmd/golangci-lint,$(GOLANGCI_LINT_VERSION))
+
+$(GOLANGCI_LINT): $(GOLANGCI_LINT_BASE) .custom-gcl.yml
+	@echo "Running golangci-lint custom..."
+	@$(GOLANGCI_LINT_BASE) custom || { \
+		echo "golangci-lint failed. Cleaning up..."; \
+		rm -f $(GOLANGCI_LINT_BASE); \
+		exit 1; \
+	}
 
 # 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

diff --git a/docs/book/src/multiversion-tutorial/testdata/project/.custom-gcl.yml b/docs/book/src/multiversion-tutorial/testdata/project/.custom-gcl.yml
@@ -0,0 +1,7 @@
+version: v2.5.0
+name: golangci-lint-kube-api
+destination: ./bin
+
+plugins:
+  - module: sigs.k8s.io/kube-api-linter
+    version: latest
diff --git a/docs/book/src/multiversion-tutorial/testdata/project/.github/workflows/lint.yml b/docs/book/src/multiversion-tutorial/testdata/project/.github/workflows/lint.yml
@@ -17,7 +17,13 @@ jobs:
         with:
           go-version-file: go.mod
 
+      - name: Check linter configuration
+        run: make lint-config
+
       - name: Run linter
         uses: golangci/golangci-lint-action@v8
         with:
           version: v2.5.0
+
+      - name: Run lint target
+        run: make lint
diff --git a/docs/book/src/multiversion-tutorial/testdata/project/.golangci.yml b/docs/book/src/multiversion-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:
+        type: module
+        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$

diff --git a/docs/book/src/multiversion-tutorial/testdata/project/Makefile b/docs/book/src/multiversion-tutorial/testdata/project/Makefile
@@ -188,7 +188,8 @@ KIND ?= kind
 KUSTOMIZE ?= $(LOCALBIN)/kustomize
 CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
 ENVTEST ?= $(LOCALBIN)/setup-envtest
-GOLANGCI_LINT = $(LOCALBIN)/golangci-lint
+GOLANGCI_LINT_BASE = $(LOCALBIN)/golangci-lint
+GOLANGCI_LINT = $(LOCALBIN)/golangci-lint-kube-api
 
 ## Tool Versions
 KUSTOMIZE_VERSION ?= v5.7.1
@@ -230,8 +231,17 @@ $(ENVTEST): $(LOCALBIN)
 
 .PHONY: golangci-lint
 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))
+
+$(GOLANGCI_LINT_BASE): $(LOCALBIN)
+	$(call go-install-tool,$(GOLANGCI_LINT_BASE),github.com/golangci/golangci-lint/v2/cmd/golangci-lint,$(GOLANGCI_LINT_VERSION))
+
+$(GOLANGCI_LINT): $(GOLANGCI_LINT_BASE) .custom-gcl.yml
+	@echo "Running golangci-lint custom..."
+	@$(GOLANGCI_LINT_BASE) custom || { \
+		echo "golangci-lint failed. Cleaning up..."; \
+		rm -f $(GOLANGCI_LINT_BASE); \
+		exit 1; \
+	}
 
 # 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

diff --git a/pkg/plugins/golang/v4/scaffolds/init.go b/pkg/plugins/golang/v4/scaffolds/init.go
@@ -176,6 +176,7 @@ func (s *initScaffolder) Scaffold() error {
 		&templates.DockerIgnore{},
 		&templates.Readme{CommandName: s.commandName},
 		&templates.Golangci{},
+		&templates.CustomGcl{GolangciLintVersion: GolangciLintVersion},
 		&e2e.Test{},
 		&e2e.WebhookTestUpdater{WireWebhook: false},
 		&e2e.SuiteTest{},

diff --git a/pkg/plugins/golang/v4/scaffolds/internal/templates/custom-gcl.go b/pkg/plugins/golang/v4/scaffolds/internal/templates/custom-gcl.go
@@ -0,0 +1,54 @@
+/*
+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.
+*/
+
+package templates
+
+import (
+	"sigs.k8s.io/kubebuilder/v4/pkg/machinery"
+)
+
+var _ machinery.Template = &CustomGcl{}
+
+// CustomGcl scaffolds a file ..custom-gcl.yaml which define KAL configuration to install
+type CustomGcl struct {
+	machinery.TemplateMixin
+	machinery.ProjectNameMixin
+
+	// GolangciLintVersion is the golangci-lint version used to build the custom binary
+	GolangciLintVersion string
+}
+
+// SetTemplateDefaults implements machinery.Template
+func (f *CustomGcl) SetTemplateDefaults() error {
+	if f.Path == "" {
+		f.Path = ".custom-gcl.yml"
+	}
+
+	f.TemplateBody = customGCLTemplate
+
+	f.IfExistsAction = machinery.SkipFile
+
+	return nil
+}
+
+const customGCLTemplate = `version: {{ .GolangciLintVersion }}
+name: golangci-lint-kube-api
+destination: ./bin
+
+plugins:
+  - module: sigs.k8s.io/kube-api-linter
+    version: latest
+`
diff --git a/pkg/plugins/golang/v4/scaffolds/internal/templates/github/lint.go b/pkg/plugins/golang/v4/scaffolds/internal/templates/github/lint.go
@@ -65,8 +65,14 @@ jobs:
         with:
           go-version-file: go.mod
 
+      - name: Check linter configuration
+        run: make lint-config
+
       - name: Run linter
         uses: golangci/golangci-lint-action@v8
         with:
           version: {{ .GolangciLintVersion }}
+
+      - name: Run lint target
+        run: make lint
 `
diff --git a/pkg/plugins/golang/v4/scaffolds/internal/templates/golangci.go b/pkg/plugins/golang/v4/scaffolds/internal/templates/golangci.go
@@ -64,11 +64,20 @@ linters:
     - unconvert
     - unparam
     - unused
+    - kubeapilinter
   settings:
     revive:
       rules:
         - name: comment-spacings
         - name: import-shadowing
+    custom:
+      kubeapilinter:
+        type: module
+        description: "Kube API Linter plugin"
+        original-url: "sigs.k8s.io/kube-api-linter"
+        settings:
+          linters: {}
+          lintersConfig: {}
   exclusions:
     generated: lax
     rules:
@@ -79,6 +88,9 @@ linters:
           - dupl
           - lll
         path: internal/*
+      - path-except: "^api/"
+        linters:
+          - kubeapilinter
     paths:
       - third_party$
       - builtin$