feat: add kube api linter in kagent (#1759)

Add kube-api-linter: https://github.com/kubernetes-sigs/kube-api-linter

## Fix
* Added the `// +kubebuilder:optional` marker to the `Conditions` field
in the status struct to comply with Kubernetes API conventions and pass
kube-apilinter validation.
* Removed the conflicting `+kubebuilder:required` marker.
* Kept `+kubebuilder:default:=xxx` and added the explicit
`+kubebuilder:optional` marker to comply with Kubebuilder validation
rules.

---------

Signed-off-by: dongjiang <dongjiang1989@126.com>
Co-authored-by: Eitan Yarmush <eitan.yarmush@solo.io>

Author: dongjiang1989

.github/workflows/ci.yaml

@@ -304,11 +304,9 @@ jobs:
           go-version: "1.26"
           cache: true
           cache-dependency-path: go/go.sum
-      - name: golangci-lint
-        uses: golangci/golangci-lint-action@v9
-        with:
-          version: v2.11.3
-          working-directory: go
+      - name: golangci-lint 
+        working-directory: go
+        run: make lint
 
   python-test:
     env:

go/.golangci.yaml

@@ -17,6 +17,7 @@ linters:
     - importas
     - ineffassign
     - iotamixing
+    - kubeapilinter
     - makezero
     - misspell
     - modernize
@@ -26,6 +27,43 @@ linters:
     - unused
     - whitespace
   settings:
+    custom:
+      kubeapilinter:
+        path: "bin/kube-api-linter.so"
+        description: Kube API Linter lints Kube like APIs based on API conventions and best practices.
+        original-url: sigs.k8s.io/kube-api-linter
+        settings:
+          linters:
+            enable:
+              - "conflictingmarkers"
+              - "duplicatemarkers"
+              - "nofloats"
+              - "optionalorrequired"
+              - "statussubresource"
+              - "uniquemarkers"
+              - "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"
     depguard:
       rules:
         forbid-pkg-errors:
@@ -88,6 +126,10 @@ linters:
     paths:
       - zz_generated.*\.go$
       - .*conversion.*\.go$
+    rules:
+      - linters:
+          - kubeapilinter
+        path-except: "api/v1alpha"
 issues:
   max-issues-per-linter: 0
   max-same-issues: 0

go/Makefile

@@ -43,18 +43,29 @@ fmt: ## Run go fmt.
 vet: ## Run go vet.
 	go vet ./...
 
+KAL_SO = $(LOCALBIN)/kube-api-linter.so
+
 .PHONY: lint
-lint: golangci-lint ## Run golangci-lint.
+lint: golangci-lint $(KAL_SO) ## Run golangci-lint.
 	$(GOLANGCI_LINT) run
 
 .PHONY: lint-fix
-lint-fix: golangci-lint ## Run golangci-lint with auto-fix.
+lint-fix: golangci-lint $(KAL_SO) ## Run golangci-lint with auto-fix.
 	$(GOLANGCI_LINT) run --fix
 
 .PHONY: lint-config
 lint-config: golangci-lint ## Verify golangci-lint linter configuration.
 	$(GOLANGCI_LINT) config verify
 
+$(KAL_SO):
+	@mkdir -p $(LOCALBIN)
+	@echo "Building kube-api-linter plugin..."
+	@rm -rf $(LOCALBIN)/golangci-lint-src
+	@git clone --depth 1 --branch $(GOLANGCI_LINT_VERSION) --quiet https://github.com/golangci/golangci-lint.git $(LOCALBIN)/golangci-lint-src
+	@cd $(LOCALBIN)/golangci-lint-src && go get sigs.k8s.io/kube-api-linter@$(KAL_VERSION)
+	@cd $(LOCALBIN)/golangci-lint-src && go build -buildmode=plugin -o $(KAL_SO) sigs.k8s.io/kube-api-linter/pkg/plugin
+	@rm -rf $(LOCALBIN)/golangci-lint-src
+
 .PHONY: govulncheck
 govulncheck: ## Run govulncheck.
 	$(call go-install-tool,bin/govulncheck,golang.org/x/vuln/cmd/govulncheck,latest)
@@ -99,6 +110,8 @@ core/bin/kagent-windows-amd64.exe.sha256: core/bin/kagent-windows-amd64.exe
 .PHONY: clean
 clean:
 	rm -f core/bin/kagent* && mkdir -p core/bin
+	rm -f $(LOCALBIN)/kube-api-linter.so
+	rm -rf $(LOCALBIN)/golangci-lint-src
 
 .PHONY: build
 build: core/bin/kagent-linux-amd64.sha256 core/bin/kagent-linux-arm64.sha256 core/bin/kagent-darwin-amd64.sha256 core/bin/kagent-darwin-arm64.sha256 core/bin/kagent-windows-amd64.exe.sha256
@@ -136,6 +149,7 @@ ENVTEST_VERSION ?= $(shell go list -m -f "{{ .Version }}" sigs.k8s.io/controller
 #ENVTEST_K8S_VERSION is the version of Kubernetes to use for setting up ENVTEST binaries (i.e. 1.31)
 ENVTEST_K8S_VERSION ?= $(shell go list -m -f "{{ .Version }}" k8s.io/api | awk -F'[v.]' '{printf "1.%d", $$3}')
 GOLANGCI_LINT_VERSION ?= v2.11.3
+KAL_VERSION ?= v0.0.0-20260423112246-3fa174937a6b
 SQLC_VERSION ?= v1.30.0
 BUF ?= $(LOCALBIN)/buf
 BUF_VERSION ?= v1.52.1

go/api/config/crd/bases/kagent.dev_agents.yaml

@@ -2257,14 +2257,10 @@ spec:
                           type: string
                       type: object
                     type:
-                      allOf:
-                      - enum:
-                        - McpServer
-                        - Agent
-                      - enum:
-                        - McpServer
-                        - Agent
                       description: ToolProviderType represents the tool provider type
+                      enum:
+                      - McpServer
+                      - Agent
                       type: string
                   type: object
                   x-kubernetes-validations:
@@ -2347,9 +2343,6 @@ spec:
               observedGeneration:
                 format: int64
                 type: integer
-            required:
-            - configHash
-            - observedGeneration
             type: object
         type: object
     served: true
@@ -13052,19 +13045,15 @@ spec:
                         type: array
                     type: object
                   runtime:
-                    allOf:
-                    - enum:
-                      - python
-                      - go
-                    - enum:
-                      - python
-                      - go
                     default: python
                     description: |-
                       Runtime specifies which ADK implementation to use for this agent.
                       - "python": Uses the Python ADK (default, slower startup, full feature set)
                       - "go": Uses the Go ADK (faster startup, most features supported)
                       The runtime determines both the container image and readiness probe configuration.
+                    enum:
+                    - python
+                    - go
                     type: string
                   stream:
                     description: |-
@@ -13215,15 +13204,11 @@ spec:
                             rule: '!has(self.requireApproval) || self.requireApproval.all(x,
                               has(self.toolNames) && x in self.toolNames)'
                         type:
-                          allOf:
-                          - enum:
-                            - McpServer
-                            - Agent
-                          - enum:
-                            - McpServer
-                            - Agent
                           description: ToolProviderType represents the tool provider
                             type
+                          enum:
+                          - McpServer
+                          - Agent
                           type: string
                       type: object
                       x-kubernetes-validations:
@@ -13553,18 +13538,12 @@ spec:
                     type: array
                 type: object
               type:
-                allOf:
-                - enum:
-                  - Declarative
-                  - BYO
-                - enum:
-                  - Declarative
-                  - BYO
                 default: Declarative
                 description: AgentType represents the agent type
+                enum:
+                - Declarative
+                - BYO
                 type: string
-            required:
-            - type
             type: object
             x-kubernetes-validations:
             - message: type must be specified
@@ -13637,8 +13616,6 @@ spec:
               observedGeneration:
                 format: int64
                 type: integer
-            required:
-            - observedGeneration
             type: object
         type: object
     served: true

go/api/config/crd/bases/kagent.dev_memories.yaml

@@ -86,8 +86,6 @@ spec:
                 enum:
                 - Pinecone
                 type: string
-            required:
-            - provider
             type: object
           status:
             description: MemoryStatus defines the observed state of Memory.
@@ -151,9 +149,6 @@ spec:
               observedGeneration:
                 format: int64
                 type: integer
-            required:
-            - conditions
-            - observedGeneration
             type: object
         type: object
     served: true

go/api/config/crd/bases/kagent.dev_modelconfigs.yaml

@@ -259,7 +259,6 @@ spec:
                 type: string
             required:
             - model
-            - provider
             type: object
             x-kubernetes-validations:
             - message: provider.openAI must be nil if the provider is not OpenAI
@@ -340,9 +339,6 @@ spec:
               observedGeneration:
                 format: int64
                 type: integer
-            required:
-            - conditions
-            - observedGeneration
             type: object
         type: object
     served: true
@@ -606,13 +602,10 @@ spec:
                         - audience
                         type: object
                       type:
-                        allOf:
-                        - enum:
-                          - GDCHServiceAccount
-                        - enum:
-                          - GDCHServiceAccount
                         description: TokenExchangeType identifies the token exchange
                           mechanism
+                        enum:
+                        - GDCHServiceAccount
                         type: string
                     required:
                     - type
@@ -691,7 +684,6 @@ spec:
                 type: object
             required:
             - model
-            - provider
             type: object
             x-kubernetes-validations:
             - message: provider.openAI must be nil if the provider is not OpenAI
@@ -821,9 +813,6 @@ spec:
                   this model config detect changes to these secrets and restart if
                   necessary.
                 type: string
-            required:
-            - conditions
-            - observedGeneration
             type: object
         type: object
     served: true

go/api/config/crd/bases/kagent.dev_remotemcpservers.yaml

@@ -262,9 +262,6 @@ spec:
                   Important: Run "make" to regenerate code after modifying this file
                 format: int64
                 type: integer
-            required:
-            - conditions
-            - observedGeneration
             type: object
         type: object
     served: true

go/api/config/crd/bases/kagent.dev_sandboxagents.yaml

@@ -10703,19 +10703,15 @@ spec:
                         type: array
                     type: object
                   runtime:
-                    allOf:
-                    - enum:
-                      - python
-                      - go
-                    - enum:
-                      - python
-                      - go
                     default: python
                     description: |-
                       Runtime specifies which ADK implementation to use for this agent.
                       - "python": Uses the Python ADK (default, slower startup, full feature set)
                       - "go": Uses the Go ADK (faster startup, most features supported)
                       The runtime determines both the container image and readiness probe configuration.
+                    enum:
+                    - python
+                    - go
                     type: string
                   stream:
                     description: |-
@@ -10866,15 +10862,11 @@ spec:
                             rule: '!has(self.requireApproval) || self.requireApproval.all(x,
                               has(self.toolNames) && x in self.toolNames)'
                         type:
-                          allOf:
-                          - enum:
-                            - McpServer
-                            - Agent
-                          - enum:
-                            - McpServer
-                            - Agent
                           description: ToolProviderType represents the tool provider
                             type
+                          enum:
+                          - McpServer
+                          - Agent
                           type: string
                       type: object
                       x-kubernetes-validations:
@@ -11204,18 +11196,12 @@ spec:
                     type: array
                 type: object
               type:
-                allOf:
-                - enum:
-                  - Declarative
-                  - BYO
-                - enum:
-                  - Declarative
-                  - BYO
                 default: Declarative
                 description: AgentType represents the agent type
+                enum:
+                - Declarative
+                - BYO
                 type: string
-            required:
-            - type
             type: object
             x-kubernetes-validations:
             - message: type must be specified
@@ -11288,8 +11274,6 @@ spec:
               observedGeneration:
                 format: int64
                 type: integer
-            required:
-            - observedGeneration
             type: object
         type: object
     served: true

go/api/config/crd/bases/kagent.dev_toolservers.yaml

@@ -321,9 +321,6 @@ spec:
                   Important: Run "make" to regenerate code after modifying this file
                 format: int64
                 type: integer
-            required:
-            - conditions
-            - observedGeneration
             type: object
         type: object
     served: true