Developer Guide
Pieces of Cluster API
Cluster API is made up of many components, all of which need to be running for correct operation. For example, if you wanted to use Cluster API with AWS, you’d need to install both the cluster-api manager and the aws manager.
Cluster API includes a built-in provisioner, Docker, that’s suitable for using for testing and development. This guide will walk you through getting that daemon, known as CAPD, up and running.
Other providers may have additional steps you need to follow to get up and running.
Prerequisites
Docker
Iterating on the cluster API involves repeatedly building Docker containers. You’ll need the docker daemon v19.03 or newer available.
On MacOS systems using Lima is a viable alternative to Docker Desktop.
A Cluster
You’ll likely want an existing cluster as your management cluster. The easiest way to do this is with kind v0.9 or newer, as explained in the quick start.
Make sure your cluster is set as the default for kubectl
.
If it’s not, you will need to modify subsequent kubectl
commands below.
A container registry
If you’re using kind, you’ll need a way to push your images to a registry so they can be pulled. You can instead side-load all images, but the registry workflow is lower-friction.
Most users test with GCR, but you could also use something like Docker Hub.
If you choose not to use GCR, you’ll need to set the REGISTRY
environment variable.
Kustomize
You’ll need to install kustomize
.
There is a version of kustomize
built into kubectl, but it does not have all the features of kustomize
v3 and will not work.
Kubebuilder
You’ll need to install kubebuilder
.
Envsubst
You’ll need envsubst
or similar to handle clusterctl var replacement. Note: drone/envsubst releases v1.0.2 and earlier do not have the binary packaged under cmd/envsubst. It is available in Go pseudo-version v1.0.3-0.20200709231038-aa43e1c1a629
We provide a make target to generate the envsubst
binary if desired. See the provider contract for more details about how clusterctl uses variables.
make envsubst
The generated binary can be found at ./hack/tools/bin/envsubst
Cert-Manager
You’ll need to deploy cert-manager components on your management cluster, using kubectl
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.0/cert-manager.yaml
Ensure the cert-manager webhook service is ready before creating the Cluster API components.
This can be done by following instructions for manual verification from the cert-manager web site. Note: make sure to follow instructions for the release of cert-manager you are installing.
Development
Option 1: Tilt
Tilt is a tool for quickly building, pushing, and reloading Docker containers as part of a Kubernetes deployment. Many of the Cluster API engineers use it for quick iteration. Please see our Tilt instructions to get started.
Option 2: The Old-fashioned way
# Build all the images
make docker-build
# Push images
make docker-push
# Apply the manifests
kustomize build config/default | ./hack/tools/bin/envsubst | kubectl apply -f -
kustomize build bootstrap/kubeadm/config/default | ./hack/tools/bin/envsubst | kubectl apply -f -
kustomize build controlplane/kubeadm/config/default | ./hack/tools/bin/envsubst | kubectl apply -f -
kustomize build test/infrastructure/docker/config/default | ./hack/tools/bin/envsubst | kubectl apply -f -
Testing
Cluster API has a number of test suites available for you to run. Please visit the testing page for more information on each suite.
That’s it!
Now you can create CAPI objects! To test another iteration, you’ll need to follow the steps to build, push, update the manifests, and apply.
Videos explaining CAPI architecture and code walkthroughs
CAPI components and architecture
- Simplified Experience Of Building Cluster API Provider In Multitenant Cloud - October 2022
- Cluster API Intro and Deep Dive - May 2022 v1beta1
- Cluster API Deep Dive - Dec 2020 v1alpha3
- Cluster API Deep Dive - Sept 2020 v1alpha3
- Declarative Kubernetes Clusters with Cluster API - Oct 2020 v1alpha3
- TGI Kubernetes 178: ClusterAPI - ClusterClass & Managed Topologies - Dec 2020 v1beta1
Additional ClusterAPI KubeCon talks
- SIG Cluster Lifecycle Intro & Future - November 2023
- Cluster API Deep Dive: Improving Performance up to 2k Clusters - November 2023
- Leveraging Cluster-API for Production-Ready Multi-Regional Infrastructures - November 2023
- The Stars Look Very Different Today”: Kubernetes and Cloud Native at the SKA Observatory - November 2023
- 15,000 Minecraft Players Vs One K8s Cluster. Who Wins? - November 2023
- Cluster API Providers: Intro, Deep Dive, and Community! - April 2023
- Ephemeral Clusters as a Service with ClusterAPI and GitOps - April 2023
- The Power of Self-Managing Clusters - April 2023
- How to Turn Release Management from Duty to Fun - April 2023
- Tilt Your World! Lessons Learned in Improving Dev Productivity with Tilt - April 2023
- How Adobe Planned For Scale With Argo CD, Cluster API, And VCluster - October 2022
- Bare-Metal Chronicles: Intertwinement Of Tinkerbell, Cluster API And GitOps - October 2022
- Running Isolated VirtualClusters With Kata & Cluster API - October 2022
- SIG Cluster Lifecycle Intro - October 2022
- How to Migrate 700 Kubernetes Clusters to Cluster API with Zero Downtime - May 2022
- Build Your Own Cluster API Provider the Easy Way - May 2022
Tutorials
-
kubectl Create Cluster: Production-ready Kubernetes with Cluster API 1.0 - October 2022
-
So You Want To Develop a Cluster API Provider? - October 2022
Code walkthroughs
Let’s chat about ...
We are currently hosting “Let’s chat about ...” sessions where we are talking about topics relevant to contributors and users of the Cluster API project. For more details and an up-to-date list of recordings of past sessions please see Let’s chat about ....