This is unreleased documentation for Cluster API v0.28-dev.

Cluster Resource Relationships in SUSE® Rancher Prime Cluster API

Overview

Rancher integrates several components that define their own Cluster custom resources. SUSE® Rancher Prime Cluster API builds on this foundation using Cluster API and Fleet, which can lead to confusion around how these Cluster resources interact and what users should edit.

This document explains the purpose, behavior, and relationships between the following cluster resources:

  • clusters.cluster.x-k8s.io (CAPI Cluster)

  • clusters.management.cattle.io (Management Cluster)

  • clusters.provisioning.cattle.io (Provisioning Cluster)

  • clusters.fleet.cattle.io (Fleet Cluster)

Resource Summary

API Group Cluster Resource Role

cluster.x-k8s.io

CAPI Cluster

Defines the cluster lifecycle and topology. Acts as the source of truth in Turtles.

management.cattle.io

Management Cluster

Rancher’s current cluster representation. management.cattle.io/v3 clusters are now the default resource created and managed by Turtles. This should not be confused with CAPI-managed clusters, where “managed” refers to Cluster API lifecycle management, not Rancher’s management.cattle.io API group.

provisioning.cattle.io

Provisioning Cluster

Rancher’s earlier general-purpose cluster abstraction. Encapsulates both infrastructure-agnostic and provider-specific configuration, and is required for generating cluster registration tokens and manifests. In SUSE® Rancher Prime Cluster API, this resource has been used to wrap imported CAPI clusters, but it is being phased out.

fleet.cattle.io

Fleet Cluster

Used for GitOps bundle targeting and application synchronization via Fleet.

Relationships

CAPI Cluster → Management Cluster

When a CAPI cluster is marked for import, Turtles creates a clusters.management.cattle.io. Users are abstracted from interacting with this cluster, as Turtles acts as the interface between the CAPI cluster and the Rancher management layer.

Management Cluster → Provisioning Cluster

A provisioning.cattle.io.Cluster is created to represent the CAPI Cluster and expose Rancher-specific fields (e.g., display name, RKE config).

CAPI Cluster → Fleet Cluster

Rancher handles the creation of the Fleet cluster object when a CAPI cluster is imported.

The Turtles import controller automatically propagates labels and annotations from the CAPI Cluster to the corresponding Fleet Cluster via the Management Cluster. This enables targeting GitOps bundles via label selectors.

Label Propagation Behavior

From → To Propagation Notes

CAPI → Management

Yes

Propagated by Turtles

CAPI → Fleet

Yes

Propagated by Turtles via Management cluster

Label propagation also applies to the Provisioning cluster via the Management cluster, but it was purposely left out of the table because Turtles does not interact directly with this resource and the CAPI cluster is considered the single source of truth.

What Should Users Edit?

Recommended: cluster.x-k8s.io.Cluster

The CAPI Cluster is the authoritative resource for cluster definition in SUSE® Rancher Prime Cluster API. Labels must be placed on the CAPI Cluster object. They will automatically propagate to the Fleet Cluster, enabling label-based bundle selectors to work as expected.

Labels of the domain cattle.io and x-k8s.io are reserved for Rancher and CAPI internal use, respectively, and they’re filtered out of propagation.

Avoid: management.cattle.io.Cluster

These resources are internal and fully managed by Rancher. Do not modify them.

Avoid: provisioning.cattle.io.Cluster

These resources are internal and fully managed by Rancher. Do not modify them.

Avoid: fleet.cattle.io.Cluster

Fleet Clusters are managed automatically. Edits are discouraged unless working on Fleet internals.

  • The CAPI Cluster is the source of truth.

  • Fleet Clusters are generated automatically from CAPI Clusters on import.

  • Provisioning and Management Clusters are automatically managed by Turtles and Rancher.

Use the CAPI Cluster’s labels to drive Fleet bundle deployment. The Turtles controller ensures those labels are synced to the Fleet Cluster object.

References