The perception that Kubebuilder is an "anti-pattern" in Go

[chinglinwen]

can it become more go library like in the future(by compose library), less of marker, scaffold, replace by interface etc?

I'd like no constraint on project structure, say currently, it scaffold all crd types into the same package, what if I want it to place in separate package by domain logic, not by types.

current scaffold way, make things hard to do(separate package by domain, pure go test), for each new kind create.

in order to do such way, one may not use kubebuilder cli at all, or use in the half way ( with thin wrapper etc), is it possible that kubebuilder can have better ideas?

note the following are express well by ai for my perception. post it here, to bring more thought, I see it's hard to do such change, just provide some feedbacks here.

---

The perception that Kubebuilder is an "anti-pattern" in Go often stems from its heavy reliance on code generation and scaffolding rather than standard Go library conventions. 

While it is the standard tool for building Kubernetes Operators, its design choices clash with typical Go philosophy in several ways: 

1. Code Generation vs. Composable Libraries

Go developers generally prefer small, composable libraries. Kubebuilder operates as a scaffolding tool that generates a large amount of boilerplate code.

• The Issue: Once the code is generated, the developer "owns" it. Updating the underlying tool can make migrating or merging your custom logic back into a new scaffold difficult. The Kubebuilder Book +1
• "Framework" Feel: Although built on the controller-runtime library, the CLI-driven nature makes it feel like a heavy framework, which many Go purists avoid in favor of more explicit code.

2. Magic Comments (Markers)

Kubebuilder uses special comments (e.g., // +kubebuilder:validation:Pattern=...) to define CRD validation, RBAC, and deep-copy logic. The Kubebuilder Book +3

• The Issue: These are effectively "compiler directives" hidden in comments. This is often considered an anti-pattern because the actual behavior of the program is determined by metadata that isn't visible to the Go compiler or standard linting tools. 

3. Opaque Abstractions

The tool abstracts away the complexities of informers, caches, and the reconciliation loop.

• The Issue: For beginners, this "magic" can lead to a lack of understanding of how Kubernetes actually works under the hood. If the generated logic doesn't fit a specific use case (like needing a dynamic client), developers often find themselves fighting the scaffold. 

4. Opinionated Project Structure

Kubebuilder enforces a very specific directory layout (e.g., api/, controllers/, cmd/main.go). The Kubebuilder Book +3

• The Issue: This can be restrictive for teams that have their own established Go project structures or need to integrate the operator into an existing codebase. The Kubebuilder Book

Summary Table: Go Idioms vs. Kubebuilder

Go Philosophy	Kubebuilder Approach
Explicit is better than implicit	Heavy use of "magic" comments for logic
Prefer libraries over frameworks	Scaffolds a rigid project structure
Code should be readable by humans	Generates thousands of lines of boilerplate
Minimize dependencies	Introduces many deep dependencies on K8s internals

Would you like to explore lighter alternatives to Kubebuilder for writing controllers, such as using controller-runtime directly?

[camilamacedo86]

Hi @chinglinwen,

Thank you for taking the time to raise these points and share your perspective.

First of all, we are always open to feedback, suggestions, and improvements. That said, a significant portion of the content shared here appears to be AI-generated and includes several inaccuracies and misconceptions about Kubebuilder’s purpose and design. I’ll try to clarify the main points below.

---

💬 On the “anti-pattern” perception

Many of the concerns raised seem to stem from misunderstandings or disagreement with the intended purpose of the project.

Kubebuilder is not trying to be a minimal Go library. It is a framework and toolkit designed to accelerate development, reduce boilerplate, and standardize patterns across Kubernetes operators.

If those goals don’t align with a specific use case, alternative approaches (like using controller-runtime directly) are valid—but that does not make Kubebuilder an anti-pattern. In fact, using controller-runtime directly would typically require you to implement the same patterns and structure that Kubebuilder already provides, but without its tooling, scaffolding, and ecosystem support.

---

📚 Kubebuilder Book references

• The Kubebuilder Book +1, +2, +3 refer to documentation for older, no longer supported versions.
• book-v4 corresponds to the current, supported version and should be used as the authoritative reference.

---

🧩 “Go developers prefer small, composable libraries”

“Kubebuilder operates as a scaffolding tool that generates a large amount of boilerplate code.”

This characterization is not accurate.

Kubebuilder generates a base project scaffold, but the resulting project is composable by design:

• Users extend functionality by running commands such as:
  • create api
  • create webhook
• Additional functionality is enabled via plugins:
  • https://book.kubebuilder.io/plugins/available-plugins.html
• Developers are free to add custom code and structure on top.

The scaffold represents a common starting point that covers the majority of use cases, not a rigid or closed system.

---

🧠 “Opaque abstractions”

“The tool abstracts away informers, caches, and the reconciliation loop.”

This is incorrect.

Kubebuilder itself does not abstract these concepts away. It builds on top of the controller-runtime library, which—like any library—provides abstractions to reduce complexity.

---

🏷️ “Magic comments (markers)”

Please refer to the Kubebuilder README:

Kubebuilder is a framework for building Kubernetes APIs using CRDs. It increases velocity and reduces complexity by providing abstractions and tooling on top of the canonical Kubernetes API patterns.

Markers are part of the controller-tools ecosystem and are used to declaratively define metadata such as validation and RBAC.

The goal is not hidden behavior, but to reduce boilerplate, keep definitions close to the API types, and align with upstream Kubernetes patterns.

---

🏗️ “Opinionated project structure”

“Kubebuilder enforces a very specific directory layout.”

Kubebuilder follows:

• Go project layout best practices
  https://github.com/golang-standards/project-layout
• Kubernetes operator conventions

See also:
https://book.kubebuilder.io/plugins/extending.html

So while the structure may appear “opinionated**,” it is based on community standards, real-world usage, and ecosystem feedback.**

Additionally:

• Features like kubebuilder alpha update and the AutoUpdate Plugin (uses GitHub Actions)](https://book.kubebuilder.io/plugins/available/autoupdate-v1-alpha) help projects stay aligned with ecosystem changes without losing your customisations on top.

---

Regards

The Issue: This can be restrictive for teams that have their own established Go project structures or need to integrate the operator into an existing codebase. The Kubebuilder Book

Can you provide an example about what you are trying to say here?
That does not seems to be coerent . It is hard to follow that.
What do you mean here?

Happy to continue the discussion—especially if you can share concrete examples of the challenges you’re facing and based in your analysis.

Thanks again for the feedback. For now, I am closing this as resolved.
If you have further suggestions or specific concerns, please feel free to open new issues. I would kindly ask that you open one issue per topic, each including a concrete use case or example so we can better understand and address it.

[chinglinwen]

Thanks for the clarification, I'll restructure the api and controller to organize by domain logic, it's doable with manual change; agree to close.

[camilamacedo86]

I'll restructure the api and controller to organize by domain logic,

The scaffold is actually designed to support exactly that.

It follows the same structural patterns used in Kubernetes itself, organizing APIs and controllers in a way that aligns with domain-driven design and how the ecosystem builds and maintains components.

Also, as a helpful resource, you might find this useful to ramp up more quickly:
https://dev4devs.com/2025/09/04/operators-where-to-start-shortcut-5-hour-plan/

If you have any suggestions or ideas for improvements, please don’t hesitate to reach out or open an issue—we’re always happy to hear feedback.