Deploy Helm and Kubernetes Workloads with Rancher Fleet

When you maintain dozens of clusters across dev, staging, and production, applying the same Helm chart or raw manifests by hand is error‑prone. A single mis‑applied change can create drift that is hard to detect and fix. Rancher Fleet solves this by turning a Git repository into a declarative source of truth that automatically reconciles workloads on any cluster that matches a label selector.

Fleet: Rancher’s Built‑in GitOps Engine

Fleet is bundled with Rancher and runs as a controller in the management cluster. It watches one or more GitRepo resources, pulls the desired branch or tag, and applies the contents to downstream clusters through Bundle and BundleDeployment objects. The reconciliation loop is pull‑based; agents on each downstream cluster connect back to the server, making Fleet suitable for firewalled clusters that only allow outbound traffic.

Core Fleet Resources

• GitRepo – Points to a Git URL, branch, and optional subdirectory. This is the single source of truth.
• Bundle – Defines the application to deploy. It can reference a Helm chart, a Kustomize overlay, or a directory of plain Kubernetes manifests.
• BundleDeployment – Maps a Bundle to a set of clusters (via label selectors) and a namespace. It also allows per‑cluster configuration overrides.

Concrete Example: Deploying Nginx Across Dev and Prod

Below is a step‑by‑step example that demonstrates how to use Fleet to deploy a standard Nginx ingress controller to all dev clusters and a hardened version only to prod clusters.

1. Label Your Clusters

First, add an env label to each cluster. This can be done from the Rancher UI or via the CLI. The labels are used by BundleDeployment to target the correct clusters.

# Run on the Rancher management cluster
kubectl label cluster dev-cluster-01 env=dev
kubectl label cluster prod-cluster-01 env=prod

2. Create the GitRepo

Apply a GitRepo object that points to a public repository containing the Nginx manifests. Replace https://github.com/example/fleet-manifests with your own repository URL.

apiVersion: fleet.cattle.io/v1alpha1
kind: GitRepo
metadata:
  name: nginx-repo
spec:
  repo:
    url: https://github.com/example/fleet-manifests
    branch: main
  subdirectory: nginx

3. Define the Bundle

The bundle is a lightweight wrapper that references the GitRepo. In this example we deploy the Helm chart directly from the repo.

apiVersion: fleet.cattle.io/v1alpha1
kind: Bundle
metadata:
  name: nginx-bundle
spec:
  bundleRef:
    repoName: nginx-repo
    path: helm

4. Create BundleDeployments

Deploy the bundle to dev clusters:

apiVersion: fleet.cattle.io/v1alpha1
kind: BundleDeployment
metadata:
  name: nginx-dev
spec:
  bundleRef:
    name: nginx-bundle
  target:
    cluster:
      matchLabels:
        env: dev
    namespace: ingress-nginx

And to prod clusters with a custom values file:

apiVersion: fleet.cattle.io/v1alpha1
kind: BundleDeployment
metadata:
  name: nginx-prod
spec:
  bundleRef:
    name: nginx-bundle
  target:
    cluster:
      matchLabels:
        env: prod
    namespace: ingress-nginx
  values:
    - values-prod.yaml

5. Verify the Deployment

On the management cluster, check the status of the BundleDeployment objects:

kubectl get bundledeployments -n fleet-system

Look for the Ready column. On a downstream cluster, you can confirm the Nginx pods are running:

kubectl get pods -n ingress-nginx

Operational Trade‑offs and Caveats

• Repository Size – A monolithic repo with many applications increases Fleet’s scan time and memory usage. Split unrelated apps into separate repos or use the subdirectory field to limit the scan.
• Cluster Provisioning – Fleet only manages workloads. You must provision clusters first with Rancher RKE2, K3s, or another driver before Fleet can target them.
• RBAC Scope – Fleet permissions are scoped to the namespace of the Bundle. They do not inherit Rancher project roles automatically, so review the service accounts used by Fleet agents in downstream clusters.
• Air‑gapped Installations – Pre‑pull Fleet images and configure a private registry. Verify image pull secrets on the management cluster before deploying Fleet.
• Connectivity – Fleet agents require outbound access to the Rancher server. If outbound traffic is blocked, consider setting up a reverse proxy or VPN.

Takeaway

Rancher Fleet turns a Git repository into a single source of truth for Kubernetes workloads across any number of clusters. By leveraging cluster labels and declarative resources, you can promote the same Helm chart or manifest from dev to prod with a single change in Git. Just be mindful of repo size, RBAC, and cluster provisioning to keep the system healthy.