Rancher Backup

Rancher Backup is the operator that saves and restores the state of a Rancher server: its users, auth settings, roles, cluster registrations, projects and settings, which all live as custom resources and secrets on the cluster that hosts Rancher. If that cluster is lost, the backup file plus a fresh cluster brings the same Rancher back, and the downstream clusters reconnect to it. The official guides at ranchermanager.docs.rancher.com own the full reference.

What it is

A Kubernetes operator from the rancher/backup-restore-operator repository, shipped as two Helm charts: rancher-backup-crd (the CRDs) and rancher-backup (the operator). It installs into the cattle-resources-system namespace and appears in the Rancher UI as Rancher Backups under cluster tools. Licence is Apache 2.0.

Its scope is narrow on purpose. The README lists three uses: back up before a Rancher upgrade and restore after a failed one, restore Rancher to a new cluster after a disaster, and migrate Rancher between Kubernetes distributions of the same version. It states that it does not take downstream cluster snapshots, does not replace etcd backups, and does not back up user workloads on the Rancher cluster. For those, see Velero.

The operator's major version tracks Rancher's minor version. Each line has its own release branch:

Rancher	Operator line	Latest stable (2026-09-21)
v2.15.x	v11.x	v11.0.3
v2.14.x	v10.x	v10.0.10
v2.13.x	v9.x	v9.0.8
v2.12.x	v8.x	v8.1.9
v2.11.x	v7.x	v7.0.11

Release candidates v11.0.4-rc.2 and siblings on every line followed in mid-October 2026 with Go toolchain and dependency security updates; no breaking change is listed. The v11 chart declares kubeVersion >= 1.34 and Rancher >= 2.15.0 < 2.16.0.

How it works

Three cluster-scoped CRDs in the resources.cattle.io group carry the whole design. A ResourceSet lists which resource types, namespaces and name patterns to capture. A Backup points at a ResourceSet and a storage location, with an optional cron schedule, a retention count and an encryption secret. A Restore names one backup file and replays it.

The operator does not read etcd. It asks the Kubernetes API for every object the ResourceSet matches, keeps ownerReferences so dependencies survive, and packs the objects into a .tar.gz (.tar.gz.enc when encrypted). On restore it reads the tarball back and applies the objects to the API server of whichever cluster it is installed on. Because it works through the API, the host can be any Kubernetes distribution that Rancher supports.

The order in the restore path matters. The migration guide says to restore first and install Rancher after; a running Rancher on the target cluster creates its own default objects, and those conflict with the restored ones. With the same hostname, the downstream agents dial the same URL and reconnect to the new server.

Storage options

The chart sets one operator-level default storage location: none, an S3-compatible bucket, a PVC from a StorageClass, or an existing PV. A single Backup or Restore can override the default, but only with an S3 location. S3 settings are bucketName, folder (one level only, no nested folders), region, endpoint, endpointCA and insecureTLSSkipVerify, plus a credential secret with accessKey and secretKey.

Encryption

The API server returns secrets in plaintext, so an unencrypted backup of the full resource set holds every Rancher secret in the clear. Encryption uses the same EncryptionConfiguration format as Kubernetes encryption at rest, stored in a secret in cattle-resources-system. The operator does not save that file anywhere. Without it, an encrypted backup can not be restored.

When to use it

Reach for it when:

• You run Rancher on Helm and need to recover from a failed upgrade or a lost host cluster.
• You want to move Rancher to new hardware or a different distribution (K3s to RKE2, for example) at the same Rancher version.
• You want a small, Rancher-aware backup that knows exactly which CRDs and secrets Rancher needs.

Skip it when:

• You need workload or volume backups. Use Velero or database-native tooling.
• You run Rancher as a single Docker container. That install has its own backup procedure.
• You need to restore a downstream cluster. Use that cluster's etcd snapshots or Velero.

At a glance

Core concepts

• ResourceSet — what to capture. rancher-resource-set-full includes secrets and is the documented choice for production; rancher-resource-set-basic leaves secrets out. The old rancher-resource-set default is deprecated.
• Backup — one-time when schedule is empty, recurring with a cron string or @midnight-style descriptor. retentionCount defaults to 10.
• Restore — names one backupFilename. prune (default true) deletes Rancher-managed resources that are not in the backup; set it to false for a migration onto a fresh cluster.
• Encryption config secret — the key material. Back it up separately from the backups.

Key facts

Item	Value
Charts	rancher-backup-crd, rancher-backup from https://charts.rancher.io
Namespace	cattle-resources-system
CRD group	resources.cattle.io/v1 (cluster-scoped)
Output	.tar.gz, or .tar.gz.enc with encryption
Default PVC size	2Gi, mounted at /var/lib/backups
PVC name	<release>-<revision> unless persistence.volumeName is set
Version rule	Restore into the same Rancher version the backup came from

Rancher Backup vs Velero

Aspect	Rancher Backup	Velero
Scope	Rancher's own resources only	Any namespaces, objects and volume data
Selection	Curated ResourceSets shipped by Rancher	Namespace, type and label filters
Volume data	None	Kopia file-system backup or snapshots
Restore target	Same or new cluster, before Rancher is installed	Same or new cluster, any time
Encryption	Kubernetes EncryptionConfiguration	Kopia repository key

The two complement each other: Velero for workloads, Rancher Backup for the Rancher server.

How to integrate

Install both charts with a version that matches the Rancher line (v11.x for Rancher v2.15), then create the encryption secret and a scheduled Backup.

helm repo add rancher-charts https://charts.rancher.io
helm repo update
helm install rancher-backup-crd rancher-charts/rancher-backup-crd \
  -n cattle-resources-system --create-namespace --version <chart-version>
helm install rancher-backup rancher-charts/rancher-backup \
  -n cattle-resources-system --version <chart-version> \
  --set persistence.enabled=true \
  --set persistence.storageClass=<retain-class> \
  --set persistence.size=2Gi

An encryption config, the same format the API server uses for encryption at rest:

# encryption-provider-config.yaml (keep a copy outside the cluster)
apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
  - resources: ["secrets"]
    providers:
      - aescbc:
          keys:
            - name: key1
              secret: <base64 32-byte key>

kubectl create secret generic encryptionconfig \
  --from-file=./encryption-provider-config.yaml -n cattle-resources-system

A nightly encrypted full backup to the operator's default location:

apiVersion: resources.cattle.io/v1
kind: Backup
metadata:
  name: rancher-nightly
spec:
  resourceSetName: rancher-resource-set-full
  encryptionConfigSecretName: encryptionconfig
  schedule: "0 3 * * *"
  retentionCount: 14

The restore on a new cluster, before Rancher is installed:

apiVersion: resources.cattle.io/v1
kind: Restore
metadata:
  name: restore-migration
spec:
  backupFilename: <backup-file-name>.tar.gz.enc
  prune: false
  encryptionConfigSecretName: encryptionconfig
  storageLocation:
    s3:
      credentialSecretName: s3-creds
      credentialSecretNamespace: default
      bucketName: <bucket>
      folder: <folder>
      endpoint: <s3-endpoint>

kubectl apply -f restore-migration.yaml
kubectl get restore
kubectl logs -n cattle-resources-system -f -l app.kubernetes.io/instance=rancher-backup
# when the Restore is Completed: install cert-manager, then Rancher at the same version
helm install rancher rancher-stable/rancher -n cattle-system \
  --set hostname=<original-hostname> --version <same-version>

helm get values rancher -n cattle-system -o yaml on the old cluster gives the values file to reuse on the new one.

In the GL stack

Rancher Backup v11.0.3 runs on the management cluster, next to the Rancher server that manages the three K3s clusters behind builddaily.io, paiddaily.io and the other products.

• What is captured. A nightly backup of the full resource set, encrypted with an EncryptionConfiguration, so Rancher's secrets are never in a file in plaintext.
• Where it lands. The operator only speaks HTTPS S3, so its default storage location is a PVC. A separate CronJob copies each new file from the PVC to the cluster's S3 store, which puts the backups outside the PVC's lifecycle.
• Copy, never sync. The drill showed that the chart names the PVC after the Helm release and revision, so a chart upgrade creates a new, empty PVC. A sync from that empty volume would delete every backup in the bucket. The copy job only adds files.
• Restore drill. A restore was drilled on a throwaway VM, with Rancher installed on top afterwards. The restore took 51 seconds, and Rancher came up with all users, auth settings and clusters in place.

Gotchas

• A chart upgrade makes a new, empty PVC. The chart names the PVC <release>-<revision> (see backupRestore.pvcName in the chart helpers) unless persistence.volumeName is set. After helm upgrade, the operator writes to a fresh volume and the old backups sit on an orphaned PVC. Set volumeName to a pre-made PV, or copy files off the volume. Any job that mirrors the PVC to a bucket must copy, not sync, or the first run after an upgrade wipes the bucket.
• Use a Retain reclaim policy. The storage docs warn that deleting the PVC can delete the PV and every backup on it, which can happen during an app upgrade. Pick a StorageClass with reclaimPolicy: Retain, or patch the PV after it is provisioned.
• HTTPS-only S3 in practice. In this setup the operator only spoke HTTPS to S3. An in-cluster store on plain HTTP needs a TLS front, or the PVC-plus-copy pattern above.
• Restore before Rancher, not after. The migration guide warns against installing Rancher on the target cluster before the restore. Install only the two backup charts, restore, then install cert-manager and Rancher.
• Same version, same hostname. Restore into the Rancher version the backup came from, and install Rancher with the original hostname; a new hostname leaves downstream clusters Unavailable.
• Prune on a migration. prune defaults to true. Set it to false when restoring onto a fresh cluster, as the migration guide shows.
• The encryption file is not saved. Lose the EncryptionConfiguration and every .enc backup is unreadable. A wrong config makes the restore fail.
• HostPath PVCs need root. The chart runs as non-root by default; a hostPath-backed PVC needs securityContext.runAsNonRoot=false to be writable, which the chart comments mark as against best practice.
• Fleet secrets after restore. The backup docs list a known issue: secrets referenced by Fleet GitRepos through clientSecretName and helmSecretName are missing after a restore and need the documented workaround.
• Changing distributions needs an edit. For K3s to RKE2 or similar, edit clusters.management.cattle.io local before Rancher starts: set status.driver to imported and remove the provider-specific fields the guide lists.

Risks

• Licence and stewardship. Apache 2.0, maintained by SUSE's Rancher team. Release cadence follows Rancher's, with every supported line patched on the same day.
• Version lock. A backup is only good for the Rancher version that made it. A backup taken before an upgrade can restore the old version, not the new one; take a fresh backup after each upgrade.
• Secret concentration. A full backup holds every credential Rancher has, including access to every managed cluster. The encryption key and bucket credentials deserve cluster-admin care.
• Untested backups. A completed Backup proves a file was written, not that a restore works. Only a restore drill on a scratch cluster shows that the encryption key, the version and the steps line up.

Alternatives

• Velero — pick it to back up workloads and volumes, or the whole Rancher cluster as a general backup; it has no knowledge of which Rancher resources matter.
• K3s or RKE2 etcd snapshots — pick them to roll back the entire host cluster at once, including everything else on it; they do not help with a migration to a different distribution.
• Rancher single-node backup — the documented path for the Docker single-container install, which this operator does not cover.

Related

• Rancher — the server this operator protects.
• Velero — workload and volume backups on the same clusters.
• K3s and Lima — the host cluster and the VMs a rebuild starts from.
• SeaweedFS and MinIO — S3-compatible stores for backup files.
• Backup layer — how the backup services fit together.
• Official: backup-restore-operator repo, Migrating Rancher to a new cluster, Storage configuration, Releases.