Install

Rancher Turtles is a Rancher extension which means that you must have Rancher installed before you can get started with Rancher Turtles.

If you don’t have Rancher installed yet, make sure to follow one of the official installation guides. We recommend you take a look at the Prerequisites table to determine the appropriate version to install.

Prerequisites

Before you can install Rancher Turtles, you need to have the following components installed:

Name Version Details

Kubernetes cluster

v1.30.0

Helm

v3.12.0

Follow the official installation docs

Rancher

v2.10.0

Install using Helm on any Kubernetes cluster, whether self-hosted or on a managed service from Amazon, Azure, or Google.

Cert-manager

v1.15.2

Using Helm based installation or via kubectl apply.

Components Versions

This table lists the version of the components installed with the latest version v0.17.0 of Rancher Turtles:

If you’re customizing the installation parameters, please make sure that you are using compatible versions of the components.
Name Version

Cluster API Operator

v0.17.0

Cluster API

v1.9.5

Cluster API Provider RKE2

v0.12.0

Install Rancher Turtles using Rancher Dashboard

This is the recommended option for installing Rancher Turtles.

Via Rancher UI, and just by adding the Turtles repository, we can easily let Rancher take care of the installation and configuration of the Cluster API Extension.

Installing Rancher Turtles will transform your Rancher Manager cluster into a CAPI Management cluster so you can provision and manage CAPI workload clusters.

Rancher’s embedded-cluster-api functionality will be disabled when installing Rancher Turtles. This includes also cleaning up Rancher-specific webhooks that otherwise would conflict with CAPI ones.

The recommended way to disable this feature and the Rancher-specific webhooks, is to use the official Rancher Turtles Helm chart, that includes a pre-install hook to apply the following changes:

  • Disable the embedded-cluster-api feature in Rancher.

  • Delete the mutating-webhook-configuration and validating-webhook-configuration webhooks that are no longer needed.

Installation

  • From your browser, access Rancher Manager and explore the local cluster.

  • Using the left navigation panel, go to Apps -> Repositories.

  • Click Create to add a new repository.

  • Enter the following:

  • Wait for the turtles repository to have a status of Active.

  • Go to Apps -> Charts.

  • Filter for turtles.

  • Click Rancher Turtles - the Cluster API Extension

  • Click Install -> Next -> Install.

Rancher will select not to install Turtles into a Project by default. Installing Turtles into a Project is not supported and the default configuration None should be used to avoid unexpected behavior during installation.
install-turtles-from-ui

This will use the default values for the Helm chart, which are good for most installations. If your configuration requires overriding some of these defaults, you can either specify the values during installation from Rancher UI or, alternatively, you can opt for the manual installation via Helm. And, if you are interested on learning more about the available values, you can check the reference guide.

The installation may take a few minutes and, when it finishes, you will be able to see the following new deployments in the cluster:

  • capi-system/capi-controller-manager

  • rancher-turtles-system/caapf-controller-manager

  • rancher-turtles-system/rancher-turtles-cluster-api-operator

  • rancher-turtles-system/rancher-turtles-controller-manager

  • rke2-bootstrap-system/rke2-bootstrap-controller-manager

  • rke2-control-plane-system/rke2-control-plane-controller-manager

deployments-turtles

CAPI UI extension installation

Rancher also provides a UI extension that makes it easy to manage CAPI providers, create CAPI clusters and view CAPI related resources via the Rancher Dashboard. Installing the CAPI UI extension is similar to installing Turtles.

Installing Turtles prior to installing the CAPI UI extension is recommended.

  • From your browser, access Rancher Manager and navigate to the Extensions page.

  • Using the three dots menu located at the top right, select Manage Repositories. This should open the Repositories page for the local cluster.

  • Click Create to add a new repository.

  • Enter the following:

  • Click Create.

  • Wait for the capi-ui repository to have a status of Active.

  • Go to Extensions -> Available.

  • Find the CAPI UI card and click on its Install button.

  • Select the version to install (default is the latest) and click Install.

  • Once the extension is installed, click on the Reload button at the top of the page to reload the page.

  • The CAPI UI extension is now installed. You can navigate to Cluster Management -> CAPI to start using it.

install-capi-ui-extension