docs/book/src/quick-start.md
This Quick Start guide will cover:
Please, ensure that you see the guidance.
</aside>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/
You can work with the master branch by cloning the repository and running make install to generate the binary.
Please follow the steps in the section How to Build Kubebuilder Locally from the Contributing Guide.
Kubebuilder provides autocompletion support via the command kubebuilder completion <bash|fish|powershell|zsh>, which can save you a lot of typing. For further information see the completion document.
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
If your project is initialized within GOPATH, the implicitly called go mod init will interpolate the module path for you.
Otherwise --repo=<module path> must be set.
Read the Go modules blogpost if unfamiliar with the module system.
</aside>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
If you press y for Create Resource [y/n] and for Create Controller [y/n] then this will create the files api/v1/guestbook_types.go where the API is defined
and the internal/controller/guestbook_controller.go where the reconciliation business logic is implemented for this Kind(CRD).
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
// 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"`
}
+kubebuilder are markers processed by controller-gen
to generate CRDs and RBAC. Kubebuilder also provides scaffolding markers
to inject code into existing files and simplify common tasks. See cmd/main.go for examples.
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.
<aside class="note"> <h1>Context Used</h1>Your controller will automatically use the current context in your
kubeconfig file (i.e. whatever cluster kubectl cluster-info shows).
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
If you pressed y for Create Resource [y/n] then you created a CR for your CRD in your
config/samples/ directory.
Edit config/samples/webapp_v1_guestbook.yaml to contain a valid spec. For example:
# ...
spec:
foo: bar
Hint: "foo" is a string field defined in api/v1/guestbook_types.go:
// foo is an example field of Guestbook. Edit guestbook_types.go to remove/update
// +optional
Foo *string `json:"foo,omitempty"`
kubectl apply -k config/samples/
You can have a look at your applied resource now:
kubectl get guestbooks.webapp.my.domain guestbook-sample -o yaml
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
This image ought to be published in the personal registry you specified. And it is required to have access to pull the image from the working environment. Make sure you have the proper permission to the registry if the above commands don't work.
Consider incorporating Kind into your workflow for a faster, more efficient local development and CI experience. Note that, if you're using a Kind cluster, there's no need to push your image to a remote container registry. You can directly load your local image into your specified Kind cluster:
kind load docker-image <your-image-name>:tag --name <your-kind-cluster-name>
It is highly recommended to use Kind for development purposes and CI. To know more, see: Using Kind For Development Purposes and CI
<h1>RBAC errors</h1>If you encounter RBAC errors, you may need to grant yourself cluster-admin privileges or be logged in as admin. See Prerequisites for using Kubernetes RBAC on GKE cluster v1.11.x and older which may be your case.
</aside>To delete your CRDs from the cluster:
make uninstall
Undeploy the controller to the cluster:
make undeploy
Kubebuilder design is based on Plugins and you can use available plugins to add optional features to your project.
<aside class="note"> <h1>References and Examples</h1>Use the Deploy Image Plugin (deploy-image/v1-alpha) as a reference when creating your project. It follows Kubernetes conventions and recommended good practices. For example:
kubebuilder create api --group webapp --version v1alpha1 --kind Busybox --image=busybox:1.36.1 --plugins="deploy-image/v1-alpha"
Use AutoUpdate Plugin to keep your project aligned with the latest ecosystem changes. When a new release is available, it automatically opens an issue with a PR comparison link so you can review and update easily.
kubebuilder edit --plugins="autoupdate/v1-alpha"