Viewing legacy documentation for Kubebuilder, check out the latest documentation instead.

Quick Start

This Quick Start guide will cover:

  • Create a project
  • Create an API
  • Run locally
  • Run in-cluster
  • Build documentation

Installation

version=1.0.8 # latest stable version
arch=amd64

# download the release
curl -L -O "https://github.com/kubernetes-sigs/kubebuilder/releases/download/v${version}/kubebuilder_${version}_darwin_${arch}.tar.gz"

# extract the archive
tar -zxvf kubebuilder_${version}_darwin_${arch}.tar.gz
sudo mv kubebuilder_${version}_darwin_${arch} /usr/local/kubebuilder

# update your PATH to include /usr/local/kubebuilder/bin
export PATH=$PATH:/usr/local/kubebuilder/bin

version=1.0.8 # latest stable version
arch=amd64

# download the release
curl -L -O "https://github.com/kubernetes-sigs/kubebuilder/releases/download/v${version}/kubebuilder_${version}_linux_${arch}.tar.gz"

# extract the archive
tar -zxvf kubebuilder_${version}_linux_${arch}.tar.gz
sudo mv kubebuilder_${version}_linux_${arch} /usr/local/kubebuilder

# update your PATH to include /usr/local/kubebuilder/bin
export PATH=$PATH:/usr/local/kubebuilder/bin

Create a new API

Project Creation

Initialize the project directory.

kubebuilder init --domain k8s.io --license apache2 --owner "The Kubernetes Authors"

API Creation

Create a new API called Sloop. The will create files for you to edit under pkg/apis/<group>/<version> and under pkg/controller/<kind>.

Optional: Edit the schema or reconcile business logic in the pkg/apis and pkg/controller respectively. For more on this see What is a Controller and What is a Resource

kubebuilder create api --group ships --version v1beta1 --kind Sloop

Locally Running An API

Optional: Create a new minikube cluster for development.

Build and run your API by installing the CRD into the cluster and starting the controller as a local process on your dev machine.

Create a new instance of your API and look at the command output.

Install the CRDs into the cluster

make install

Run the command locally against the remote cluster.

make run

In a new terminal - create an instance and expect the Controller to pick it up

kubectl apply -f config/samples/ships_v1beta1_sloop.yaml

Adding Schema and Business Logic

Edit your API Schema and Controller, then re-run make.

nano -w pkg/apis/ship/v1beta1/sloop_types.go
...
nano -w pkg/controller/sloop/sloop_controller.go
...
make

Publishing

Controller-Manager Container and Manifests installation

  • Build and push a container image
  • Create installation manifests for your API
  • Run in-cluster with kubectl apply
make

export IMG=gcr.io/kubeships/manager:v1
gcloud auth configure-docker
make docker-build
make docker-push
make deploy

API Documentation

Generate documentation:

  • Create an example of your API
  • Generate the docs
  • View the generated docs at docs/reference/build/index.html
kubebuilder create example  --version v1beta1 --group ships.k8s.io --kind Sloop
nano -w docs/reference/examples/sloop/sloop.yaml
...

kubebuilder docs