Cluster API

What is Cluster API?

Cluster API (CAPI) is a Kubernetes sub-project that provides declarative, Kubernetes-style APIs to create, configure, upgrade, and delete Kubernetes clusters. Clusters are described with custom resources (Cluster, Machine, MachineDeployment, …) applied to a management cluster. Controllers running in this management cluster then provision and operate the workload clusters that you described.

What are providers?

Cluster API itself is cloud and distribution agnostic: the actual work is delegated to providers, which are controllers installed in the management cluster with clusterctl. The main provider types are:

• Core provider — the Cluster API controllers themselves (Cluster, Machine, MachineDeployment, …).
• Infrastructure provider — creates the cloud resources a cluster needs: compute instances, networking, security groups, load balancing, …
• Bootstrap provider — generates the configuration (for example cloud-init data) that turns a machine into a Kubernetes node.
• Control plane provider — creates and manages the Kubernetes control plane of the workload cluster.

Other provider types exist (IPAM, add-on, runtime extension, …) but are not required to deploy a cluster.

The Exoscale infrastructure provider

The Cluster API Provider Exoscale (CAPEX) is the Cluster API infrastructure provider for Exoscale: it turns its custom resources into Exoscale cloud resources. Turning those resources into a running Kubernetes cluster is the job of a bootstrap/control-plane provider, such as kubeadm or k0smotron.

CAPEX exposes four custom resources:

Prerequisites

• A Kubernetes cluster to use as management cluster (a local kind cluster is enough to get started)
• kubectl installed and configured
• clusterctl installed
• An Exoscale account with API credentials

Deploy the provider

CAPEX is installed with clusterctl, which first has to know where to find it. Depending on your clusterctl version, the provider is either built in or must be declared in a custom configuration.

With the built-in provider (clusterctl v1.15.0 and later)

CAPEX is one of the built-in clusterctl providers starting from clusterctl v1.15.0. No configuration is needed, skip directly to Install the provider.

With a custom configuration (older clusterctl versions)

Declare the provider in the clusterctl configuration file, located by default at $XDG_CONFIG_HOME/cluster-api/clusterctl.yaml (usually ~/.config/cluster-api/clusterctl.yaml):

providers:
  - name: exoscale
    url: https://github.com/exoscale/cluster-api-provider-exoscale/releases/latest/infrastructure-components.yaml
    type: InfrastructureProvider

Install the provider

Install CAPEX into the management cluster alongside the bootstrap and control-plane providers of your choice (kubeadm by default):

clusterctl init --infrastructure exoscale

Configure the credentials

Exoscale API credentials are not configured at install time: each ExoscaleCluster references a Kubernetes Secret, in its own namespace, holding them. By default, the Secret is named exoscale and uses the apikey and apisecret keys:

export EXOSCALE_API_KEY=<your-api-key>
export EXOSCALE_API_SECRET=<your-api-secret>

kubectl create secret generic exoscale \
  --from-literal=apikey=$EXOSCALE_API_KEY \
  --from-literal=apisecret=$EXOSCALE_API_SECRET \
  --namespace <cluster-namespace>

The Secret name and keys can be changed with the spec.exoscaleSecret field of the ExoscaleCluster.

Examples

Ready-to-use samples, each with a step-by-step README, are available in the config/samples/ directory of the repository:

• kubeadm — the default Cluster API bootstrap/control-plane provider, which expects Kubernetes to already be installed on the machines:
  • cluster: a simple cluster where Kubernetes is installed at boot time by cloud-init — a quick way to try things out.
  • cluster-custom-image: the same cluster, built from a custom template with Kubernetes pre-installed.
• k0smotron — backs the cluster with k0s and needs no custom template:
  • cluster: a cluster whose control plane and worker nodes scale independently.
  • cluster-csi: the same cluster with the Exoscale CSI driver installed.
  • move: the same cluster, moved from one management cluster to another with clusterctl move.