Soteria is a small in-cluster service that orchestrates Longhorn backups for PVCs. It is intended to be called by Ariadne (or another controller) and focuses on:

Longhorn-managed backups to an S3-compatible backend (Backblaze B2 by default).
On-demand restore tests into a target PVC.
Minimal long-running footprint (the backup work happens in Longhorn).

Snapshots are managed by Longhorn; backups are crash-consistent for the PVC as mounted.

API

POST /v1/backup (Longhorn)

{
  "namespace": "ai",
  "pvc": "llm-cache",
  "tags": ["namespace=ai", "service=llm"],
  "dry_run": false
}

Response:

{
  "job_name": "soteria-backup-llm-cache-20260131-013001",
  "namespace": "ai",
  "secret": "soteria-soteria-backup-llm-cache-20260131-013001-restic",
  "dry_run": false
}

POST /v1/restore-test (Longhorn)

{
  "namespace": "ai",
  "snapshot": "latest",
  "pvc": "ollama-models",
  "target_pvc": "restore-sandbox",
  "dry_run": false
}

Notes:

pvc is required to resolve the Longhorn volume and locate the latest backup.
snapshot may be latest or a specific backup/snapshot name. You can also pass backup_url.

Configuration

Environment variables:

SOTERIA_BACKUP_DRIVER (default: longhorn, allowed: longhorn, restic)
SOTERIA_LONGHORN_URL (default: http://longhorn-backend.longhorn-system.svc:9500)
SOTERIA_LONGHORN_BACKUP_MODE (default: incremental, allowed: incremental, full)
SOTERIA_RESTIC_REPOSITORY (required for restic driver) Example: s3:s3.us-west-004.backblazeb2.com/atlas-backups
SOTERIA_RESTIC_SECRET_NAME (default: soteria-restic)
SOTERIA_SECRET_NAMESPACE (default: service namespace)
SOTERIA_RESTIC_IMAGE (default: restic/restic:0.16.4)
SOTERIA_RESTIC_BACKUP_ARGS (optional) Extra args for restic backup
SOTERIA_RESTIC_FORGET_ARGS (optional) Extra args for restic forget (include --prune if desired)
SOTERIA_S3_ENDPOINT (optional) Example: s3.us-west-004.backblazeb2.com
SOTERIA_S3_REGION (optional) Example: us-west-004
SOTERIA_JOB_TTL_SECONDS (default: 86400)
SOTERIA_JOB_NODE_SELECTOR (optional) Comma-separated node selector, e.g. kubernetes.io/arch=arm64,node-role.kubernetes.io/worker=true
SOTERIA_JOB_SERVICE_ACCOUNT (optional) ServiceAccount for backup Jobs
SOTERIA_LISTEN_ADDR (default: :8080)

The restic repository is encrypted with RESTIC_PASSWORD from the secret below.

Secrets

Create a secret named soteria-restic in the Soteria namespace (or set SOTERIA_RESTIC_SECRET_NAME) if using the restic driver. Keys required:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
RESTIC_PASSWORD

The service copies this secret into the target namespace per job and attaches an owner reference so it gets cleaned up with the Job.

A template is in deploy/secret-example.yaml (do not commit real credentials).

Deployment

The deploy/ folder includes Kustomize-ready manifests:

namespace.yaml
configmap.yaml (set your repository and endpoint)
serviceaccount.yaml
clusterrole.yaml
clusterrolebinding.yaml
deployment.yaml
service.yaml

Apply with:

kubectl apply -k deploy

Notes

Backups mount the PVC read-only at /data and run restic backup /data.
Restore tests write into /restore (either an emptyDir or a target PVC).
For Backblaze B2, use the S3 endpoint and region for your bucket (example: s3.us-west-004.backblazeb2.com).