cozystack/examples/backups/nats

NATS JetStream backup/restore example

This directory shows how to back up and restore a Cozystack-managed NATS application using the generic Job backup strategy. Unlike the app-specific drivers (Altinity for ClickHouse, CNPG for Postgres, ...), the Job strategy has no built-in knowledge of the application: it runs a Pod the operator supplies. Here that Pod is a stock natsio/nats-box image (which carries the nats CLI plus curl and tar) running one shell script:

• backup: nats stream backup → tar → PUT the tarball to S3.
• restore: GET the tarball from S3 → tar -x → nats stream restore.

The same PodTemplateSpec serves both directions. The strategy engine templates each string field independently — it cannot add or remove containers per mode — so the single image branches at runtime on {{ .Mode }} (rendered into the MODE env var). Backup pushes to a key scoped by the source app ({{ .Release.Name }}); restore reads the key scoped by the backup's source ({{ .Backup.ApplicationRef.Name }}), so a to-copy restore lands the source's data into a differently-named target.

The upload uses curl --aws-sigv4, so no purpose-built backup image is needed — a stock client image plus a shell one-liner is the whole driver. This is the point of the generic Job strategy: back up an app that has no dedicated driver, with tools you already have.

Step order

File	Role	Triggered by
00-helpers.sh	Shared bash helpers, env defaults, and the nats/S3-secret helpers; sourced by every step.	n/a
01-create-strategy.sh	Creates the cluster-scoped Job strategy (the nats-box PodTemplateSpec).	admin
02-create-backupclass.sh	Maps apps.cozystack.io/NATS to that strategy, with stream/natsUser parameters.	admin
03-create-bucket.sh	Provisions a Bucket and caches its S3 coordinates into .bucket-info.env (chmod 600; raw access keys). cleanup.sh removes this file.	admin. A tenant admin can create the Bucket itself, but the script also waits on its HelmRelease and COSI objects and reads the bucket-<name>-backup Secret; no tenant role grants access to helmreleases or objectstorage.k8s.io, or get on that Secret
04-create-nats.sh	Provisions a NATS instance, creates the <app>-backup-s3 Secret, seeds a JetStream stream with sentinel messages.	admin. A tenant admin can create the NATS itself, but the script also waits on its HelmRelease and StatefulSet, creates the Secret, and seeds the stream through a CLI Pod it execs into; no tenant role grants access to helmreleases or statefulsets, create on secrets or pods, or pods/exec
05-create-backupjob.sh	Submits a BackupJob and waits for Succeeded.	tenant
06-restore-in-place.sh	Deletes the stream and restores it into the same instance via RestoreJob.	admin. A tenant admin can submit the RestoreJob, but the script deletes and checks the stream through the CLI Pod; no tenant role grants create on pods or pods/exec
07-restore-to-copy.sh	Provisions a second NATS and restores into it via RestoreJob.spec.targetApplicationRef.	admin, for the same reasons as step 04. The tenant admin's part is the second NATS and the RestoreJob
cleanup.sh	Removes everything created by the demo.	admin: it deletes Secrets, the Backup, and the cluster-scoped BackupClass and strategy, and no tenant role grants delete on any of them
run-all.sh	Convenience runner that executes 01..07 in order.	demo
90-scenario-admin-prepare.md	Narrative for the admin preparation steps.	docs
91-scenario-user-backup.md	Narrative for the user backup flow.	docs
92-scenario-user-restore.md	Narrative for the user restore flow (in-place and to-copy).	docs

Environment variables (overrides)

All variables come from 00-helpers.sh:

Variable	Default	Description
NAMESPACE	tenant-test	Tenant namespace for the demo.
NATS_NAME	nats-test	Source NATS application name.
NATS_RESTORE_NAME	nats-restore	Target NATS for the to-copy restore.
NATS_USER	backup	NATS user the strategy authenticates as.
NATS_PASSWORD	jetstream-demo-pw	Password set on that user (kept fixed for a deterministic demo).
STREAM_NAME	ORDERS	JetStream stream to back up.
MESSAGE_COUNT	10	Sentinel messages published before backup.
BUCKET_NAME	nats-backups	Cozystack Bucket to provision.
BACKUPCLASS_NAME	nats-backup	BackupClass name (cluster-scoped).
STRATEGY_NAME	nats-job	Strategy name (cluster-scoped).
BACKUPJOB_NAME	nats-backup-job	BackupJob name.
RESTOREJOB_INPLACE_NAME	nats-restore-inplace	In-place RestoreJob name.
RESTOREJOB_TOCOPY_NAME	nats-restore-to-copy	To-copy RestoreJob name.
NATS_BOX_IMAGE	natsio/nats-box:0.14.5	Image with the nats CLI used by the strategy and the seed/verify helpers.

Prerequisites

• Cozystack cluster with the backup-controller and backupstrategy-controller installed.
• kubectl and jq locally.
• Egress to pull natsio/nats-box (used both by the strategy Pod and by the demo's seed/verify helpers).

Notes / caveats

• Not run in CI. Like every other directory under examples/backups/, this demo is a runnable reference, not an automated regression test — the e2e harness (hack/e2e-chainsaw/) does not exercise backup examples. Run it by hand against a cluster.
• nats CLI specifics. The strategy invokes nats stream backup/nats stream restore; flag names can vary across nats CLI versions. Pin NATS_BOX_IMAGE to a version whose CLI matches if the defaults drift.
• Self-signed S3. The COSI/seaweedfs S3 endpoint uses an internal CA, so the strategy passes -k to curl. A production strategy should mount the tenant CA and drop -k.
• Definitions vs. data. This backs up a JetStream stream's messages and configuration via nats stream backup; it does not capture NATS account or KV/object-store state beyond the named stream.