Getting started with Cluster API¶
This guide covers how to deploy a Canonical Kubernetes management cluster for Cluster API (CAPI).
Install clusterctl
¶
The clusterctl
CLI tool manages 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 guide was written,
for amd64
you would run:
curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.9.3/clusterctl-linux-amd64 -o clusterctl
sudo install -o root -g root -m 0755 clusterctl /usr/local/bin/clusterctl
For more clusterctl
versions refer to the
upstream release page.
Set up a management cluster¶
The management cluster hosts the CAPI providers. You can use Canonical Kubernetes as a management cluster:
sudo snap install k8s --classic --channel=1.32-classic/stable
sudo k8s bootstrap
When setting up the management cluster, place its kubeconfig under
~/.kube/config
so other tools such as clusterctl
can discover and interact
with it.
sudo k8s status --wait-ready
mkdir -p ~/.kube/
sudo k8s config > ~/.kube/config
Prepare the infrastructure provider¶
Before generating a cluster, you need to configure the infrastructure provider. Each provider has its own prerequisites. Please follow the instructions for your provider:
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.5.2/clusterawsadm-linux-amd64 -o clusterawsadm
chmod +x clusterawsadm
sudo mv clusterawsadm /usr/local/bin
clusterawsadm
helps you bootstrapping the AWS environment that CAPI will use.
It will also create the necessary IAM roles for you. For more clusterawsadm
versions refer to the upstream release page.
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>
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 need to be encoded and stored as a Kubernetes secret:
export AWS_B64ENCODED_CREDENTIALS=$(clusterawsadm bootstrap credentials encode-as-profile)
You are now all set to deploy the AWS CAPI infrastructure provider.
Start by setting up environment variables to allow access to MAAS:
export MAAS_API_KEY="<maas-api-key>"
export MAAS_ENDPOINT="http://<maas-endpoint>/MAAS"
export MAAS_DNS_DOMAIN="<maas-dns-domain>"
The MAAS infrastructure provider uses these credentials to deploy machines, create DNS records and perform various other operations for workload clusters.
Warning
The management cluster needs to resolve DNS records from the MAAS domain, therefore it should be deployed on a MAAS machine.
Define further environment variables for the machine image and minimum compute resources of the control plane and worker nodes:
export CONTROL_PLANE_MACHINE_MINCPU="1"
export CONTROL_PLANE_MACHINE_MINMEMORY="2048"
export CONTROL_PLANE_MACHINE_IMAGE="ubuntu"
export WORKER_MACHINE_MINCPU="1"
export WORKER_MACHINE_MINMEMORY="2048"
export WORKER_MACHINE_IMAGE="ubuntu"
Note
The minimum resource variables are used to select machines with resources more than or equal to the provided values.
Optional environment variables can be defined for specifying resource pools and machine tags:
# (optional) Configure resource pools for control plane and worker machines
# export CONTROL_PLANE_MACHINE_RESOURCEPOOL="kvm-pool"
# export WORKER_MACHINE_RESOURCEPOOL="bare-metal-pool"
# (optional) Configure (comma-separated) tags for control plane and worker machines
# export CONTROL_PLANE_MACHINE_TAGS="control-plane,controller"
# export WORKER_MACHINE_TAGS="worker,compute"
You are now all set to deploy the MAAS CAPI infrastructure provider.
Initialize the management cluster¶
To initialize the management cluster with the latest released version of the providers and the infrastructure of your choice:
clusterctl init --bootstrap canonical-kubernetes --control-plane canonical-kubernetes -i <infra-provider-of-choice>
Once 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.
Next steps¶
Learn how to provision a Canonical Kubernetes cluster with CAPI: Provision a Canonical Kubernetes cluster
Learn how to upgrade the providers: Upgrade the providers of a management cluster
Learn how to install a custom Canonical Kubernetes version: Install custom Canonical Kubernetes