From 47891095f2740e1251f449f801f66d704289c717 Mon Sep 17 00:00:00 2001 From: potetochips86 Date: Mon, 9 Nov 2026 22:04:44 +0100 Subject: [PATCH 1/3] docs(operations): document talos-backup for etcd snapshots Signed-off-by: potetochips86 --- docs/operations/etcd-talos-backup.md | 69 ++++++++++++++++++++++++++++ zensical.toml | 1 + 2 files changed, 70 insertions(+) create mode 100644 docs/operations/etcd-talos-backup.md diff --git a/docs/operations/etcd-talos-backup.md b/docs/operations/etcd-talos-backup.md new file mode 100644 index 00000000..b481905a --- /dev/null +++ b/docs/operations/etcd-talos-backup.md @@ -0,0 +1,69 @@ +# Backing up your cluster with talos-backup + +Superphenix includes an implementation of Siderolab's [talos-backup](https://github.com/siderolabs/talos-backup) disaster recovery tool, a periodic etcd-snapshotter designed to run on Talos-based Kubernetes clusters. + +A CronJob is deployed on your cluster and periodically runs a job that takes an **etcd snapshot** and pushes it to **S3 storage**. + +Backups are compressed (with `zstd`) and encrypted (with `age`). + +To recover a cluster from an etcd snapshot, refer to the [official Talos documentation](https://docs.siderolabs.com/talos/v1.13/build-and-extend-talos/cluster-operations-and-maintenance/disaster-recovery#recovery). + + +## Prerequisites +Before enabling `talos-backup`, you will need to: + +- Have access to an S3 bucket. Your snapshots will be stored there. +- Have a pair of public/private **age** keys, used for snapshot encryption. You can [install age here](https://github.com/FiloSottile/age#installation) and run `age-keygen` to generate your pair of keys. +- Apply the following patch to your Talos **controlplane nodes** to allow Pod access to the Talos API: + ```yaml + # Talos machine configuration patch + spec: + machine: + features: + kubernetesTalosAPIAccess: + enabled: true + allowedRoles: + - os:etcd:backup + allowedKubernetesNamespaces: + - talos-backup # Namespace in which talos-backup is deployed + ``` + +## Enable `talos-backup` +Enable the tool from the Superphenix system configuration, using base64-encoded credentials for your S3 bucket: + +```yaml +systemConfiguration: + apps: + talos-backup: + enabled: true + values: + cronjob: + clusterName: "" # The name of your cluster (optional) + agePubKey: "" # Your age public key + s3: + endpointUrl: "" # Base64-encoded S3 endpoint + bucket: "" # Base64-encoded bucket name + accessKey: "" # Base64-encoded S3 access key + secretKey: "" # Base64-encoded S3 secret key +``` + +### Schedule +The CronJob is configured to run **every day at 07:00 UTC** by default. You can adjust this schedule by overriding the `cronjob.schedule` value. + +### Snapshot encryption +Snapshots are encrypted with **age** using your public key; it needs to be stored in the `cronjob.agePubKey` value. + +You can then decrypt your backups with your private key by running the following command: +```sh +age --decrypt -i .snap.zst.age > .snap.zst +``` +!!! note "Don't lose your keys" + Make sure to keep your keys safe to avoid losing access to your backups. + +### Compression +Before encryption, snapshots are compressed with the **ztsd** algorithm. After decrypting a backup, decompress it with the following command: +```sh +zstd --decompress ./.snap.zst +``` + +You can turn off compression by switching the `cronjob.enableCompression` value to `false`. \ No newline at end of file diff --git a/zensical.toml b/zensical.toml index a41c1769..4005b89d 100644 --- a/zensical.toml +++ b/zensical.toml @@ -130,6 +130,7 @@ nav = [ { "Configuring backups" = "operations/storage/configuring-backups.md" }, { "Using local storage" = "operations/storage/using-local-storage.md" } ]}, + { "Cluster backup and recovery" = "operations/etcd-talos-backup.md" }, { "Limitations" = "operations/limitations.md" } ]}, { "Reference" = [ From 671cdd8d7264a49765cfa9d7fce741ea811bb5a5 Mon Sep 17 00:00:00 2001 From: potetochips86 Date: Mon, 9 Nov 2026 22:44:09 +0100 Subject: [PATCH 2/3] fix(operations): minor fixes and typos Signed-off-by: potetochips86 --- docs/operations/etcd-talos-backup.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/operations/etcd-talos-backup.md b/docs/operations/etcd-talos-backup.md index b481905a..2ae8008d 100644 --- a/docs/operations/etcd-talos-backup.md +++ b/docs/operations/etcd-talos-backup.md @@ -17,15 +17,14 @@ Before enabling `talos-backup`, you will need to: - Apply the following patch to your Talos **controlplane nodes** to allow Pod access to the Talos API: ```yaml # Talos machine configuration patch - spec: - machine: - features: - kubernetesTalosAPIAccess: - enabled: true - allowedRoles: - - os:etcd:backup - allowedKubernetesNamespaces: - - talos-backup # Namespace in which talos-backup is deployed + machine: + features: + kubernetesTalosAPIAccess: + enabled: true + allowedRoles: + - os:etcd:backup + allowedKubernetesNamespaces: + - talos-backup # Namespace in which talos-backup is deployed ``` ## Enable `talos-backup` @@ -45,17 +44,18 @@ systemConfiguration: bucket: "" # Base64-encoded bucket name accessKey: "" # Base64-encoded S3 access key secretKey: "" # Base64-encoded S3 secret key + region: "" # Base64-encoded S3 region ``` ### Schedule The CronJob is configured to run **every day at 07:00 UTC** by default. You can adjust this schedule by overriding the `cronjob.schedule` value. ### Snapshot encryption -Snapshots are encrypted with **age** using your public key; it needs to be stored in the `cronjob.agePubKey` value. +Before being pushed to S3, snapshots are encrypted with **age** using your public key; it needs to be stored in the `cronjob.agePubKey` value. -You can then decrypt your backups with your private key by running the following command: +When you retrieve a backup from S3 (using any tool of your choice), you can then decrypt it with your private key by running the following command: ```sh -age --decrypt -i .snap.zst.age > .snap.zst +age --decrypt -i .age > ``` !!! note "Don't lose your keys" Make sure to keep your keys safe to avoid losing access to your backups. From c64fc6b35a4f36790be6f780df982d113dc87e13 Mon Sep 17 00:00:00 2001 From: potetochips86 Date: Mon, 9 Nov 2026 23:00:33 +0100 Subject: [PATCH 3/3] fix(operations): minor fixes Signed-off-by: potetochips86 --- docs/operations/etcd-talos-backup.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/operations/etcd-talos-backup.md b/docs/operations/etcd-talos-backup.md index 2ae8008d..9ff6ac96 100644 --- a/docs/operations/etcd-talos-backup.md +++ b/docs/operations/etcd-talos-backup.md @@ -55,7 +55,8 @@ Before being pushed to S3, snapshots are encrypted with **age** using your publi When you retrieve a backup from S3 (using any tool of your choice), you can then decrypt it with your private key by running the following command: ```sh -age --decrypt -i .age > +# Assuming the snapshot is compressed with zstd: +age --decrypt -i .snap.zst.age > .snap.zst ``` !!! note "Don't lose your keys" Make sure to keep your keys safe to avoid losing access to your backups. @@ -66,4 +67,4 @@ Before encryption, snapshots are compressed with the **ztsd** algorithm. After d zstd --decompress ./.snap.zst ``` -You can turn off compression by switching the `cronjob.enableCompression` value to `false`. \ No newline at end of file +You can turn off compression by switching the `cronjob.enableCompression` value to `false`. In that case, the decrypted file will be uncompressed already (no `.zst` extension) and you can skip this step. \ No newline at end of file