---
title: "Cluster API"
description: "Provision and manage Kubernetes clusters on Exoscale declaratively with Cluster API and the Exoscale infrastructure provider (CAPEX)."
url: https://community.exoscale.com/reference/cluster-api/
section: reference
last_updated: 2026-10-08
---
> For AI agents: the documentation index is at https://community.exoscale.com/llms.txt. Every page is available as markdown at `<page URL>index.md` or with `Accept: text/markdown`.

# Cluster API

## What is Cluster API?

[Cluster API](https://cluster-api.sigs.k8s.io/) (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`](https://cluster-api.sigs.k8s.io/clusterctl/overview). The main [provider types](https://cluster-api.sigs.k8s.io/user/concepts#providers) 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 <a href="https://github.com/exoscale/cluster-api-provider-exoscale/releases/latest" target="_blank" rel="noopener"><img src="https://img.shields.io/github/v/release/exoscale/cluster-api-provider-exoscale?color=green" alt="Latest release" style="display:inline;margin:0;vertical-align:middle"></a> {#the-exoscale-infrastructure-provider}

The [Cluster API Provider Exoscale](https://github.com/exoscale/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](https://cluster-api.sigs.k8s.io/tasks/bootstrap/kubeadm-bootstrap) or [k0smotron](https://docs.k0smotron.io).

CAPEX exposes four custom resources:

| Kind | Purpose |
| --- | --- |
| `ExoscaleCluster` | Cluster-wide infrastructure backing a cluster API `Cluster`. |
| `ExoscaleMachine` | A single Exoscale Compute Instance backing a Cluster API `Machine`. |
| `ExoscaleClusterTemplate` | A reusable `ExoscaleCluster` template. |
| `ExoscaleMachineTemplate` | A reusable `ExoscaleMachine` template. |

## Prerequisites

- A Kubernetes cluster to use as management cluster (a local [kind](https://kind.sigs.k8s.io/) cluster is enough to get started)
- [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl) installed and configured
- [`clusterctl`](https://cluster-api.sigs.k8s.io/user/quick-start#install-clusterctl) installed
- An [Exoscale](https://portal.exoscale.com/register) account with [API credentials](https://community.exoscale.com/documentation/iam/quick-start/)

## 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](#install-the-provider).

### With a custom configuration (older clusterctl versions)

Declare the provider in the [clusterctl configuration file](https://cluster-api.sigs.k8s.io/clusterctl/configuration#provider-repositories), located by default at `$XDG_CONFIG_HOME/cluster-api/clusterctl.yaml` (usually `~/.config/cluster-api/clusterctl.yaml`):

```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):

```bash
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:

```bash
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/`](https://github.com/exoscale/cluster-api-provider-exoscale/tree/main/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](https://github.com/exoscale/cluster-api-provider-exoscale/tree/main/config/samples/kubeadm/cluster): a simple cluster where Kubernetes is installed at boot time by cloud-init — a quick way to try things out.
  - [cluster-custom-image](https://github.com/exoscale/cluster-api-provider-exoscale/tree/main/config/samples/kubeadm/cluster-custom-image): the same cluster, built from a custom template with Kubernetes pre-installed.
- **k0smotron** — backs the cluster with [k0s](https://k0sproject.io/) and needs no custom template:
  - [cluster](https://github.com/exoscale/cluster-api-provider-exoscale/tree/main/config/samples/k0smotron/cluster): a cluster whose control plane and worker nodes scale independently.
  - [cluster-csi](https://github.com/exoscale/cluster-api-provider-exoscale/tree/main/config/samples/k0smotron/cluster-csi): the same cluster with the [Exoscale CSI driver](https://github.com/exoscale/exoscale-csi-driver) installed.
  - [move](https://github.com/exoscale/cluster-api-provider-exoscale/tree/main/config/samples/k0smotron/move): the same cluster, moved from one management cluster to another with `clusterctl move`.