# soteria

Soteria is a small in-cluster service that launches restic Jobs to back up PVCs. It is intended to be called by Ariadne (or another controller) and focuses on:

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

Snapshots are not implemented yet; backups are crash-consistent for the PVC as mounted.

## API

### POST /v1/backup

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

Response:

```json
{
  "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

```json
{
  "namespace": "ai",
  "snapshot": "latest",
  "target_pvc": "restore-sandbox",
  "dry_run": false
}
```

## Configuration

Environment variables:

- `SOTERIA_RESTIC_REPOSITORY` (required) 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_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`). 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:

```sh
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`).