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.31.4

Helm

v3.17.1

Follow the official installation docs

Rancher

v2.11.0

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

Cert-manager

v1.16.3

Using Helm based installation or via kubectl apply.

Components Versions

This table lists the version of the components installed with the latest version v0.20.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.18.1

Cluster API

v1.9.5

Cluster API Provider RKE2

v0.16.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

Install Rancher Turtles using a CLI (development/experimental)

For users who prefer a streamlined command-line installation process, Rancher Manager with Rancher Turtles can be installed using the turtles-quickstart.sh script.

This installation method provides a fast way to get Rancher Manager and Turtles without doing too many manual steps.

Using the quickstart script

  1. Ensure you have installed on your system kubectl, kind, helm and running docker daemon.

  2. Download the script from Rancher Turtles github repository:

    curl -fsSL https://raw.githubusercontent.com/rancher/turtles/main/scripts/turtles-quickstart.sh -o turtles-quickstart.sh

  3. Run turtles-quickstart.sh script:

    bash ./turtles-quickstart.sh

  4. Wait until the script completes - this may take a few minutes while all components are installed

The script:

  • Verifies that your cluster meets the prerequisites.

  • Adds the Rancher and Turtles Helm repositories.

  • Installs Rancher Turtles with default configuration.

  • Displays status information when complete.

  • Creates a new example downstream cluster using the CAPI Docker Provider.