Implementing GitOps with Rancher Fleet for Multi-Cluster Workload Deployment

Achieving Consistent, Automated Workload Deployment Across Multiple Kubernetes Clusters

The problem is ensuring that the desired state of your applications—defined in a Git repository—is consistently and automatically applied across several distinct Kubernetes clusters managed by Rancher, without manual intervention on each cluster.

Useful Takeaway

Rancher Fleet acts as the native GitOps operator within Rancher Manager, enabling continuous delivery by monitoring Git repositories for Helm, Kustomize, or raw YAML manifests and applying them progressively to targeted downstream clusters.

Prerequisites for Fleet Operation

• A running Rancher Manager instance (version compatibility must be verified against official release notes).
• Target downstream Kubernetes clusters (RKE2, RKE1, or imported clusters) registered in Rancher.
• A Git repository containing deployment manifests (Helm charts, Kustomize overlays, or YAML).
• Appropriate credentials (SSH keys or tokens) stored securely within Rancher for Git access.

Procedure: Defining and Syncing Workloads

Fleet relies on two primary Custom Resources (CRs): GitRepo and Bundle.

1. Define the Source: Create a GitRepo resource in Rancher Manager, pointing to your manifest repository and providing necessary access credentials.
2. Define the Deployment: Create a Bundle resource, referencing the GitRepo. Use cluster or clusterGroup selectors to specify exactly which downstream clusters and namespaces should receive the deployment.
3. Monitor and Sync: Rancher Fleet continuously scans the repository. Once a change is detected, it attempts synchronization according to the bundle's defined rollout strategy.

Verification and Diagnostics

To confirm successful setup, verify the Fleet controller status and a sample deployment:

• Check Controller Health: Navigate to Cluster Manager > Fleet in the Rancher UI. Confirm the fleet-controller deployment is running in the fleet-local namespace on the Rancher Manager host.
• Test Deployment: Create a GitRepo pointing to a public manifest repository. Verify that a corresponding Bundle resource appears and transitions to the Applied state on one of the targeted downstream clusters.

Concrete Example: If a Bundle remains in a Pending or Error state on a downstream cluster, inspect the fleet-agent logs on that specific cluster for detailed synchronization failures, rather than solely relying on Rancher UI status.

Limitations and Recovery

Limitations: Fleet manages *application* state, not *cluster* lifecycle. It does not handle cluster upgrades, node provisioning, or etcd backups; use Rancher provisioning tools for those tasks. High volumes of GitRepo resources can strain the Fleet controller; tune scan intervals if necessary.

Recovery: If an operation changes state (e.g., a Bundle is applied), the state is managed by Git. If an unwanted state is reached, revert the change in the source Git repository and allow Fleet to detect and re-sync to the desired state. No direct rollback command is needed within Rancher Fleet for GitOps compliance.

Practical Check

Confirm the operational status by querying the Bundle resource status directly via the Rancher API or UI, ensuring the status.appliedState matches the expected deployment status on the target cluster.