Quick Start
This Quick Start guide will cover:
Prerequisites
- go version v1.24.5+
- docker version 17.03+.
- kubectl version v1.11.3+.
- Access to a Kubernetes v1.11.3+ cluster.
Installation
Install kubebuilder:
# download kubebuilder and install locally.
curl -L -o kubebuilder "https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go env GOARCH)"
chmod +x kubebuilder && sudo mv kubebuilder /usr/local/bin/
Create a Project
Create a directory, and then run the init command inside of it to initialize a new project. Follows an example.
mkdir -p ~/projects/guestbook
cd ~/projects/guestbook
kubebuilder init --domain my.domain --repo my.domain/guestbook
Create an API
Run the following command to create a new API (group/version) as webapp/v1
and the new Kind(CRD) Guestbook
on it:
kubebuilder create api --group webapp --version v1 --kind Guestbook
OPTIONAL: Edit the API definition and the reconciliation business logic. For more info see Designing an API and What’s in a Controller.
If you are editing the API definitions, generate the manifests such as Custom Resources (CRs) or Custom Resource Definitions (CRDs) using
make manifests
Click here to see an example. (api/v1/guestbook_types.go)
// GuestbookSpec defines the desired state of Guestbook
type GuestbookSpec struct {
// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
// Important: Run "make" to regenerate code after modifying this file
// Quantity of instances
// +kubebuilder:validation:Minimum=1
// +kubebuilder:validation:Maximum=10
Size int32 `json:"size"`
// Name of the ConfigMap for GuestbookSpec's configuration
// +kubebuilder:validation:MaxLength=15
// +kubebuilder:validation:MinLength=1
ConfigMapName string `json:"configMapName"`
// +kubebuilder:validation:Enum=Phone;Address;Name
Type string `json:"type,omitempty"`
}
// GuestbookStatus defines the observed state of Guestbook
type GuestbookStatus struct {
// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
// Important: Run "make" to regenerate code after modifying this file
// PodName of the active Guestbook node.
Active string `json:"active"`
// PodNames of the standby Guestbook nodes.
Standby []string `json:"standby"`
}
// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:resource:scope=Cluster
// Guestbook is the Schema for the guestbooks API
type Guestbook struct {
metav1.TypeMeta `json:",inline"`
metav1.ObjectMeta `json:"metadata,omitempty"`
Spec GuestbookSpec `json:"spec,omitempty"`
Status GuestbookStatus `json:"status,omitempty"`
}
Test It Out
You’ll need a Kubernetes cluster to run against. You can use KinD to get a local cluster for testing, or run against a remote cluster.
Install the CRDs into the cluster:
make install
For quick feedback and code-level debugging, run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running):
make run
Install Instances of Custom Resources
If you pressed y
for Create Resource [y/n] then you created a CR for your CRD in your samples (make sure to edit them first if you’ve changed the
API definition):
kubectl apply -k config/samples/
Run It On the Cluster
When your controller is ready to be packaged and tested in other clusters.
Build and push your image to the location specified by IMG
:
make docker-build docker-push IMG=<some-registry>/<project-name>:tag
Deploy the controller to the cluster with image specified by IMG
:
make deploy IMG=<some-registry>/<project-name>:tag
Uninstall CRDs
To delete your CRDs from the cluster:
make uninstall
Undeploy controller
Undeploy the controller to the cluster:
make undeploy
Using Plugins
Kubebuilder design is based on Plugins and you can use available plugins to add optional features to your project.
Creating an API and Controller with code to manage an image
For example, you can scaffold an API and controller that manages container images by using the deploy-image plugin:
kubebuilder create api --group webapp --version v1alpha1 --kind Busybox --image=busybox:1.36.1 --plugins="deploy-image/v1-alpha"
This command generates:
- The API definition in
api/v1alpha1/busybox_types.go
. - The controller logic in
internal/controllers/busybox_controller.go
. - A test scaffold in
internal/controllers/busybox_controller_test.go
, which uses EnvTest for integration-style testing.
Keeping your project up to date with ecosystem changes
Kubebuilder provides the AutoUpdate Plugin to help keep your project aligned with the latest ecosystem changes. When a new release is available, the plugin opens an Issue with a Pull Request compare link. You can then review the updates and, if helpful, use GitHub AI models to understand what changes are needed to keep your project current.
kubebuilder edit --plugins="autoupdate/v1-alpha"
This command scaffolds a GitHub workflow file at .github/workflows/autoupdate.yml
.
Next Step
- Proceed with the Getting Started Guide, which should take no more than 30 minutes and will provide a solid foundation.
- Afterward, dive into the CronJob Tutorial to deepen your understanding by developing a demo project.
- Ensure that you understand the APIs and Groups concepts Groups and Versions and Kinds, oh my! before designing your own API and project.