Proposal: Integrate kube-api-linter into Kubebuilder via golangci-lint

[camilamacedo86]

What do you want to happen?

Proposal: Integrate kube-api-linter into Kubebuilder

kube-api-linter is a custom linter designed to enforce Kubernetes API conventions and best practices. Since Kubebuilder is centered around building Kubernetes APIs and controllers, enforcing these standards early in the development process can help ensure high-quality, compliant APIs.

Integrating it into our tooling would provide users with immediate feedback about common issues or violations, leading to more robust and consistent operator development.

Even if we decide not to adopt it, this effort will still help us identify and possibly fix latent API issues.

---

✅ Why

• Enforces Kubernetes API best practices
• Helps users catch issues early
• Useful for both maintainers and contributors

---

⚙️ What

1. Update Kubebuilder’s .golangci.yml
   Add kube-api-linter to:
   https://github.com/kubernetes-sigs/kubebuilder/blob/master/.golangci.yml

2. Update the scaffolding logic

   • Add linter config to scaffolded .golangci.yml
   • See:
     golangci.go
init.go lines 181–183
   • Likely need a new template for the custom linter config block

3. Regenerate after changes

   make install
   make generate

---

➕ Pros

• Adds value immediately
• Aligns scaffolded projects with Kubernetes API standards
• Maintained under kubernetes-sigs → better trust/adoption
• Low risk (can be removed if needed; doesn't affect runtime behavior)

---

➖ Cons

• Adds an extra dependency
• May require tuning over time
• We generally aim to limit third-party dependencies to reduce long-term maintenance burden

---

🧪 Suggested Steps – Workflow

Phase 1: Kubebuilder (core project)

1. Create a PR to add kube-api-linter to Kubebuilder itself

   • This is safe to do directly in the main repo.
   • We can be more flexible here, but should still evaluate its usefulness.
   • We do not need to scaffold this part for users (yet).

2. Check for issues/failures in CI

   • Validate if the linter raises any violations.
   • Determine if they are real/useful and if fixes are needed.

3. If CI passes and the linter adds value, merge the PR

---

Phase 2: Scaffolding (generated user projects)

1. Create a separate PR to add kube-api-linter into the scaffolded .golangci.yml

   • Modify scaffold templates:
     • golangci.go
     • init.go

2. Check if scaffolded projects generate with issues

   • Test with real generated projects.

3. Fix any issues found

4. Evaluate critically

   • What is the value vs. risk of including this linter by default?
   • Why should we include or exclude it from the user scaffolds?
   • Does it provide immediate benefit without noise or confusion?

Only if the linter proves valuable and stable should we consider merging this into the default scaffolds.

Note: Adding it to the Kubebuilder CLI itself is more straightforward; adding it to the scaffolds created by Kubebuilder requires an evaluation to determine whether we should move forward.

---

Reference: https://golangci-lint.run/contributing/new-linters/

Extra Labels

No response

[camilamacedo86]

@sbueringer @JoelSpeed @guettli