Manual Installation

This page describes how to install SUSE® Rancher Prime Cluster API manually, using the Helm CLI.

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

SUSE® Rancher Prime Cluster API 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 SUSE® Rancher Prime Cluster API depends on the Cluster API Operator functionality, it is installed as a dependency of the SUSE® Rancher Prime Cluster API Helm chart.

Rancher’s embedded-cluster-api functionality will be disabled when installing SUSE® Rancher Prime Cluster API. 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 SUSE® Rancher Prime Cluster API 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 SUSE® Rancher Prime Cluster API works and what the architecture looks like, you can refer to the Architecture section.

If uninstalling, you can refer to Uninstalling SUSE® Rancher Prime Cluster API

Install SUSE® Rancher Prime Cluster API 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
bash

Once the Helm repository has been added and updated locally, you can proceed to install SUSE® Rancher Prime Cluster API. 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
bash

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>
bash

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"
yaml

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