Quick Start

This Quick Start guide will cover:

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

Installation

• Install dep
• Install kustomize
• Install kubebuilder

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 underpkg/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 Controllerand 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 localprocess 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