Create & import a cluster using CAPI providers

This guide goes over the process of creating and importing CAPI clusters with a selection of the officially certified providers.

Keep in mind that most Cluster API Providers are upstream projects maintained by the Kubernetes open-source community.

Prerequisites

  • AWS RKE2

  • AWS Kubeadm

  • Docker Kubeadm

Create Your Cluster Definition

  • AWS RKE2

  • AWS Kubeadm

  • Docker Kubeadm

Before creating an AWS+RKE2 workload cluster, it is required to build an AMI for the RKE2 version that is going to be installed on the cluster. You can follow the steps in the RKE2 image-builder README to build the AMI.

We recommend you refer to the CAPRKE2 repository where you can find a samples folder with different CAPA+CAPRKE2 cluster configurations that can be used to provision downstream clusters. The internal folder contains cluster templates to deploy an RKE2 cluster on AWS using the internal cloud provider, and the external folder contains the cluster templates to deploy a cluster with the external cloud provider.

We will use the internal one for this guide, however the same steps apply for external.

To generate the YAML for the cluster, do the following:

  1. Open a terminal and run the following:

    export CLUSTER_NAME=cluster1
export CONTROL_PLANE_MACHINE_COUNT=3
export WORKER_MACHINE_COUNT=3 export RKE2_VERSION=v1.30.3+rke2r1
export AWS_NODE_MACHINE_TYPE=t3a.large
export AWS_CONTROL_PLANE_MACHINE_TYPE=t3a.large
export AWS_SSH_KEY_NAME="aws-ssh-key" export AWS_REGION="aws-region"
export AWS_AMI_ID="ami-id"

curl -s https://raw.githubusercontent.com/rancher/cluster-api-provider-rke2/refs/heads/main/examples/aws/cluster-template.yaml | envsubst > cluster1.yaml

  2. View cluster1.yaml and examine the resulting yaml file. You can make any changes you want as well.

    The Cluster API quickstart guide contains more detail. Read the steps related to this section here.

  3. Create the cluster using kubectl

    bash kubectl create -f cluster1.yaml

To generate the YAML for the cluster, do the following:

  1. Open a terminal and run the following:

    export CLUSTER_NAME=cluster1
export KUBERNETES_VERSION=v1.30
export AWS_REGION=eu-west-2
export AWS_INSTANCE_TYPE=t3.medium

curl -s https://raw.githubusercontent.com/rancher-sandbox/rancher-turtles-fleet-example/templates/capa.yaml | envsubst > cluster1.yaml

  2. View cluster1.yaml to ensure there are no tokens (i.e. SSH keys or cloud credentials). You can make any changes you want as well.

    The Cluster API quickstart guide contains more detail. Read the steps related to this section here.

  3. Create the cluster using kubectl

     kubectl create -f cluster1.yaml

To generate the YAML for the cluster, do the following:

  1. Open a terminal and run the following:

    export CLUSTER_NAME=cluster1
export CONTROL_PLANE_MACHINE_COUNT=1
export WORKER_MACHINE_COUNT=1
export KUBERNETES_VERSION=v1.30.0

curl -s https://raw.githubusercontent.com/rancher-sandbox/rancher-turtles-fleet-example/templates/docker-kubeadm.yaml | envsubst > cluster1.yaml

  2. View cluster1.yaml to ensure there are no tokens. You can make any changes you want as well.

    The Cluster API quickstart guide contains more detail. Read the steps related to this section here.

  3. Create the cluster using kubectl

    kubectl create -f cluster1.yaml

After your cluster is provisioned, you can check functionality of the workload cluster using kubectl:

kubectl describe cluster cluster1

Remember that clusters are namespaced resources. These examples provision clusters in the default namespace, but you will need to provide yours if using a different one.

Mark Namespace or Cluster for Auto-Import

To automatically import a CAPI cluster into Rancher Manager, there are 2 options:

  1. Label a namespace so all clusters contained in it are imported.

  2. Label an individual cluster definition so that it’s imported.

Labeling a namespace:

kubectl label namespace default cluster-api.cattle.io/rancher-auto-import=true

Labeling an individual cluster definition:

kubectl label cluster.cluster.x-k8s.io -n default cluster1 cluster-api.cattle.io/rancher-auto-import=true