Restore API7 Gateway

Goal

Restore an API7 Gateway deployment from either a database-native dump or a declarative ADC export, and prove that it serves traffic before returning it to production.

The database dump is the authoritative recovery source. Use it whenever a valid dump exists. The declarative ADC export is the fallback when no database backup is available; it restores gateway configuration only and does not restore users, roles, API products, audit data, or other control-plane state.

Before you begin

• You have a backup set produced by Back Up API7 Gateway: a database dump directory, a gateway-group inventory JSON file, and one ADC export per gateway group.
• You have a source-version API7 Gateway image and deployment artifacts ready.
• You know whether you will restore from the database dump or from the ADC export.

Set the variables this guide uses:

export API7_ADMIN_URL="https://localhost:7443"
export GATEWAY_URL="http://127.0.0.1:9080"
export API7_DB_USER="api7ee"             # the database role the control plane connects as
export API7_DB_NAME="api7ee"             # the original database the control plane uses
export API7_DB_RESTORED="api7ee_restored"   # the empty database the dump is restored into
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
export API7_GATEWAY_GROUP_ID="default"   # only the group the quickstart creates; otherwise copy the gateway group's UUID from Gateway Groups in the Dashboard
export SMOKE_PATH="/get"                 # a path one of your own routes serves
read -rsp "Dashboard token: " API7_ADMIN_KEY && export API7_ADMIN_KEY && echo
read -rsp "Database password: " API7_DB_PASSWORD && export API7_DB_PASSWORD && echo

API7_DB_PASSWORD is read here because the connection string refers to it rather than carrying a password. The control-plane process needs it in its environment, not only in yours — how it gets there is your deployment's secret mechanism, a Kubernetes Secret or the Compose file's env_file.

• 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.

• 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.

Steps

Step 1: Restore from the database dump

Use this path whenever a valid database backup exists. Provision a new database and keep every control-plane component stopped until the restore and its checks are complete: a control plane that connects to a half-restored database is harder to reason about than one that has not started.

1.1 Create an empty target database

createdb -U "${API7_DB_USER}" "${API7_DB_RESTORED}"

1.2 Restore the dump into the new database

pg_restore -U "${API7_DB_USER}" -d "${API7_DB_RESTORED}" "${API7_BACKUP_DIR}/"

Expected: both commands exit without an error. Check the restored source version, the schema, and a few representative resources before any control-plane component connects to it.

1.3 Point the control plane at the restored database

Update API7 Dashboard, the DP Manager, and every other control-plane database client to the restored database. Both services read the same key in their own configuration file, and API7 configuration files resolve ${VAR} from the process environment — see Environment Variables:

database:
  dsn: "postgres://api7ee:${API7_DB_PASSWORD}@192.168.31.10:5432/api7ee_restored"

Start one Dashboard replica on the source-version image and check it before starting the remaining replicas and the DP Managers. The ports each service listens on are in Ports and Endpoints.

1.4 Restore the data planes

Bring the data planes back on the source-version image, from the deployment scripts, values, certificates, and configuration files you saved in the backup inventory. Install fresh mTLS material issued by the restored control plane rather than reusing certificates from the old CA — see Mutual TLS between Control Plane and Data Plane.

Keep them out of production traffic until the Validate check below passes on at least one instance.

Step 2: Restore from the ADC export

Use this path only when no valid database backup is available. Declarative restoration restores gateway configuration only.

2.1 Start the source-version control plane with an empty database

Start the source-version control plane with its original configuration and image tags, pointed at a new, empty database.

2.2 Recreate the gateway-group records from the inventory

Use the source-version Admin API. ADC does not create gateway groups — see Manage Gateway Groups.

• Update the automatically created default group with its saved name, description, and labels. On 3.10.5–3.10.7, also restore its saved environment, which those versions accept on update.
• Recreate every required non-default group with its saved common fields, plus enforce_service_publishing on 3.8.23, 3.9.19–3.9.20, or 3.10.0–3.10.2; no additional field on 3.10.3–3.10.4; environment on 3.10.5–3.10.7.
• Send no field the source version does not accept. type and enforce_service_publishing are create-only, so if either saved value for the default group differs from the fresh control plane's value, stop rather than sync: the Admin API cannot make the two groups equivalent.

2.3 Restore connection material for each group

• For api7_gateway, restore the source-version data-plane deployment configuration, replace its CP-DP connection settings, and install fresh mTLS certificates from the restored control plane.

• For api7_ingress_controller, restore the controller's deployment configuration, then read the key the recreated group generated:

  curl -ks "${API7_ADMIN_URL}/api/gateway_groups/${API7_GATEWAY_GROUP_ID}/admin_key" \
    -H "X-API-KEY: ${API7_ADMIN_KEY}"

  A PUT to the same path rotates it instead. Replace the old key in the Secret or values the controller consumes, and store the plaintext key as a secret.

Keep the data planes and controllers stopped, or isolated from production traffic, until the sync below is complete.

2.4 Check that ADC reaches the restored control plane

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

2.5 Sync each exported file to its gateway group

Check the group's name before every command, because ADC's --gateway-group is a name lookup:

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

2.6 Reconnect data planes and controllers

Confirm that each one reaches the intended gateway group with its replacement credential, and run the Validate check before returning them to production.

Validate

A restore is not complete until it serves traffic. Run the restore in an isolated environment, then send a request through a restored data plane to a route the deployment served before:

curl -is "${GATEWAY_URL}${SMOKE_PATH}" | sed -n '1p'

HTTP/1.1 200 OK

Repeat the restore test whenever the source version changes, and never let a production change depend on a backup that has not had one.

Roll back / Clean up

A database restore wrote to a new database and left the original in place, so going back is one configuration change and a restart: point database.dsn at ${API7_DB_NAME} again, start one Dashboard replica, check it, then bring the rest of the control plane and the data planes back. The deployment serves no traffic through a restarting data plane, so roll instances one at a time.

Once the rollback deadline for the change has passed, remove the restored database:

dropdb -U "${API7_DB_USER}" "${API7_DB_RESTORED}"

Keep the backup set in an access-controlled backup system for as long as your retention policy says.

Troubleshoot

Related

• Back Up API7 Gateway — how to create the backup set this guide consumes.
• Plan an API7 Gateway Upgrade — the change this restore is almost always performed 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.
• Ports and Endpoints — the ports the restored control plane and data planes listen on.