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

Rancher Setup

Installing Rancher

If you’re already running Rancher v2.13 or later, you can skip this section and jump to Your First Cluster.

Starting with Rancher v2.13, Rancher Turtles is pre-installed as a Rancher system chart. There is no longer a need to install Rancher Turtles separately. Simply installing Rancher v2.13 or later is all that is required to get started with Cluster API (CAPI).

Helm is the recommended way to install Rancher in an existing or new Kubernetes cluster.

Make sure to follow one of the official installation guides for Rancher.

Here’s a minimal example of installing Rancher with Helm:

helm install rancher rancher-stable/rancher \
    --namespace cattle-system \
    --create-namespace \
    --set hostname=<rancher-hostname> \
    --version <rancher-version> \
    --wait

Replace <rancher-hostname> with the actual hostname of your Rancher server and use --version to specify a Rancher version of v2.13.0 or later.

What Gets Installed

When Rancher v2.13 or later is installed, Rancher Turtles is automatically deployed as a system component in the cattle-turtles-system namespace. This includes:

  • The rancher-turtles-controller-manager pod, which handles all CAPI-related resources

  • Core CAPI CRDs and the core CAPI controller

  • The CAPIProvider custom resource, which allows declarative definition of CAPI providers

The core CAPI controller manifest is embedded in a ConfigMap, which simplifies operation in air-gapped environments.

Installing CAPI Providers

With Rancher Turtles embedded in Rancher, CAPI providers are no longer bundled by default. Providers are managed declaratively using the CAPIProvider custom resource, and a separate providers chart is available for installing certified providers. For more information on the providers chart, refer to Install certified providers.

For example, to define a provider:

apiVersion: turtles-capi.cattle.io/v1alpha1
kind: CAPIProvider
metadata:
  name: aws
  namespace: cattle-turtles-system
spec:
  type: infrastructure
  name: aws

Refer to the CAPIProvider reference for the full list of configuration options.

You are now ready to use Rancher Turtles! 🎉