Backup and Restore

What This Page Covers

What you back up, and who is responsible for it, depends on which AISIX deployment you run.

In Hybrid Cloud, API7 hosts and operates the AISIX Cloud control-plane database. There is no database backup procedure for you to run here — contact API7 support about retention and recovery for your organization.

In On-Premises, you own the control-plane database — the bundled Docker Compose Postgres instance, the Helm chart's own bundled PostgreSQL sub-chart, or an external Postgres reached through Helm — and the database backup and restore procedures below are written for that database.

AISIX OSS, the standalone open-source gateway, keeps no control-plane database at all: it is mostly stateless, and what you back up is the resources.yaml file you deploy it with, or an export of the etcd keyspace it reads from. See Back Up Non-Database Objects.

Everything after the database sections — configuration, provider secrets, TLS certificates, and audit exports — applies regardless of which control-plane deployment produced those objects, so read past the database sections even if Hybrid Cloud made the database ones not applicable to you.

Back Up the Control-Plane Database (On-Premises)

cp-api owns the schema migration, and it is the service every backup and restore step below is timed around. Upgrade AISIX requires exactly this backup before every control-plane upgrade — the commands here are the same ones, kept current in one place and cross-linked from there.

Bundled Docker Compose Postgres

The online and offline packages run PostgreSQL as the postgres service, with POSTGRES_USER and POSTGRES_DB set in .env (see On-Premises Configuration). Dump the database from inside the container so the command picks up those values without exporting secrets into your shell:

cd aisix-self-hosted
docker compose exec -T postgres sh -c \
  'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -F c' \
  > aisix-backup-$(date +%Y%m%d%H%M%S).dump

-F c produces pg_dump's custom format, which pg_restore can replay selectively or in parallel. Copy the resulting .dump file off the host — it is not covered by run.sh's own backup of anything, and it is your only path back once a later version has migrated the schema.

Bundled PostgreSQL (Helm)

With postgresql.builtin: true (the Helm chart's default — see PostgreSQL), the control plane runs its own bundled PostgreSQL sub-chart instead of the Docker Compose service or an external database. That sub-chart uses different environment variable names than the Compose package (POSTGRES_DATABASE rather than POSTGRES_DB), and its non-superuser application role does not own every schema in the database, so pg_dump against that role fails on the internal auth schema:

kubectl exec -n "${AISIX_NAMESPACE}" aisix-cp-postgresql-0 -- sh -c \
  'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DATABASE" -F c' \
  > aisix-backup-$(date +%Y%m%d%H%M%S).dump
# pg_dump: error: query failed: ERROR:  permission denied for schema auth

Dump as the postgres superuser role instead, using the POSTGRES_POSTGRES_PASSWORD credential the sub-chart also exposes — this is the same role the control plane itself connects as by default (postgresql.auth.usePostgresUserForAppConnections: true):

kubectl exec -n "${AISIX_NAMESPACE}" aisix-cp-postgresql-0 -- sh -c \
  'PGPASSWORD="$POSTGRES_POSTGRES_PASSWORD" pg_dump -U postgres -d "$POSTGRES_DATABASE" -F c' \
  > aisix-backup-$(date +%Y%m%d%H%M%S).dump

External Postgres (Helm)

When the control plane points at an external database you provisioned yourself (postgresql.builtin: false), back it up with your DBA team's standard tooling, run against the role and database from that guide's role setup.

pg_dump works fine as that role: the CREATE ROLE statement in step 1 grants it neither SUPERUSER nor REPLICATION, but it owns the database and every object in it — and ownership is all a logical dump needs.

Physical backup is different. pg_basebackup, and any point-in-time recovery setup built on streaming replication, needs the REPLICATION privilege, which that role deliberately does not have. The same connection the control plane uses cannot take one. A DBA running physical backups needs a separate, appropriately-privileged connection — not the AISIX application role.

Point-in-Time Recovery

This page covers pg_dump-based snapshots only. Recovering to an arbitrary point between snapshots is your DBA team's own standard PITR tooling, run against their own privileged connection rather than the role AISIX connects as. AISIX does not ship or document a point-in-time recovery mechanism of its own.

Restore the Database

Both paths follow the same shape: stop the control plane, replace the database, start it again against the restored data. A control-plane rollback is a database restore for the same reason — see Roll Back.

Bundled Docker Compose Postgres

cd aisix-self-hosted
./run.sh stop
docker compose down -v          # drops the bundled Postgres volume; this destroys the current database
docker compose up -d postgres   # recreates an empty volume and starts only the database
# wait until `docker compose ps postgres` reports healthy, then:
docker compose exec -T postgres sh -c \
  'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists' \
  < aisix-backup-TIMESTAMP.dump
./run.sh                        # bring the rest of the stack back up against the restored database

Bundled PostgreSQL (Helm)

Restore as the same postgres superuser role you dumped with — the non-superuser application role cannot restore objects in schemas it does not own, the same restriction that blocks it from pg_dump:

kubectl exec -i -n "${AISIX_NAMESPACE}" aisix-cp-postgresql-0 -- sh -c \
  'PGPASSWORD="$POSTGRES_POSTGRES_PASSWORD" pg_restore -U postgres -d "$POSTGRES_DATABASE" --clean --if-exists' \
  < aisix-backup-TIMESTAMP.dump
kubectl -n "${AISIX_NAMESPACE}" rollout restart deployment \
  -l app.kubernetes.io/instance="${AISIX_CP_RELEASE}",app.kubernetes.io/component=api

External Postgres (Helm)

Restore through your DBA team's standard pg_restore (or physical-recovery) process, against the same role and database, then point cp-api back at it and wait for it to come up:

kubectl -n "${AISIX_NAMESPACE}" rollout status deployment \
  -l app.kubernetes.io/instance="${AISIX_CP_RELEASE}",app.kubernetes.io/component=api

cp-api's migration runs against whatever schema version the restored dump carries, and applies any pending migrations on top of it if the dump predates the control-plane version you're running.

Back Up Non-Database Objects

Configuration

• AISIX OSS: the resources.yaml file is the source of truth — back up the file itself, wherever you keep it under version control. For a gateway configured through etcd instead, export its keyspace with aisix export:

  aisix export --etcd "http://127.0.0.1:2379" -o resources-backup.yaml

• AISIX Enterprise: control-plane resources — models, provider keys, caller API keys, budgets — live in the database backed up above. For a portable, human-reviewable copy outside of a database dump, export the same resources through the AISIX Enterprise Admin API.

Provider Keys and Secrets

See Secrets management for where provider keys, caller API keys, and control-plane tokens live and how to rotate them. Back them up the way you back up any other secret in your secrets manager — AISIX Enterprise stores provider keys encrypted and write-only, so the control-plane database backup above does not give you a way to read them back out in plaintext.

TLS Certificates

See TLS and mTLS for the four independent certificate surfaces — listener, upstream trust, etcd, and the AISIX Enterprise control-plane connection. Back up certificates and keys the way you back up any other credential: a Kubernetes Secret, or your external certificate manager's own backup path.

Audit Log Exports

See Logging and Auditing for the audit-log export. A CSV or JSON export returns at most 50,000 entries per request, newest first; when the filtered range matches more than that, narrow the time range or filters and export the remainder in a second pass.

Restore Non-Database Objects

Backup Cadence

• Daily: export configuration (OSS resources.yaml or etcd export; Enterprise Admin API export) and audit logs.
• On demand: before upgrades — this is the same backup Upgrade AISIX requires before every control-plane upgrade — before credential rotations, and before major configuration changes.
• Before deletion: always back up a database, an environment's full configuration, or a gateway group before removing it. A deleted organization, environment, or resource is not recoverable from within AISIX itself.

Validate a Backup

A backup you have not restored is unverified. Periodically restore your latest dump into a scratch environment — a disposable Compose stack or a separate namespace — and confirm two things: cp-api starts cleanly against it, and its migration completes without error. A dump that restores but fails migration is not a usable backup, and finding that out during a drill costs far less than finding it out during an incident.

Next Steps

• Disaster Recovery for the broader recovery scenarios this backup feeds into.
• Upgrade AISIX for the pre-upgrade backup step and the rollback procedure that consumes it.
• External Database for provisioning and role setup when the control plane points at your own Postgres.
• Organization Data Export and Import for exporting or migrating one organization on its own, without a database-level restore — available on Hybrid Cloud as well as On-Premises.