Proposal: Shift to a library-first architecture for v5

[vitorfloriano]

I get that Kubebuilder is first and foremost a CLI app and it has notably helped thousands of developers succesfully build their operators throughout the years.

BUT, it is also noticeable that Kubebuilder has seen very little adoption as a library. I can only think of the Operator-SDK as its biggest consumer.

One of the reasons, I think, is that the Kubebuilder API could be better documented as a library. The Kubebuilder Book is an excellent resource for end-users, but lacks the documentation for developers who want to use Kubebuilder as a library.

Talking about the structure, the deeply nested packages results in a not-so-nice developer experience. For example, the yaml package is nested inside pkg/config/store/yaml, so the user needs to import sigs.k8s.io/kubebuilder/v4/pkg/config/store/yaml, which is bit java-esque.

Also, I believe some identifiers were leaked into the public API and very little documentation has been provided for them. For example, the yaml package I just mentioned, which has already been imported by three other projects, as per what pkg.go.dev shows, has a lacking documentation. Some other packages, like the cmd, docs/utils and e2e/utils should not have been exposed in the API, I believe. If they are indeed meant for external usage, their documentation clearly needs improvements.

Talking about the docs, of all the thirty packages exposed in pkg/, only two (cli and go/v4/scaffolds) have a more detailed documentation.

Another reason for its low usage as a library is that Kubebuilder is not very discoverable in the most important directory for go packages and modules, pkg.go.dev. And when you do find it on pkg.go.dev, it is shown primarily as a command, not a package.

So, my proposal is:

Why not shift into a library-first architecture for v5? We could cleanup the API, deprecate identifiers that leaked, and improve the developer experience.

We could adopt the "Facade Pattern" and expose a new kubebuilder package to seal the API contract in a single package, similar to what controller-runtime already does, keep all the implementation in internal packages, and keep the CLI app into cmd/kubebuilder/, as it would be the most idiomatic place for the command, as a consumer of the Kubebuilder library.

We could move to the following structure:

├── kubebuilder.go        <-- the "facade" (the entry-point to the library) lives here
├── doc.go                <-- the kubebuilder package documentation lives here
├── cmd/
│   └── kubebuilder/
│       └── main.go       <-- the kubebuilder binary lives here
└── pkg/
    ├── cli/
    ├── plugins/
    ├── tests/
    └── .../

Or we could be more extreme and put the deprecated API into an internal:

├── kubebuilder.go
├── doc.go
├── cmd/
│   └── kubebuilder/
│       └── main.go
└── internal/
    ├── cli/
    ├── plugins/
    ├── tests/
    └── .../

This would help keep the API concise into one package, kubebuilder, improving maintenance and developer experience. Users of the library then would only have to import sigs.k8s.io/kubebuilder in their packages.

As a nice bonus, we would have a better idea of how many projects are actually using Kubebuilder as a library by looking at pkg.go.dev "Imported by" stats.

Would Kubebuilder still be "go-installable"?

Yes, but in a more verbose path. Currently, users type go install sigs.k8s.io/kubebuilder/v4 to install the CLI. If we shift to library first structure, users will have to type go install sigs.k8s.io/kubebuilder/v4/cmd/kubebuilder, which is a bit verbose, but still possible. With that in mind, I have to note that the current documentation doesn't recommend or even mention the go install method for installing Kubebuilder. The other installation methods would still work just as fine.

Anyway, thanks for reading through this and I look forward to hearing your opinions on this.

[camilamacedo86]

I think the ideas are good. We should improve the API.
So, POV:

• For All changes that are not breaking changes, please feel free to push.
• Protecting test/utils by moving it under an internal directory can be done as well, since that would be considered a bug fix rather than a breaking change.
• Then, for changes that would require a v5.x release, I’d suggest we list them as issues and track them over time. Once we have a meaningful set of changes and the timing is right, we can tackle them together more easily.

[vitorfloriano]

Protecting test/utils by moving it under an internal directory can be done as well, since that would be considered a bug fix rather than a breaking change.

@camilamacedo86 It seems that the test/e2e/utils package has already been imported by other projects, as per what pkg.go.dev import stats, so that would be a breaking change for them.

The cmd and hack/docs/utils packages seem to be safe to move to an internal, as they apparently have not been imported by any other project (yet).

That being said, I believe the safest path would be to treat all of them as breaking changes and deprecate them before any removal. We could add a // Deprecated: comment in all the abstractions that are meant to be removed from the API, and users would have a chance to refactor the code that depends on them. Also, I believe the Go LSP and some linters catch deprecations and warn users.

[camilamacedo86]

Thanks for putting this together. I agree the library UX and public API could be better (docs, discoverability, clearer what is public).

But I’d be very careful about starting a v5 just for cleanup or small improvements. Every major bump adds friction (breaking changes, slower upgrades, and some users staying behind). In the past, v2 → v3 → v4 was mostly forced by upstream/Kubernetes changes. Today v4 feels mature and stable, so honestly I hope we don’t need v5 in the next 2–3 years.

My suggestion:

• Do as much as we can in v4 when it’s non-breaking (docs, clarify the public API, move internal helpers under internal/, reduce “leaked” packages).
• For breaking ideas, track them as issues and build a backlog.
• If we ever must do a major release again, that backlog will make v5 worth the migration cost.

So: +1 to improvements, but v5 only when it really matters (or we’re forced), not for minor cleanup.

[vitorfloriano]

Agreed!

I'll start working on non-breaking changes that could improve DX and we can discuss them individually in the PRs. I'll also create some issues to keep track of the breaking changes.

Thanks for taking the time to analyze this proposal and for your feedback!