This document provides an overview of how
clusterctl works and explains how one can use
to create a Kubernetes cluster from scratch.
clusterctl is a CLI tool to create a Kubernetes cluster.
clusterctl is provided by the provider implementations.
It uses Cluster API provider implementations to provision resources needed by the Kubernetes cluster.
clusterctl needs 4 YAML files to start with:
provider-components.yamlcontains the Custom Resource Definitions (CRDs) of all the resources that are managed by Cluster API. Some examples of these resources are:
MachineSet, etc. For more details about Cluster API resources click here.
cluster.yamldefines an object of the resource type
machines.yamldefines an object of the resource type
Machine. Generally creates the machine that becomes the control-plane.
addons.yamlcontains the addons for the provider.
Many providers implementations come with helpful scripts to generate these YAMLS. Provider implementation can be found here.
clusterctl also comes with additional features. For example,
clusterctl can also take in an optional
bootstrap-only-components.yaml to provide resources to the bootstrap cluster without also providing them
to the target cluster post-pivot.
For more details about all the supported options run:
clusterctl create cluster --help
After generating the YAML files run the following command:
clusterctl create cluster --bootstrap-type <BOOTSTRAP CLUSTER TYPE> -c cluster.yaml -m machines.yaml -p provider-components.yaml --addon-components addons.yaml
clusterctl create cluster --bootstrap-type kind -c cluster.yaml -m machines.yaml -p provider-components.yaml --addon-components addons.yaml
What happens when we run the command?
After running the command first it creates a local cluster. If
kind was passed as the
it creates a local kind cluster. This cluster is generally referred to as the bootstrap cluster.
On this kind Kubernetes cluster the
provider-components.yaml file is applied. This step loads the CRDs into
the cluster. It also creates two Deployment
pods that run the cluster api controller manager and the provider specific controller manager. These pods register
the custom controllers that manage the newly defined resources (
as well as provider-specific resources).
clusterctl applies the
machines.yaml to the local kind Kubernetes cluster. This
step creates a Kubernetes cluster with only a control-plane (as defined in
machines.yaml) on the specified
provider. This newly created cluster is generally referred to as the management cluster or pivot cluster
or initial target cluster. The management cluster is responsible for creating and maintaining the workload cluster.
clusterctl moves all the CRDs and the custom controllers from the bootstrap cluster to the
management cluster and deletes the locally created bootstrap cluster. This step is referred to as the pivot.