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

Cluster API Addon Provider Fleet

Overview

Cluster API Add-on Provider for Fleet (CAAPF) is a Cluster API (CAPI) provider that provides integration with Fleet to enable the easy deployment of applications to a CAPI-provisioned cluster.

For more information about the provider, please refer to CAAPF book.

In previous versions of Rancher Turtles, CAAPF was installed by default. From Rancher 2.14.1 onwards, it is no longer part of Rancher Turtles and if required it needs to be installed separately. See the Prerequisites section below for information on how to enable it.

CAAPF depends on the WatchList Kubernetes feature gate. This feature needs to be explicitly enabled on Kubernetes 1.33 versions. See the Kubernetes upstream documentation for further information.

Prerequisites

Starting with Rancher 2.14.1, CAAPF needs to be installed and enabled manually, if required. To enable CAAPF, two configuration changes are required:

  • Apply a CAPIProvider manifest for CAAPF in your management cluster.

    • CAAPF provider installation example:

      Click to Expand 
      apiVersion: v1
kind: Namespace
metadata:
  name: fleet-addon-system
---
apiVersion: turtles-capi.cattle.io/v1alpha1
kind: CAPIProvider
metadata:
  name: fleet
  namespace: fleet-addon-system
spec:
  name: rancher-fleet
  type: addon

  • Set features.use-caapf.enabled: true in the Rancher Turtles chart values to enable the use-caapf alpha feature gate (disabled by default). For instructions on how to set feature gates, refer to this section.

Once both are in place, Turtles will automatically add the provisioning.cattle.io/externally-managed annotation to imported Rancher clusters, delegating Fleet agent installation on CAPI workload clusters to CAAPF rather than Rancher managing it directly.

Functionality

  • The provider will register a newly provisioned CAPI cluster with Fleet by creating a Fleet Cluster instance with the same name and namespace. Applications can be automatically deployed to the created cluster using GitOps.

  • The provider will automatically create a Fleet ClusterGroup for every CAPI ClusterClass in the ClusterClass namespace. This enables you to deploy the same applications to all clusters created from the same ClusterClass.

  • The provider will automatically create a Fleet ClusterGroup for every referenced CAPI ClusterClass by Cluster located in a different namespace from ClusterClass. This enables you to deploy the same applications to all clusters referencing the same ClusterClass in a particular namespace.

This allows a user to specify either a Bundle resource with raw application workloads or GitRepo to install applications from git. Each of the resources can provide targets with any combination of:

  targets:
  - clusterGroup: <cluster-class-name> # If the cluster is created from cluster-class
  - clusterName: <a specific CAPI cluster name>

Additionally, CAAPF automatically propagates CAPI cluster labels to the Fleet cluster resource, so users can specify a target matching a common cluster label with:

  targets:
  - clusterSelector: <label selector for the cluster instances, inherited from CAPI clusters>
  - clusterGroupSelector: <label selector for the cluster group instances, labels inherited from ClusterClass>

Helm Chart templating based on CAPI Cluster and ControlPlane

The Cluster API Addon Provider Fleet automates application templating for imported CAPI clusters based on matching cluster state. This feature ensures that the state of a CAPI cluster and resources is always up-to-date in the spec.templateValues.ClusterValues field of the Fleet cluster resource. This allows users to:

  • Reference specific parts of the CAPI cluster directly or via Helm substitution patterns referencing .ClusterValues.Cluster data.

  • Substitute based on the state of the control plane resource via the .ClusterValues.ControlPlane field.

  • Substitute based on the state of the infrastructure cluster resource via the .ClusterValues.InfrastructureCluster field.

  • Maintain a consistent application state across different clusters.

  • Use the same template for multiple matching clusters to simplify deployment and management.

For more information on the feature, please refer to templating documentation in the book.

Example - deploying kindnet CNI

Demo: asciicast

Example - deploying Calico CNI using GitRepo

Demo: asciicast

For a tutorial and prerequisites, please refer to gitrepo tutorial section in the book.