t.behrendt/backupsidecar
1
0
Fork 0
Code Issues 4 Pull Requests 3 Actions Packages Activity
Files
main
backupsidecar/README.md
Timo Behrendt 73ce57b122
All checks were successful
CD / Check changes (push) Successful in 14s
Details
CD / Create tag (push) Successful in 11s
Details
CD / Build and push (amd64) (push) Successful in 26s
Details
CD / Build and push (arm64) (push) Successful in 1m14s
Details
CI / Build Docker image (pull_request) Successful in 18s
Details
CD / Create manifest (push) Successful in 25s
Details
feat: add restore functionality (#12) 
Reviewed-on: #12
Co-authored-by: Timo Behrendt <t.behrendt@t00n.de>
Co-committed-by: Timo Behrendt <t.behrendt@t00n.de>
2025-09-04 20:36:40 +02:00

242 lines
8.4 KiB
Markdown
Raw Permalink Blame History

# BackupSidecar
BackupSidecar is a lightweight backup and restore solution designed to run as a cron job in Kubernetes. It automates backups and restores using Restic and supports both directory and PostgreSQL database operations. Optional notifications can be sent via Gotify to keep you informed of operation results.
## Configuration
BackupSidecar is configured through environment variables. Below is a breakdown of the available settings.
### General Settings
These variables apply to both backup and restore operations.
- **`OPERATION_MODE`** _(optional)_ - Defines the operation type (`backup` or `restore`). Defaults to `backup`.
- **`BACKUP_MODE`** _(optional)_ - Defines the backup type (`directory` or `postgres`). Defaults to `directory`.
- **`RESTIC_PASSWORD`** _(required)_ - The encryption password for Restic.
- **`RESTIC_REPOSITORY`** _(required)_ - The URI of the Restic repository (e.g., `rest:http://your-rest-server:8000/backup`).
- **`RESTIC_REST_USERNAME`** _(optional)_ - The username for REST server authentication.
- **`RESTIC_REST_PASSWORD`** _(optional)_ - The password for REST server authentication.
- **`ENABLE_GOTIFY`** _(optional)_ - Enable Gotify notifications. Set to `true` to enable, any other value or unset disables notifications. Defaults to `true`.
- **`GOTIFYHOST`** _(required when ENABLE_GOTIFY=true)_ - The Gotify server URL.
- **`GOTIFYTOKEN`** _(required when ENABLE_GOTIFY=true)_ - The API token for Gotify.
- **`GOTIFYTOPIC`** _(required when ENABLE_GOTIFY=true)_ - The topic under which backup notifications will be sent.
### Directory Operations
When running in `directory` mode, the following variables must be set:
**For Backup Operations:**
- **`SOURCEDIR`** _(required)_ - The path of the directory to be backed up.
**For Restore Operations:**
- **`RESTOREDIR`** _(required)_ - The path where files should be restored to.
- **`RESTORE_SNAPSHOT_ID`** _(optional)_ - The specific snapshot ID to restore (defaults to `latest`).
### PostgreSQL Operations
For `postgres` mode, the following database-related variables are required:
**Common Variables:**
- **`PGHOST`** _(required)_ - The hostname of the PostgreSQL server.
- **`PGDATABASE`** _(required)_ - The name of the database.
- **`PGUSER`** _(required)_ - The PostgreSQL username.
- **`PGPORT`** _(optional)_ - The port for PostgreSQL (defaults to `5432`).
- **`PGPASSWORD`** _(optional)_ - The password for authentication. Setting this prevents interactive prompts.
**Backup-Specific Variables:**
- **`PG_DUMP_ARGS`** _(optional)_ - Additional flags for `pg_dump`.
**Restore-Specific Variables:**
- **`RESTORE_SNAPSHOT_ID`** _(optional)_ - The specific snapshot ID to restore (defaults to `latest`).
- **`PSQL_ARGS`** _(optional)_ - Additional flags for `psql` (e.g., `--single-transaction`).
## Dependencies
Ensure the following commands are available in the container:
- `restic`
- `curl`
- `jq`
- `pg_dump` _(only required for PostgreSQL backup operations)_
- `psql` _(only required for PostgreSQL restore operations)_
## Usage
### Backup Operations
Example Kubernetes CronJob manifest for running BackupSidecar as a cron job for directory backups in minimal configuration:
```yaml
apiVersion: batch/v1
kind: CronJob
metadata:
name: backupsidecar-cron
namespace: authentik
spec:
schedule: "0 7 * * *"
concurrencyPolicy: Forbid
successfulJobsHistoryLimit: 5
failedJobsHistoryLimit: 3
jobTemplate:
spec:
backoffLimit: 3
activeDeadlineSeconds: 300
template:
spec:
restartPolicy: OnFailure
containers:
- name: backupsidecar
image: backupsidecar:latest
env:
- name: RESTIC_REPOSITORY
value: "rest:http://rest-server:8000/backup"
- name: RESTIC_PASSWORD
valueFrom:
secretKeyRef:
name: backupsidecar-secret
key: restic_password
- name: BACKUP_MODE
value: "directory" # or "postgres"
- name: SOURCEDIR
value: "/data/source"
- name: ENABLE_GOTIFY
value: "true"
- name: GOTIFYHOST
value: "http://gotify.example.com"
- name: GOTIFYTOKEN
valueFrom:
secretKeyRef:
name: backupsidecar-secret
key: gotify_token
- name: GOTIFYTOPIC
value: "Backup Notification"
# (For PostgreSQL mode, add PGHOST, PGDATABASE, PGUSER, PGPORT, PGPASSWORD)
volumeMounts:
- name: source-data
mountPath: /data/source
restartPolicy: OnFailure
volumes:
- name: source-data
persistentVolumeClaim:
claimName: source-data-pvc
```
### Restore Operations
Example Kubernetes Job manifest for running BackupSidecar to restore a directory:
```yaml
apiVersion: batch/v1
kind: Job
metadata:
name: backupsidecar-restore
namespace: authentik
spec:
backoffLimit: 3
activeDeadlineSeconds: 600
template:
spec:
restartPolicy: OnFailure
containers:
- name: backupsidecar
image: backupsidecar:latest
env:
- name: OPERATION_MODE
value: "restore"
- name: BACKUP_MODE
value: "directory"
- name: RESTOREDIR
value: "/data/restore"
- name: RESTORE_SNAPSHOT_ID
value: "abc123def456" # optional, defaults to latest
- name: RESTIC_REPOSITORY
value: "rest:http://rest-server:8000/backup"
- name: RESTIC_PASSWORD
valueFrom:
secretKeyRef:
name: backupsidecar-secret
key: restic_password
- name: GOTIFYHOST
value: "http://gotify.example.com"
- name: GOTIFYTOKEN
valueFrom:
secretKeyRef:
name: backupsidecar-secret
key: gotify_token
- name: GOTIFYTOPIC
value: "Restore Notification"
volumeMounts:
- name: restore-data
mountPath: /data/restore
volumes:
- name: restore-data
persistentVolumeClaim:
claimName: restore-data-pvc
```
Example Kubernetes Job manifest for running BackupSidecar to restore a PostgreSQL database:
```yaml
apiVersion: batch/v1
kind: Job
metadata:
name: backupsidecar-postgres-restore
namespace: authentik
spec:
backoffLimit: 3
activeDeadlineSeconds: 600
template:
spec:
restartPolicy: OnFailure
containers:
- name: backupsidecar
image: backupsidecar:latest
env:
- name: OPERATION_MODE
value: "restore"
- name: BACKUP_MODE
value: "postgres"
- name: PGHOST
value: "postgres.example.com"
- name: PGDATABASE
value: "mydatabase"
- name: PGUSER
value: "myuser"
- name: PGPASSWORD
valueFrom:
secretKeyRef:
name: postgres-secret
key: password
- name: PGPORT
value: "5432"
- name: RESTORE_SNAPSHOT_ID
value: "abc123def456" # optional, defaults to latest
- name: PSQL_ARGS
value: "--single-transaction" # optional
- name: RESTIC_REPOSITORY
value: "rest:http://rest-server:8000/backup"
- name: RESTIC_PASSWORD
valueFrom:
secretKeyRef:
name: backupsidecar-secret
key: restic_password
- name: GOTIFYHOST
value: "http://gotify.example.com"
- name: GOTIFYTOKEN
valueFrom:
secretKeyRef:
name: backupsidecar-secret
key: gotify_token
- name: GOTIFYTOPIC
value: "Database Restore Notification"
```
## Notifications
The script can send success or failure notifications via Gotify when enabled. To enable notifications, set `ENABLE_GOTIFY=true` and provide the required Gotify configuration variables (`GOTIFYHOST`, `GOTIFYTOKEN`, `GOTIFYTOPIC`). When notifications are disabled, backup status messages are still logged to the console.
Reference in New Issue View Git Blame Copy Permalink