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

[afzal442]

/assign

[afzal442]

@camilamacedo86 I take this up!

[camilamacedo86]

We did an experimental usage internally, and you can take a look at the PR for more details.
-> #4887

The purpose of the project is very cool 🎉 and could be very beneficial for the community. However, it’s not quite mature enough yet for us to add it to the Kubebuilder scaffolds.

• 1. The project currently has no official releases.
• 2. I’ve opened a couple of issues here: https://github.com/kubernetes-sigs/kube-api-linter/issues?q=is%3Aissue%20state%3Aopen%20author%3Acamilamacedo86
• 3. Looking through the existing issues, we can see many useful checks are planned, which is great to see.
• 4. I could not make it work with golangci github action: https://github.com/kubernetes-sigs/kubebuilder/actions/runs/15901556991/job/44845553251?pr=4887 we would need to see if that is possible, To add in the default scaffold that must work too.

So, once the project becomes more mature, we can definitely revisit this idea and evaluate adding it to the default scaffold. 🙂

c/c @JoelSpeed

[JoelSpeed]

The project currently has no official releases.

There are definitely a few changes I want to get through in terms of the way the project is organised which I'd expect to get in before an initial release, so we can keep an eye on this.

I’ve opened a couple of issues here

I actually believe both of the current open issues are behaving as expected

I could not make it work with golangci github action

There are two modes, module and plugin. The plugin mode is preferred, but requires that the golangci-lint binary and the KAL binary are built in the same environment with the same dependencies, which is not how the golangci github action works, and would need to use something custom to achieve I think. I haven't tried to make them work together. The module approach in use by cluster api might be a better path forward for Kubebuilder if you are supplying github workflows

[camilamacedo86]

Hi @JoelSpeed
Thank you very much for the reply.

I actually believe both of the current open issues are behaving as expected

We can speak from there.

There are two modes, module and plugin.

The info in the README is no longer valid with GolangCI 2x
I push a PR with the changes: kubernetes-sigs/kube-api-linter#109
Just to let you know.

[camilamacedo86]

Hi @JoelSpeed,

After reviewing the answers and giving it more thought, I’ve changed my mind 😊
I now strongly believe we should definitely add the linter as soon as possible.

Without it, we're not really promoting best practices effectively.

I’ve already started working on it: #4888
(There’s some effort involved — we need to fix the samples and a few other things.)

I just want to share with you.