Rancher Fleet Bundle Deployment: GitOps at Scale (2026)

Rancher Fleet manages GitOps deployments for many clusters by treating Git repositories as the single source of truth for your cluster state.

Let’s see Fleet in action. Imagine we have a Git repository with our desired cluster configurations.

# clusters/dev.yaml
---
apiVersion: fleet.cattle.io/v1alpha1
kind: Cluster
metadata:
  name: dev-cluster
spec:
  kubernetesVersion: v1.27.9
  cgroupDriver: systemd
  containerRuntimeEndpoint: unix:///run/containerd/containerd.sock
  cloudProvider:
    aws:
      region: us-east-1
  rkeConfig:
    network:
      plugin: canal
    services:
      etcd:
        backup:
          interval: 12
          retention: 6
      kubeAPI:
        extraArgs:
          admission-control: namespace-lifecycle,limit-range
      kubeControllerManager:
        extraArgs:
          node-cidr-mask-size-ipv4: "24"
      kubeScheduler:
        extraArgs:
          scheduler-name: default-scheduler
      kubelet:
        clusterDomain: cluster.local
        failSwapOn: false
        extraEnv:
          - AWS_REGION: us-east-1
        extraArgs:
          cgroup-driver: systemd
          provider-id: aws://us-east-1/i-0123456789abcdef0
      cloudController:
        cloudProvider: aws
---
# apps/nginx-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.25.3
        ports:
        - containerPort: 80

Fleet watches this repository. When changes are detected, it synchronizes them to the target clusters. A Cluster resource in Git defines a target cluster. A Bundle resource defines a set of Kubernetes manifests to deploy. Fleet then creates these resources on the target cluster, effectively deploying your applications and configurations.

The problem Fleet solves is managing the state of potentially hundreds or thousands of Kubernetes clusters consistently. Instead of manually applying kubectl commands or using separate tools for each cluster, Fleet centralizes this. You define what your cluster should look like in Git, and Fleet makes it so. It handles the reconciliation loop, ensuring the cluster state matches the Git state.

Internally, Fleet works by having a Fleet agent running on each managed cluster. This agent communicates with the Fleet controller (often running in your management cluster). The controller monitors your Git repositories. When a change is detected, the controller updates BundleDeployment resources. The agent on the target cluster then pulls these BundleDeployment resources and applies the associated Kubernetes manifests to its local cluster.

You control Fleet through several key resources:

Cluster: Defines a target cluster to be managed. This can be a downstream cluster registered with a management cluster, or even the management cluster itself.
Bundle: A collection of Kubernetes manifests that you want to deploy. This is your application or configuration definition.
BundleDeployment: Links a Bundle to a specific Cluster. This is what tells Fleet which bundle to deploy where. Fleet automatically creates and manages these based on your Git repository structure and your Cluster definitions.
GitRepo: Defines the Git repository that Fleet should monitor for changes.

The GitRepo resource is where you point Fleet to your source of truth. You’ll specify the URL, branch, and potentially authentication details.

apiVersion: fleet.cattle.io/v1alpha1
kind: GitRepo
metadata:
  name: my-apps
  namespace: fleet-system # Or wherever your fleet controller is installed
spec:
  repo: https://github.com/my-org/my-fleet-repo.git
  branch: main
  paths:
    - apps/*
    - clusters/*

Fleet then parses this repository. It looks for Cluster resources in the clusters/ path and Bundle resources in the apps/ path. It then automatically generates BundleDeployment resources that target the defined clusters with the defined bundles. You don’t manually create BundleDeployment resources; Fleet does it for you based on your Git structure.

The critical insight most people miss is how Fleet’s automatic BundleDeployment generation works. You don’t explicitly say "deploy this bundle to this cluster." Instead, you define your Cluster resources and your Bundle resources in your Git repository. Fleet’s controller then intelligently creates BundleDeployment resources by matching patterns. For example, if you have a clusters/dev.yaml defining dev-cluster and apps/nginx-bundle.yaml defining an Nginx Bundle, Fleet will automatically create a BundleDeployment targeting dev-cluster with the nginx-bundle if the paths and naming conventions align with its expectations. This convention-over-configuration approach is key to scaling.

Once you have your Git repositories configured and your clusters registered, the next step is understanding how to manage secrets and sensitive information within your GitOps workflow using Fleet.