Manual Installation

This page describes how to install Rancher Turtles manually, using the Helm CLI.

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

Rancher Turtles uses the Cluster API Operator to provide a declarative way of installing Cluster API Providers and managing their lifecycle. If you want to learn more about it, you can refer to the Cluster API Operator book.

Since Rancher Turtles depends on the Cluster API Operator functionality, it is installed as a dependency of the Rancher Turtles Helm chart.

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

Install Rancher Turtles using Helm

The rancher-turtles Helm chart is available in https://rancher.github.io/turtles and this Helm repository must be added before proceeding with the installation:

helm repo add turtles https://rancher.github.io/turtles
helm repo update

Once the Helm repository has been added and updated locally, you can proceed to install Rancher Turtles. The Helm chart will handle installation of any dependencies automatically:

helm install rancher-turtles turtles/rancher-turtles --version v0.16.0 \
    -n rancher-turtles-system \
    --dependency-update \
    --create-namespace --wait \
    --timeout 180s

The installation process may take a few minutes. Once complete, you can take some time to review the installed controllers:

rancher-turtles controller.
cluster-api controller.
cluster-api-operator controller.
cluster-api-addon-provider-fleet controller.
rke2-bootstrap controller.
rke2-control-plane controller.

By default, the installation process will create a secret named capi-env-variables in the core provider namespace, which is used to enable certain Cluster API feature flags (CLUSTER_TOPOLOGY, EXP_CLUSTER_RESOURCE_SET and EXP_MACHINE_POOL). These feature flags are required to enable additional Cluster API functionality.

If you need to override the default behavior and use an existing secret (or add custom environment variables), you can pass the secret name via a Helm flag, as shown in the example below. In this case, you are responsible for managing the secret creation and its contents, so make sure to include the feature flags (CLUSTER_TOPOLOGY, EXP_CLUSTER_RESOURCE_SET and EXP_MACHINE_POOL) as enabled.

helm install ...
    # Passing secret name and namespace for additional environment variables
    --set cluster-api-operator.cluster-api.configSecret.name=<secret_name>

The following is an example of a user-managed secret cluster-api-operator.cluster-api.configSecret.name=variables with CLUSTER_TOPOLOGY, EXP_CLUSTER_RESOURCE_SET and EXP_MACHINE_POOL feature flags set and an extra custom variable:

secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: variables
  namespace: rancher-turtles-system
type: Opaque
stringData:
  CLUSTER_TOPOLOGY: "true"
  EXP_CLUSTER_RESOURCE_SET: "true"
  EXP_MACHINE_POOL: "true"
  CUSTOM_ENV_VAR: "false"

For detailed information on the values supported by the chart and their usage, refer to Helm chart options