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.

Starting with Rancher v2.14.1, CAAPF is no longer installed by default. While standard Fleet integration is still available through Rancher, advanced CAAPF features require manual installation. Review the following scenarios to determine if CAAPF is necessary for your environment:

  • Standard Rancher-Fleet integration

    If you only require your CAPI workload clusters to be registered with Fleet for basic application deployment via Rancher, you do not need to install CAAPF. No manual steps are necessary, and when you use the cluster-api.cattle.io/rancher-auto-import label, Rancher will automatically register the cluster with Fleet and install the fleet-agent as part of the standard import process. Upgrading to Rancher v2.14.1 will result in Rancher updating the fleet-agent on any existing downstream clusters.

  • Advanced CAAPF automation

    If you want to use advanced automation provided by CAAPF—such as automatic creation of Fleet ClusterGroups based on ClusterClasses, automatic label propagation from CAPI to Fleet resources, or CAPI-based Helm templating—you must install and enable CAAPF manually. Refer to the prerequisites below for more information. In this scenario, CAAPF takes over the responsibility of registering the cluster with Fleet.

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

If you have chosen the Advanced CAAPF automation scenario and want to continue using CAAPF for its advanced features, two configuration changes are required:

  • Set providers.addonFleet.enabled: true in the SUSE® Rancher Prime Cluster API Providers chart values to deploy the CAAPF provider.

    • CAAPF provider installation example:

      Click to Expand 
      helm upgrade --install rancher-turtles-providers oci://<REGISTRY_URL>/rancher/charts/rancher-turtles-providers \
    --namespace cattle-turtles-system \
    --set providers.addonFleet.enabled=true \
    --wait

  • Set features.use-caapf.enabled: true in the SUSE® Rancher Prime Cluster API 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.

Disabling CAAPF

To disable CAAPF and return to Rancher’s default Fleet management, you only need to disable the feature gate: Set features.use-caapf.enabled: false (the default value) in your SUSE® Rancher Prime Cluster API Helm chart configuration.

Once the feature gate is disabled, Turtles will automatically remove the provisioning.cattle.io/externally-managed annotation from any previously managed clusters, and Rancher will resume responsibility for installing and managing the Fleet agent on the workload clusters.