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

In case you need to review the list of prerequisites (including cert-manager), you can refer to this table.

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.

If you would like to understand how Rancher Turtles works and what the architecture looks like, you can refer to the Architecture section.

If uninstalling, you can refer to Uninstalling Rancher Turtles

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:

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

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

  • capi-system/capi-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.