Backup & Restore

All KubeWatch persistent data lives in a single PostgreSQL database (with TimescaleDB). Backing up the database is sufficient to protect all organizations, users, agents, metrics history, alert rules, and alert history.

Manual database backup

cd /opt/kubewatch
docker compose exec postgres pg_dump \
  -U kubewatch \
  --format=custom \
  --compress=9 \
  kubewatch > backup-$(date +%Y%m%d-%H%M%S).dump

The --format=custom flag creates a compressed, custom-format dump that is faster and more flexible to restore than plain SQL.

Scheduled backups with cron

Add a cron job to back up the database daily:

crontab -e

Add this line:

0 2 * * * cd /opt/kubewatch && docker compose exec -T postgres pg_dump -U kubewatch --format=custom --compress=9 kubewatch > /opt/kubewatch/backups/backup-$(date +\%Y\%m\%d).dump

This runs at 2:00 AM every day. Make sure the /opt/kubewatch/backups/ directory exists:

mkdir -p /opt/kubewatch/backups

VM snapshots

Before any upgrade, take a full VM snapshot from your cloud provider's console (AWS EC2 AMI, GCP snapshot, Azure managed disk snapshot, etc.). A snapshot captures everything, the database, config, and images, and can be restored to the exact pre-upgrade state in minutes.

Restoring from a backup

cd /opt/kubewatch

# 1. Stop the application services (keep postgres running)
docker compose stop gateway auth ingestion query live-data clusters cloud integrations dashboard

# 2. Drop and recreate the database
docker compose exec postgres psql -U postgres -c "DROP DATABASE IF EXISTS kubewatch;"
docker compose exec postgres psql -U postgres -c "CREATE DATABASE kubewatch OWNER kubewatch;"

# 3. Restore the dump
docker compose exec -T postgres pg_restore \
  -U kubewatch \
  -d kubewatch \
  --format=custom \
  < backup-20260615-020000.dump

# 4. Start all services
docker compose up -d

What is backed up

Backup retention recommendation

• Keep daily backups for 7 days
• Keep weekly backups for 4 weeks
• Keep monthly backups for 12 months

Automate rotation with a script that deletes backups older than your retention window, or use your cloud provider's object storage lifecycle policies (e.g., S3, GCS, Azure Blob).