Backup and Restoration

Before every upgrade, create both a database-native backup and a declarative export of each gateway group with ADC. The database backup is the authoritative recovery source because it includes CP state that ADC does not export, such as users, roles, API products, and audit data.

Restore-test the database backup in an isolated environment before the production change. Keep the backup and ADC exports until the rollback deadline passes.

Create Backups

Create the database-native backup first, then export every gateway group's declarative configuration.

Create a Database-Native Backup

API7 Gateway uses PostgreSQL by default. The following example creates a directory-format backup with pg_dump:

pg_dump -U api7ee -d api7ee -F d -f api7ee_backup_20250523

• pg_dump: PostgreSQL's logical backup tool for exporting database contents.
• -U api7ee: Specifies the database connection username as api7ee.
• -d api7ee: Specifies the database name to back up as api7ee.
• -F d: Specifies the backup format as directory format, which is suitable for large databases and parallel restoration.
• -f api7ee_backup_20250523: Specifies the output directory name for the backup as api7ee_backup_20250523. The backup results will be stored in this directory.

Export Declarative Configuration

Use the ADC tool to back up your API7 Gateway configurations (services, routes, plugins, consumers, etc.) in the form of declarative configuration files.

1. Before exporting resources, save a recovery inventory for every gateway group. Record the fields returned by the source-version Admin API, including the following create-time fields:

   Source CP version	Common fields	Additional field
   3.8.23, 3.9.19, or 3.10.0–3.10.2	name, description, type, and labels	enforce_service_publishing
   3.10.3–3.10.4	name, description, type, and labels	None
   3.10.5–3.10.6	name, description, type, and labels	environment

   Also save the source-version connection and deployment inputs for each group according to its type:

   • For api7_gateway, save the DP deployment configuration, 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 will not authenticate to a group recreated in a fresh database.

   Store each inventory with the corresponding ADC export. ADC does not include the gateway-group record, either deployment configuration, CP-DP connection material, or the Ingress Controller admin key in the dump. Do not assume that a gateway-group field from one CP version is accepted by another version's API.

2. Verify that ADC can connect to API7 Gateway:

   adc ping --backend api7ee --server "https://{DASHBOARD_ADDR}"

3. Before each dump, list the gateway groups in the Dashboard or API and verify that the requested name identifies exactly the intended group. ADC uses --gateway-group as a name lookup, and some versions can select the first matching search result. Do not proceed when similar names make the result ambiguous.

4. Use ADC dump to store each gateway group's data in a distinct local file. Repeat this command for every gateway group. Always specify --gateway-group; otherwise ADC operates on the default group, and reusing one output filename can overwrite a previous export:

   adc dump -o "api7ee-{GATEWAY_GROUP}-dump.yaml" \
     --backend api7ee \
     --server "https://{DASHBOARD_ADDR}" \
     --gateway-group "{GATEWAY_GROUP}"

For more ADC commands, see the ADC documentation.

Data Restoration and Rollback

Restore from the database backup whenever possible. Use declarative restoration only when complete database recovery is unavailable.

Restore from Database

To restore API7 Gateway data from a database backup, provision a new database and keep every CP component stopped until the restore and validation are complete. The following PostgreSQL example restores the directory-format backup created above.

1. Create an empty target database that is not reachable by the running CP:

   createdb -U api7ee api7ee_restored

2. Restore the backup into the empty target database:

   pg_restore -U api7ee -d api7ee_restored api7ee_backup_20250523/

3. Verify the restored source version, schema, and representative resources before allowing any CP component to connect.

4. Update the Dashboard, DP Manager, and every other CP database client to use the restored database:

   database:
     dsn: "postgres://api7ee:changeme@192.168.31.10:5432/api7ee_restored"

5. Start one Dashboard replica with the source-version image and validate it before restoring the remaining CP replicas and DP Managers.

6. Use the saved deployment scripts, values, certificates, and configuration files to restore the source-version DPs. Verify representative traffic before returning them to production.

Restore from Declarative Configuration

Restore the source-version CP with the original configuration and image tags, and connect it to the new database. ADC exports do not include gateway-group records, DP deployment configuration, or CP-DP mTLS connection material. Complete these prerequisites before using ADC to restore the exported gateway configuration:

1. Using the saved recovery inventory and the source-version Admin API, restore the gateway-group records before syncing:

   • Update the existing default gateway group with its saved name, description, and labels. For 3.10.5–3.10.6, also restore its saved environment, which those versions accept on update.
   • Recreate every required non-default gateway group with its saved common fields. Also send enforce_service_publishing for 3.8.23, 3.9.19, or 3.10.0–3.10.2; send no additional field for 3.10.3–3.10.4; or send environment for 3.10.5–3.10.6.
   • Do not send fields that the source version does not accept. type and enforce_service_publishing are create-only. If either saved value for the automatically created default group differs from the fresh CP value, stop instead of syncing because the Admin API cannot make the groups equivalent.

   ADC does not create gateway-group records. See Manage Gateway Groups.

2. Restore connection material according to each saved gateway-group type:

   • For api7_gateway, restore the source-version DP deployment configuration, replace its CP-DP connection settings, and install fresh mTLS certificates generated by the restored CP instead of reusing certificates issued by the old CA.
   • For api7_ingress_controller, restore the source-version Ingress Controller deployment configuration. Retrieve the new key generated with the recreated group using GET /api/gateway_groups/{gateway_group_id}/admin_key, or rotate it using PUT on the same endpoint, then replace the old key in the Secret or values consumed by the controller. Store the plaintext key as a secret.

   Keep the DPs and Ingress Controllers stopped or isolated from production traffic until the ADC restoration and validation are complete.

3. Use ADC to verify service connectivity and confirm that it can connect to API7 Gateway:

   adc ping --backend api7ee --server "https://{DASHBOARD_ADDR}"

4. Before each sync, list the gateway groups in the Dashboard or API and verify that the requested name identifies exactly the intended group. Do not proceed when similar names make the result ambiguous. Then sync each exported file to its matching gateway group. Repeat this command for every gateway group. Always specify --gateway-group; otherwise ADC operates on the default group:

   adc sync -f "api7ee-{GATEWAY_GROUP}-dump.yaml" \
     --backend api7ee \
     --server "https://{DASHBOARD_ADDR}" \
     --gateway-group "{GATEWAY_GROUP}"

5. Start or reconnect the restored source-version DPs and Ingress Controllers. Confirm that every DP or controller reaches the intended gateway group with its replacement credential, and validate representative traffic before returning them to production.

Other Files

In addition to the resource configurations you created in API7 Gateway, there are some important files that need to be backed up manually:

1. The config.yaml file or deployment values used for each gateway instance.
2. Source code of custom plugins.
3. Deployment scripts and other files used when deploying API7 Gateway instances.

These files are specific to the deployment and may be required for recovery. Store them in an access-controlled backup system and verify that operators can retrieve them during a rollback rehearsal.