Rancher Fleet: Deliver Helm Charts Across Clusters Without Sharing Kubeconfigs

Stop shipping kubeconfigs to CI for every cluster

You operate three downstream Kubernetes clusters and one Helm chart that must run on all of them. Your CI pipeline currently stores three kubeconfigs, rotates three credential sets, and still depends on someone remembering to run kubectl apply after a promotion. Rancher Fleet changes that model. The Fleet agent runs on each downstream cluster, and a single GitRepo custom resource tells the agent which Git repository and Helm chart to synchronize. Git becomes the source of truth, and CI stops needing direct cluster access.

What a GitRepo resource controls

In Rancher 2.x, Fleet is the built-in GitOps controller. It watches GitRepo custom resources, which describe a Git repository, a target cluster or group of clusters, and optional Helm values. When the resource is accepted, Fleet creates a Bundle and the Fleet agent on the target cluster applies the chart or manifests. Access can be scoped at the cluster, project, or namespace level, so a platform team can retain cluster-level control while delegating individual workloads to project owners.

Behavior and CRD field names differ between Rancher 2.5, 2.6, and 2.7. Check the Rancher version in the UI header before copying automation from another major release.

Worked example: sync one chart to two clusters

Create a file named platform-gitrepo.yaml. Replace every placeholder with values from your environment.

apiVersion: fleet.cattle.io/v1alpha1
kind: GitRepo
metadata:
  name: 
  namespace: 
spec:
  repo: 
  branch: main
  targets:
    - cluster: 
    - cluster: 
  helm:
    chart: 
    valuesFiles:
      - values.yaml

Run the apply from a workstation whose kubectl context points to the cluster where Fleet accepts GitRepo resources—typically the Rancher management cluster or the downstream cluster running the Fleet agent, depending on your installation model.

• Permissions: cluster-admin, or a project role with Fleet write access in the target namespace.
• Command: kubectl apply -f platform-gitrepo.yaml
• Expected check: kubectl get gitrepo should show a Ready condition, and kubectl get bundles -A should list a Bundle for each target cluster.
• Risk: A mistyped cluster name in targets produces no deployment and no obvious error until you inspect the Bundle status.

If you use a monorepo with many subdirectories, be aware that reconciliation latency and Fleet agent memory usage can grow as the number of GitRepo resources and watched paths increases.

Scope access instead of sharing credentials

Fleet supports three common scopes. A cluster-scoped GitRepo is appropriate for platform tooling such as ingress controllers or monitoring agents. A project- or namespace-scoped GitRepo lets a team manage its own workloads without touching cluster-wide resources. In all cases, the Fleet agent pulls from Git, so CI never needs a downstream kubeconfig.

Limitations and a practical verification step

Fleet does not replace cluster lifecycle management. Use RKE2 or RKE1 provisioning separately to create and upgrade clusters; Fleet only delivers applications and manifests to clusters that already exist.

Before trusting Fleet with production workloads, verify the control plane components are running. In the Rancher UI, open Apps or Fleet and confirm the fleet-crd and fleet-agent deployments are present. Then apply a sample GitRepo targeting one non-production cluster and watch the Bundle status in the Fleet dashboard. Compare the Rancher version shown in the UI header against the release notes for that major version, because GitRepo fields and dashboard behavior can change.

Roll back a GitRepo safely

Because applying a GitRepo changes cluster state, you can remove it with:

kubectl delete gitrepo  -n 

Fleet garbage-collects the Bundle and the resources it deployed. Confirm removal with kubectl get bundles -A and by checking the downstream cluster workloads.

Start with one chart and one cluster

Pick a single internal Helm chart and one downstream cluster. Create the GitRepo, confirm the Bundle reaches an installed state, and only then add additional clusters or teams. Fleet centralizes delivery, but you still control the rollout pace.