Repository files navigation

Kubebuilder is a framework for building Kubernetes APIs usingcustom resource definitions (CRDs).

Similar to web development frameworks such asRuby on Rails andSpringBoot,Kubebuilder increases velocity and reduces the complexity managed bydevelopers for rapidly building and publishing Kubernetes APIs in Go.It builds on top of the canonical techniques used to build the core Kubernetes APIs to provide simple abstractions that reduce boilerplate and toil.

Kubebuilder doesnot exist as an example tocopy-paste, but instead provides powerful libraries and toolsto simplify building and publishing Kubernetes APIs from scratch. Itprovides a plugin architecture allowing users to take advantage of optional helpersand features. To learn more about this see thePlugin section.

Kubebuilder is developed on top of thecontroller-runtime andcontroller-tools libraries.

Kubebuilder is extensible and can be used as a library in other projects.Operator-SDK is a good example of a project that uses Kubebuilder as a library.Operator-SDK uses the plugin feature to include non-Go operatorse.g. operator-sdk's Ansible and Helm-based language Operators.

To learn more seehow to create your own plugins.

It is strongly recommended that you use a released version. Release binaries are available on thereleases page.Follow theinstructions to install Kubebuilder.

See theGetting Started documentation.

Also, ensure that you check out theDeploy ImagePlugin. This plugin allows users to scaffold API/Controllers to deploy and manage anOperand (image) on the cluster following the guidelines and best practices. It abstracts thecomplexities of achieving this goal while allowing users to customize the generated code.

Check out the Kubebuilderbook.

• Kubebuilder Book:book.kubebuilder.io
• GitHub Repo:kubernetes-sigs/kubebuilder
• Slack channel:#kubebuilder
• Google Group:kubebuilder@googlegroups.com
• Design Documents:designs
• Plugin:plugins

Building Kubernetes tools and APIs involves making a lot of decisions and writing a lot of boilerplate.

To facilitate easily building Kubernetes APIs and tools using the canonical approach, this frameworkprovides a collection of Kubernetes development tools to minimize toil.

Kubebuilder attempts to facilitate the following developer workflow for building APIs

1. Create a new project directory
2. Create one or more resource APIs as CRDs and then add fields to the resources
3. Implement reconcile loops in controllers and watch additional resources
4. Test by running against a cluster (self-installs CRDs and starts controllers automatically)
5. Update bootstrapped integration tests to test new fields and business logic
6. Build and publish a container from the provided Dockerfile

Building APIs using CRDs, Controllers, and Admission Webhooks.

SeeDESIGN.md for the guiding principles of the various Kubebuilder projects.

TL;DR:

Provide clean library abstractions with clear and well-exampled go docs.

• Prefer using gointerfaces andlibraries over-relying oncode generation
• Prefer usingcode generation over1 time init of stubs
• Prefer1 time init of stubs over forked and modified boilerplate
• Never fork and modify boilerplate

• Provide higher-level libraries on top of low-level client libraries
  • Protect developers from breaking changes in low-level libraries
  • Start minimal and provide progressive discovery of functionality
  • Provide sane defaults and allow users to override when they exist
• Provide code generators to maintain common boilerplate that can't be addressed by interfaces
  • Driven off of// + comments
• Provide bootstrapping commands to initialize new packages

SeeVERSIONING.md.

• Bugs and Feature Requests:

  If you have what looks like a bug, or you would like to make a feature request, please use theGithub issue tracking system.Before you file an issue, please search existing issues to see if your issue is already covered.

• Slack

  For real-time discussion, you can join the#kubebuilder slack channel. Slack requires registration, but the Kubernetes team is an open invitation to anyone to register here. Feel free to come and ask any questions.

Contributions are greatly appreciated. The maintainers actively manage the issues list and try to highlight issues suitable for newcomers.The project follows the typical GitHub pull request model. SeeCONTRIBUTING.md for more details.Before starting any work, please either comment on an existing issue or file a new one.

Currently, Kubebuilder officially supports macOS and Linux platforms. If you are using a Windows OS, we recommend you read the instructions inhere.

Contributions towards supporting Windows are not planned.

Projects created by Kubebuilder contain aMakefile that installs tools at versions defined during project creation. The main tools included are:

• kustomize
• controller-gen
• setup-envtest

Additionally, these projects include ago.mod file specifying dependency versions.Kubebuilder relies oncontroller-runtime and its Go and Kubernetes dependencies.Therefore, the versions defined in theMakefile andgo.mod files are the ones that have been tested, supported, and recommended.

Each minor version of Kubebuilder is tested with a specific minor version of the client-go.While a Kubebuilder minor versionmay be compatible with other client-go minor versions,or other tools this compatibility is not guaranteed, supported, or tested.

The minimum Go version required by Kubebuilder is determined by the highest minimumGo version required by its dependencies. This is usually aligned with the minimumGo version required by the correspondingk8s.io/* dependencies.

Compatiblek8s.io/* versions, client-go versions, and minimum Go versions can be found in thego.modfile scaffolded for each project for eachtag release.

Example: For the4.1.1 release, the minimum Go version compatibility is1.22.You can refer to the samples in the testdata directory of the tag releasedv4.1.1,such as thego.mod file forproject-v4. You can also check the versions of the tools supported andtested for this release by examining theMakefile.

The following meetings happen biweekly:

• Kubebuilder Meeting

You are more than welcome to attend. For further info join tokubebuilder@googlegroups.com.Every month, our team meets on the first Thursday at 11:00 PT (Pacific Time) to discuss our progress and plan for the upcoming weeks.Please note that we have been syncing more frequently offline via Slack lately. However, if you add a topic to the agenda, we will hold the meeting as scheduled.Additionally, we can use this channel to demonstrate new features.