Fleet

Fleet deploys Kubernetes manifests, Kustomize overlays and Helm charts from Git to a set of clusters chosen by label. It is built for the case where one baseline must reach many clusters, including clusters behind NAT that a central server cannot reach. The official docs at fleet.rancher.io own the full CRD reference.

What it is

A set of Kubernetes controllers on a manager cluster, an agent on each downstream cluster, a group of CRDs in the fleet.cattle.io API group, and a fleet CLI. Rancher installs it automatically and shows it in the UI as Continuous Delivery. It also installs on any Kubernetes cluster from its own Helm charts, as a single-cluster setup (manager and agent in the same cluster) or a multi-cluster setup. Licence is Apache 2.0.

The current stable line is v0.16. v0.16.2 shipped 2026-09-18, on the same day as patch releases v0.15.7, v0.14.11, v0.13.16 and v0.12.20. v0.17 is in alpha. Patch releases in this line often carry security fixes: v0.16.1 and v0.16.2 together closed several CVEs in cluster registration, webhook handling, Helm values paths and downstream resource cloning.

v0.16.0 carried one breaking change. Helm repository credentials are no longer sent to a chart repository unless the chart URL matches the GitRepo's helmRepoURLRegex. A pre-upgrade Job fills that field on existing GitRepos. The same release added the Policy resource for multi-tenant setups and announced that GitRepoRestriction will be deprecated in v0.17 and may be removed as early as v0.18.

How it works

Fleet uses a two-stage pull model. The controller pulls from Git, and each agent pulls from the controller. The docs state that the controller does not start connections to downstream clusters. The only exception is optional manager-initiated registration. Agents do not need a constant connection; they catch up when they reconnect.

A GitRepo names a repository, a branch or revision, a list of paths and a list of targets. The gitjob controller runs a job that clones the repository and scans each path. A fleet.yaml file in any subpath starts a new Bundle. A path with a Chart.yaml is a Helm chart, a path with a kustomization.yaml is a Kustomize build, and any other .yaml file is a plain manifest. Fleet converts every bundle into a single Helm chart for deployment.

The controller matches each Bundle against the clusters and cluster groups in the GitRepo's namespace. For each match, it writes a BundleDeployment with the cluster-specific customizations into a namespace that belongs to that cluster alone. The agent on that cluster can only list BundleDeployments in its own namespace. It renders the chart, installs it as a Helm release and writes the status back.

When a downstream object is changed outside Git, the Bundle shows Modified. Drift correction (correctDrift.enabled, off by default) puts the Git state back. paused: true on a GitRepo stops changes from going down and marks the resources OutOfSync until the pause is removed. Inside Rancher, downstream clusters register with Fleet automatically, so the token path above only applies to standalone Fleet.

When to use it

Reach for it when:

• The same baseline (monitoring agents, policies, ingress, CRDs) must reach many clusters, selected by labels such as env or region.
• Clusters sit behind NAT, at edge sites or on networks that refuse inbound traffic.
• Rancher already manages the clusters, so Fleet is installed and every cluster is already registered.
• Rollouts across a large set of clusters need staging, with partitions and a limit on unavailable clusters.

Skip it when:

• There is one cluster and a team that wants a dedicated GitOps web UI per application. Argo CD ships one.
• The workflow depends on ordered syncs with Argo CD sync waves and PreSync/PostSync hooks, or on Flux image update automation.
• The clusters are not managed by Rancher and nobody wants to run the manual multi-cluster registration. The docs note that this standalone path is not QA-tested by Rancher.

At a glance

Core concepts

• GitRepo — a watched repository: URL, branch or revision, paths, targets, polling and credentials.
• HelmOp — a chart deployed straight from a Helm repository or OCI registry, with no Git repository.
• Bundle — the internal unit Fleet produces from one scanned path. Deployed as one Helm chart.
• BundleDeployment — one Bundle for one cluster, carrying that cluster's customizations.
• Cluster and ClusterGroup — registered downstream clusters and label-selected sets of them.
• Workspace — a namespace on the manager that holds GitRepos and clusters. In Rancher, fleet-local holds the local cluster and fleet-default holds every downstream cluster registered through Rancher.
• targetCustomizations — per-target overrides in fleet.yaml. targetCustomizationMode: FirstMatch (the default) applies the first match; AllMatches merges every match in order.
• Policy — new in v0.16; limits which service accounts, secrets and source repositories the GitRepos, HelmOps and Bundles in a namespace may use.

Key facts (v0.16)

Item	Value
Licence	Apache 2.0
Latest stable	v0.16.2 (2026-09-18)
Next line	v0.17 (alpha)
Install namespace	cattle-fleet-system
Helm charts	fleet-crd, fleet from rancher.github.io/fleet-helm-charts
Default polling interval	15 seconds
Default target	the default cluster group
Bundle size limit	resources must gzip to less than 1 MB
Drift correction	off by default
Connection direction	agent to manager only

Fleet compared with Argo CD

Aspect	Fleet	Argo CD
Model	Agent on each cluster pulls from the manager	Central controller connects to each registered cluster's API server
Inbound access to clusters	Not needed	The central instance must reach each cluster's API server, with credentials kept in a cluster Secret
Unit of deploy	Bundle, installed as a Helm release	Application; Helm charts are only rendered with helm template, and Argo CD applies the manifests
Many clusters from one definition	Targets and cluster groups on the GitRepo	ApplicationSet with the Cluster generator, one Application per cluster
Ordering	dependsOn between Bundles	Sync waves and sync hooks
UI	Rancher Continuous Delivery pages	Its own web UI and CLI
Rancher integration	Built in, auto-registration	Separate install

How to integrate

Standalone install

helm repo add fleet https://rancher.github.io/fleet-helm-charts/
helm -n cattle-fleet-system install --create-namespace --wait fleet-crd fleet/fleet-crd
helm -n cattle-fleet-system install --create-namespace --wait fleet fleet/fleet
kubectl -n cattle-fleet-system get pods -l app=fleet-controller

For a multi-cluster manager, add --set apiServerURL=https://manager.example.com:6443 and --set-file apiServerCA=ca.pem to the second install. Without them, only agent-initiated registration works. Rancher users skip this step: Rancher ships its own Fleet charts.

A GitRepo with label targets

apiVersion: fleet.cattle.io/v1alpha1
kind: GitRepo
metadata:
  name: baseline
  namespace: fleet-default          # fleet-local for a single-cluster setup
spec:
  repo: https://github.com/example/platform-baseline.git
  branch: main
  paths:
    - monitoring
    - policies
  clientSecretName: git-auth        # basic auth, SSH key or GitHub App secret in this namespace
  helmRepoURLRegex: "^https://charts\\.example\\.com/.*"   # required since v0.16 for Helm credentials
  correctDrift:
    enabled: true
  targets:
    - name: prod
      clusterSelector:
        matchLabels:
          env: prod
    - name: everything-else
      clusterGroup: non-prod

Targets are alternatives, checked in order. A cluster that matches the first entry is not checked against the later ones.

A fleet.yaml for one path

defaultNamespace: monitoring
helm:
  repo: https://charts.example.com
  chart: node-exporter
  version: 4.2.0
  releaseName: node-exporter
  values:
    resources:
      limits:
        memory: 64Mi
targetCustomizations:
  - name: edge
    clusterSelector:
      matchLabels:
        site: edge
    helm:
      values:
        resources:
          limits:
            memory: 32Mi
  - name: skip-lab
    clusterSelector:
      matchLabels:
        env: lab
    doNotDeploy: true

Check the result

kubectl -n fleet-default get gitrepos
kubectl -n fleet-default get bundles
kubectl get bundledeployments -A

In the GL stack

Fleet v0.16.2 runs on the management cluster, installed by Rancher v2.15.2 as part of Rancher itself. Rancher's continuous-delivery feature is turned off and there are no GitRepos. With the feature off, Fleet stays installed (the Rancher docs say it cannot be fully disabled), and its only job is to deliver Rancher's own agent bundles to the managed clusters.

All application GitOps runs through Argo CD on the management cluster: one app for the beta cluster that tracks the beta branch, and one for the prod cluster that tracks main, both synced by hand. The split keeps one GitOps tool in charge of every application, so no workload has two controllers that could fight over its state. Fleet is described here because it is present in every Rancher install, and because the reason it is not used for apps is a design choice.

Gotchas

• Helm credentials stop flowing after the v0.16 upgrade. If a GitRepo uses helmSecretName and its chart URL does not match helmRepoURLRegex, the credentials are no longer sent and the chart pull fails. Check the field the migration Job filled in.
• GitRepoRestriction is on its way out. Its repo patterns match unanchored, and it does not cover HelmOps or Bundles. Move multi-tenant setups to Policy before v0.18.
• Unauthenticated webhooks still work but now log warnings. Configure a webhook secret; the release notes say unauthenticated calls will be deprecated.
• No targets does not mean no clusters. An empty targets list maps to the default cluster group. Clusters in a group with that name receive the GitRepo.
• First match wins twice. Both targets and, by default, targetCustomizations stop at the first matching entry. Put the most specific entry first, or set targetCustomizationMode: AllMatches for the customizations.
• Bundles have a size cap. Resources in one bundle must gzip to under 1 MB. Large CRD sets or generated manifests may need to be split across paths.
• Rancher backups miss GitRepo secrets. The Rancher docs list a known issue: clientSecretName and helmSecretName secrets are not included in Rancher backups and restores. Keep them in a secret store that can recreate them.
• Turning off continuous delivery in Rancher removes gitjob only. Fleet's controller and agents keep running, because Rancher still depends on them.

Risks

• Licence and stewardship. Apache 2.0 and developed in the open by SUSE's Rancher team. Release cadence and direction follow Rancher's roadmap; a standalone user has less pull on that roadmap than a Rancher Prime customer.
• Security surface. Recent patch releases fixed several CVEs in registration, webhooks and Helm handling. The agent installs whatever its BundleDeployments name, so write access to a watched repository is effectively deploy access to every targeted cluster. Track the patch lines and restrict repository write access.
• Lock-in. Content is plain YAML, Kustomize and Helm, so it moves to another tool with little work. fleet.yaml options (target customizations, overlays, rollout partitions) do not, and need to be rewritten for Argo CD or Flux.
• Operational visibility. Outside Rancher, status lives in CRDs and the CLI, with no dedicated UI. Debugging a failed bundle means reading BundleDeployment status and agent logs.

Alternatives

• Argo CD — pick it for application-centric delivery with its own web UI, sync waves and hooks, and ApplicationSets for many clusters.
• Flux — pick it for a set of composable GitOps controllers driven by custom resources, with optional image update automation that commits new tags to Git.
• Sveltos — pick it to deploy Helm charts, YAML and Kustomize from a management cluster to clusters chosen by label selector, without Rancher (Apache 2.0).
• Helm or Helmfile from a CI job — pick it for a small number of clusters that CI can reach directly, where drift detection is not needed.

Related

• Rancher — the management server that installs Fleet and registers clusters with it.
• Argo CD — the GitOps tool that runs all application delivery in this stack.
• K3s — the Kubernetes distribution on every cluster Fleet reaches.
• System Upgrade Controller — the other Rancher-managed controller that changes cluster state, for K3s upgrades.
• Rancher Backups — the operator that backs up Rancher's state, minus GitRepo secrets.
• Official: Fleet docs, Architecture, fleet.yaml reference, Releases.