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:

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:

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:

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.