Back Up API7 Gateway

Goal

Create a recoverable backup set for an API7 Gateway deployment: a database-native dump of the control-plane data and a declarative ADC export per gateway group, plus the inventory neither file carries.

The database dump is the authoritative recovery source. It holds control-plane state that ADC does not export, including users, roles, API products, and audit data. The ADC export is the fallback for a recovery where no valid database backup is available, and it restores gateway configuration only.

Before you begin

• You have a token from the Dashboard with access to every gateway group you are backing up, and the list of those groups in front of you. ADC's --gateway-group is a name lookup and some versions select the first matching search result, so a pair of similar names is a reason to stop rather than to guess.

Set the variables this guide uses:

export API7_ADMIN_URL="https://localhost:7443"
export API7_DB_USER="api7ee"             # the database role the control plane connects as
export API7_DB_NAME="api7ee"             # the database the control plane uses
export API7_BACKUP_DIR="api7ee-backup-$(date +%Y%m%d)"
export API7_GATEWAY_GROUP="default"      # the gateway group's *name*, which is what ADC looks up
read -rsp "Dashboard token: " API7_ADMIN_KEY && export API7_ADMIN_KEY && echo
read -rsp "Database password: " API7_DB_PASSWORD && export API7_DB_PASSWORD && echo

• The control plane is reachable and your token is valid. Check it with:

  curl -ks -o /dev/null -w '%{http_code}\n' "${API7_ADMIN_URL}/api/gateway_groups" \
    -H "X-API-KEY: ${API7_ADMIN_KEY}"

  Expected: 200.

• PostgreSQL client tools are installed on the host that will take the dump. Check it with:

  pg_dump --version

  Expected: a pg_dump (PostgreSQL) … version line. API7 Gateway stores configuration in PostgreSQL by default; the supported engines and versions are in Supported Versions and Interoperability.

• ADC is installed and can reach the control plane. Check it with:

  adc ping --backend api7ee --server "${API7_ADMIN_URL}"

  Expected: ADC reports that it connected. Installation is in the ADC documentation.

Steps

Step 1: Dump the database

Take the database-native backup first; it is the source of truth for everything else. This example writes a directory-format dump, which suits a large database and can be restored in parallel:

pg_dump -U "${API7_DB_USER}" -d "${API7_DB_NAME}" -F d -f "${API7_BACKUP_DIR}"

• -U "${API7_DB_USER}": connects as the control plane's database role.
• -d "${API7_DB_NAME}": names the database to back up.
• -F d: directory format.
• -f "${API7_BACKUP_DIR}": the output directory the dump is written into.

Step 2: Record the recovery inventory for every gateway group

ADC does not export the gateway-group record itself, the data-plane deployment configuration, the CP-DP connection material, or an Ingress Controller's gateway-group admin key. Save them yourself, from the source-version Admin API:

curl -ks "${API7_ADMIN_URL}/api/gateway_groups" -H "X-API-KEY: ${API7_ADMIN_KEY}" \
  > "${API7_BACKUP_DIR}-gateway-groups.json"

Expected: a JSON document with one entry per gateway group, each carrying at least the create-time fields below.

Which fields matter depends on the version the backup came from, because a gateway-group field one version accepts is rejected by another:

Save the source-version connection and deployment inputs for each group as well, according to its type:

• For api7_gateway, save the data-plane deployment configuration, the CP-DP connection settings, and the Secret or file locations where replacement mTLS material must be installed.
• For api7_ingress_controller, save the Ingress Controller deployment configuration and the Secret or values location that supplies its gateway-group admin key. The old key does not authenticate to a group recreated in a fresh database.

Store each inventory beside the ADC export it belongs to.

Step 3: Export each gateway group with ADC

Run adc dump once per gateway group, always with --gateway-group and always to a distinct file. Without the flag ADC operates on the default group, and one output filename reused overwrites the previous export:

adc dump -o "${API7_BACKUP_DIR}-${API7_GATEWAY_GROUP}.yaml" \
  --backend api7ee \
  --server "${API7_ADMIN_URL}" \
  --gateway-group "${API7_GATEWAY_GROUP}"

Expected: the file exists and contains the group's services, routes, plugins, and consumers. Repeat the command for every gateway group, exporting API7_GATEWAY_GROUP again each time. Further ADC commands are in the ADC documentation.

Validate

Confirm that the backup set is complete and readable:

test -d "${API7_BACKUP_DIR}" && echo "Database dump directory exists"
test -s "${API7_BACKUP_DIR}-gateway-groups.json" && echo "Gateway-group inventory exists"
test -s "${API7_BACKUP_DIR}-${API7_GATEWAY_GROUP}.yaml" && echo "ADC export exists"

Expected: all three checks print a confirmation line.

A backup is not a backup until a restore of it serves traffic. Test the restore in an isolated environment before depending on it in production; see Restore API7 Gateway.

Roll back / Clean up

A backup itself changes nothing in the deployment, so there is no runtime rollback. Keep the backup set in an access-controlled backup system for as long as your retention policy says. Three more sets of files belong there and are not in any of the backups, because they are specific to the deployment rather than to its data:

1. The config.yaml file, or the deployment values, used by each gateway instance.
2. The source code of custom plugins.
3. The deployment scripts and any other files used when the instances were deployed.

Check during a rollback rehearsal that an operator can actually retrieve all three.

After the retention period, you can remove the local copies:

rm -rf "${API7_BACKUP_DIR}"
rm -f "${API7_BACKUP_DIR}-gateway-groups.json"
rm -f "${API7_BACKUP_DIR}-${API7_GATEWAY_GROUP}.yaml"

Troubleshoot

Related

• Restore API7 Gateway — how to recover from the database dump or the ADC export.
• Plan an API7 Gateway Upgrade — the change this backup is almost always taken for.
• API Gateway Cluster Migration — the same dump and restore used to move a deployment rather than to recover one.
• API Declarative CLI (ADC) — what a declarative export contains, and why it is a fallback rather than a backup.
• Manage Gateway Groups — creating the gateway-group records a declarative restore needs first.