This is unreleased documentation for Rancher Turtles v0.26-dev.

Create & Import Your First Cluster

This section will guide you through creating your first cluster and importing it into Rancher Manager. Two alternative methods for cluster provisioning are presented: using a GitOps workflow with Fleet and manually applying the manifests via kubectl.

Prerequisites

Rancher Manager cluster
Cluster API providers installed for your scenario - we’ll be using the Docker infrastructure and RKE2 bootstrap/control plane providers in these instructions - see Initialization for common providers using Turtles' CAPIProvider

Provision a CAPI Workload Cluster

GitOps using Fleet
Manually using kubectl

Configure your Fleet repository

To simplify the process of cluster provisioning, we will be using a series of pre-configured examples that you can find in the repository https://github.com/rancher/turtles/tree/main/examples. By inspecting the contents of this repository, you will find:

An applications folder for additional apps that can be deployed using Fleet (CNI, CSI, CPI).
A clusterclasses folder with a bunch of ClusterClass examples.
A clusters/docker/rke2 folder with an example of Docker cluster definition.

If you prefer, you can create your own Fleet repository using the same base structure.

Use Rancher UI to add your Fleet repository

Now the cluster definitions are committed to a git repository they can be used to provision the clusters. To do this they will need to be imported into the Rancher Manager cluster (which is also acting as a Cluster API management cluster) using the Continuous Delivery feature (which uses Fleet).

Go to Rancher Manager
Select Continuous Delivery from the menu:
Select fleet-local as the namespace from the top right
Select Git Repos from the sidebar
Click Add Repository
Enter clusters as the name
Get the HTTPS clone URL from your git repo
Add the URL into the Repository URL field
Change the branch name to main

Add the following paths to specify which directories to deploy:

Fleet paths configuration

examples/clusterclasses/docker/rke2
examples/applications/cni/calico
examples/applications/lb/docker
examples/clusters/docker/rke2

Click Next
Click Create
Click on the clusters name
Watch the resources become ready
Select Cluster Management from the menu
Check your cluster has been imported

Apply the cluster resources

To create the cluster using kubectl, run the following commands:

Open a terminal and apply the ClusterClass and related templates:

kubectl apply -f https://raw.githubusercontent.com/rancher/turtles/refs/heads/main/examples/clusterclasses/docker/rke2/clusterclass-docker-rke2.yaml

Apply the load balancer configuration:

kubectl apply -f https://raw.githubusercontent.com/rancher/turtles/refs/heads/main/examples/applications/lb/docker/configmap.yaml

Apply the CNI (Calico) configuration:

kubectl apply -f https://raw.githubusercontent.com/rancher/turtles/refs/heads/main/examples/applications/cni/calico/helm-chart.yaml

Create the cluster:

kubectl apply -f https://raw.githubusercontent.com/rancher/turtles/refs/heads/main/examples/clusters/docker/rke2/cluster.yaml

Watch the resources become ready:
```
kubectl get clusters -w
```
Select Cluster Management from the menu
Check your cluster has been imported

Next Steps: Wait for the cluster to appear in the Rancher Dashboard

The cluster provisioned in this tutorial contains the cluster-api.cattle.io/rancher-auto-import label. This label will instruct Turtles to automatically import the cluster into Rancher. For more information please refer to Rancher Cluster Registration.