k8s-borgBorgBackup for Kubernetes

One Helm chart backs up the nodes, the cluster datastore, databases, S3 buckets and shared file systems into Borg repositories, deduplicated and encrypted on the client.

Install

Introduction

GitHub

# one release backs up the cluster
$ helm install my-borg \
    oci://ghcr.io/ioanalytica/charts/k8s-borg \
    --version 1.2.3 \
    -n k8s-borg --create-namespace \
    -f values.yaml

# the cluster's archives, from the console pod
$ kubectl -n k8s-borg exec \
    my-borg-k8s-borg-app-0 -- borg-list

Node backups

A DaemonSet backs up each node's own file systems into a repository per node, without the kubelet volumes and network mounts below them.

Cluster datastore

A consistent snapshot of etcd or k3s's SQLite on the control-plane nodes, with the token or PKI a rebuilt control plane needs.

Database dumps

MariaDB, MySQL, Percona Server, PostgreSQL, MongoDB, Redis and Valkey, with credentials from the operators' Secrets, left uncompressed so that Borg deduplicates them.

S3 and shared file systems

Buckets are mounted fresh and checked against their listing before each run; shared volumes and user homes go into the same backup.

Repository server

Optional borg serve over SSH, unprivileged, each client key bound to its own directory, with a copy of the repositories on S3 or SFTP.

Tested restores

Every engine's dump and restore runs against real servers in CI on every push, and each restore is written down step by step.

How it fits together

Each node backs up into a repository of its own, and the cluster data into another; the console pod has the Borg tools at hand for inspection and restores. With Borg UI, the node and console pods run as managed agents of a Borg UI server, one the chart deploys or an existing one; the UI itself is Borg UI, documented at docs.borgui.com.

Quick start

The chart is published as an OCI artifact; the images live on GitHub Container Registry. A first install needs an SSH host with Borg and a directory there for the repositories (mycluster below, which Borg 1 does not create), a passphrase, an SSH key the host accepts and the host's known_hosts line. The chart names no paths to back up by default: give them as R roots, here each node's /etc:

helm install my-borg oci://ghcr.io/ioanalytica/charts/k8s-borg \
  --version <version> -n k8s-borg --create-namespace \
  --set borg.repoBase.value="ssh://user@borg.example.com:22/./mycluster" \
  --set borg.passphrase.value="…" \
  --set-file ssh.privateKey=./id_ed25519 \
  --set-file ssh.knownHosts=./known_hosts \
  --set 'node.include={P fm,R /node/etc}'

ghcr.io/ioanalytica/k8s-borg:<tag>       # backup / agent / repository server image
ghcr.io/ioanalytica/k8s-borg-ui:<tag>    # Borg UI server image, built from the pinned borg-ui

For anything beyond a smoke test, keep the sensitive values in a pre-created Secret (existingSecret). The modes, the repository server, Borg 1 vs 2, the Borg UI options and every parameter are documented on the documentation site. A Flux HelmRelease with the Secrets it references is in examples/.