Viewing legacy documentation for Kubebuilder, check out the latest documentation instead.
Project Creation and Structure
Go package Structure
Kubebuilder projects contain 3 important packages.
cmd package contains the manager main program. Manager is responsible for initializing
shared dependencies and starting / stopping Controllers. Users typically
will not need to edit this package and can rely on the scaffolding.
cmd package is scaffolded automatically by
pkg/apis/... packages contains the API resource definitions.
Users edit the
*_types.go files under this director to implement their API definitions.
Each resource lives in a
pkg/apis package is scaffolded automatically by
kubebuilder create api when creating a Resource.
pkg/controller/... packages contain the Controller implementations.
Users edit the
*_controller.go files under this directory to implement their Controllers.
pkg/controller package is scaffolded automatically by
kubebuilder create api when creating a Controller.
Additional directories and files
In addition to the packages above, a Kubebuilder project has several other directories and files.
A Makefile is created with targets to build, test, run and deploy the controller artifacts for development as well as production workflows
A Dockerfile is scaffolded to build a container image for your Manager.
Kubebuilder creates yaml config for installing the CRDs and related objects under config/.
API reference documentation, user defined API samples and API conceptual documentation go here.
To prepend boilerplate comments at the top of generated and bootstrapped files,
add the boilerplate to a
hack/boilerplate.go.txt file before creating a project.
Create a new project
Create a new kubebuilder project. This will automatically initialize the vendored go libraries that will be required to build your project.
$ kubebuilder init --domain k8s.io --license apache2 --owner "The Kubernetes Authors"
Create a new API (Resource)
Create the *_types.go file and controller.go files.
For more on resources and controllers see What Is A Resource and What Is A Controller
$ kubebuilder create api --group mygroup --version v1beta1 --kind MyKind
Run your manager locally against a Kubernetes cluster
Users may run the controller-manager binary locally against a Kubernetes cluster. This will install the APIs into the cluster and begin watching and reconciling the resources.
# Create a minikube cluster $ minikube start # Install the CRDs into the cluster $ make install # Build and run the manager $ make run
Create an instance
Create a new instance of your Resource. Observe the manager logs printed to the console after creating the object.
$ kubectl apply -f sample/<resource>.yaml
Deploying your manager in a Kubernetes cluster
Users can run the controller-manager in a Kubernetes cluster.
# Create a docker image $ make docker-build IMG=<img-name> # Push the docker image to a configured container registry $ make docker-push IMG=<img-name> # Deploy the controller manager manifests to the cluster. $ make deploy