Cluster Provisioning with CAPI

This page covers how to deploy a MicroK8s multi-node cluster using the Cluster API.

Install clusterctl

The clusterctl CLI tool handles the lifecycle of a Cluster API management cluster. To install it follow the upstream instructions.
Typically this involves fetching the executable that matches your hardware architecture, and placing it in your PATH. For example, at the time this HowTo was authored for AMD64 you would:

curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.3.5/clusterctl-linux-amd64 -o clusterctl
sudo install -o root -g root -m 0755 clusterctl /usr/local/bin/clusterctl

Setup a management cluster

The management cluster hosts the CAPI providers. You can use a MicroK8s cluster as a management cluster:

sudo snap install microk8s --classic
sudo microk8s status --wait-ready
mkdir -p ~/.kube/
sudo microk8s.config  > ~/.kube/config
sudo microk8s enable dns

When setting up the management cluster place its kubeconfig under ~/.kube/config so other tools such as clusterctl can discover and interact with it.

Prepare the infrastructure provider

Before generating a cluster, you have to configure the infrastructure provider. Each such provider has its own prerequisites. Please, follow
the Cluster API instructions on the additional infrastructure specific configuration.

Example using AWS

The AWS infrastructure provider requires the clusterawsadm tool to be installed:

curl -L https://github.com/kubernetes-sigs/cluster-api-provider-aws/releases/download/v2.0.2/clusterawsadm-linux-amd64 -o clusterawsadm
chmod +x clusterawsadm
sudo mv clusterawsadm /usr/local/bin

With clusterawsadm you can then bootstrap the AWS environment that CAPI will use.

Start by setting up environment variables defining the AWS account to use, if these are not already defined

export AWS_REGION=<your-region-eg-us-east-1>
export AWS_ACCESS_KEY_ID=<your-access-key>
export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>

If you are using multi-factor authentication, you will also need:

export AWS_SESSION_TOKEN=<session-token> # If you are using Multi-Factor Auth.

The clusterawsadm uses these details to create a CloudFormation stack in your AWS account
with the correct IAM resources:

clusterawsadm bootstrap iam create-cloudformation-stack

The credentials should also be encoded and stored as a kubernetes secret

export AWS_B64ENCODED_CREDENTIALS=$(clusterawsadm bootstrap credentials encode-as-profile)

Initialse the management cluster

To initialise the management cluster with the latest released version of the providers and the infrastructure of your choice:

clusterctl init --bootstrap microk8s --control-plane microk8s -i <infra-provider-of-choice>

Generate a cluster spec manifest

As soon as the bootstrap and control-plane controllers are up and running you can apply the cluster manifests with the specifications of the cluster you want to provision.

For MicroK8s there are example manifests in the bootstrap provider examples directory on GitHub.

Alternatively, you can generate a cluster manifest for a selected set of commonly used infrastructures via templates provided by the MicroK8s team.
Visit the usage instructions for a list of different providers and their deployment.

Make sure you have initialised the desired infrastructure provider and fetch the MicroK8s bootstrap provider repository:

git clone https://github.com/canonical/cluster-api-bootstrap-provider-microk8s

Review list of variables needed for the cluster template:

cd cluster-api-bootstrap-provider-microk8s
clusterctl generate cluster microk8s-<cloud_provider> --from ./templates/cluster-template-<cloud_provider>.yaml --list-variables

Set the respective environment variables by editing the rc file as needed before sourcing it. Then generate the cluster manifest:

source ./templates/cluster-template-<cloud_provider>.rc
clusterctl generate cluster microk8s-<cloud_provider> --from ./templates/cluster-template-<cloud_proider>.yaml > cluster.yaml

Each provisioned node is associated with a MicroK8sConfig, through which you can set the cluster’s properties.
Please, review the available options in the respective definitions file and
edit the cluster manifest (cluster.yaml above) to match your needs.
Note that the configuration structure followed is similar to that of kubeadm - in the MicroK8sConfig you will find a ClusterConfiguration and an InitConfiguration section.

Deploy the cluster

Deploying the cluster is achieved by running:

sudo microk8s kubectl apply -f cluster.yaml

To see the deployed machines:

sudo microk8s kubectl get machine 

After the first control plane node is provisioned you are able to get the kubeconfig of the workload cluster:

clusterctl get kubeconfig <provisioned-cluster> > kubeconfig

You can then see the workload nodes using:

KUBECONFIG=./kubeconfig kubectl get node

Delete the cluster

To get the list of provisioned clusters:

sudo microk8s kubectl get clusters

To delete one

microk8s kubectl delete cluster <provisioned-cluster>