Skip to main content
API7.ai Logo
Version: 3.10.x

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.

caution

Use database restoration whenever a valid backup is available. ADC restores gateway configuration only and is not a replacement for complete CP recovery.

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 ADC-supported gateway configuration, including services, routes, plugins, and consumers, in 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 versionCommon fieldsAdditional field
    3.8.23, 3.9.19–3.9.21, or 3.10.0–3.10.2name, description, type, and labelsenforce_service_publishing
    3.10.3–3.10.4name, description, type, and labelsNone
    3.10.5–3.10.7name, description, type, and labelsenvironment

    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. ADC 0.30.4 also does not export consumer groups, so database backup is required to recover them. Do not assume that a gateway-group field from one CP version is accepted by another version's API.

  2. Create a Dashboard token that can list gateway groups and read their configurations, then provide it to ADC:

    export ADC_TOKEN="{DASHBOARD_TOKEN}"

  3. Verify that ADC can connect to API7 Gateway:

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

  4. Before each dump, list the gateway groups in the Dashboard or API and verify the exact name of the intended group. Pass that name to --gateway-group.

  5. Use ADC dump with --with-id to store each gateway group's data in a distinct local file. Preserving backend-assigned resource IDs retains resource identity and avoids name-derived replacements when restoring into a nonempty group. Repeat this command for every gateway group. Always specify --gateway-group; if neither this option nor ADC_GATEWAY_GROUP is set, ADC requests the group named default. 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}" \
      --with-id

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​

caution

Use declarative configuration restoration only when complete database recovery is unavailable. It does not restore users, roles, API products, audit data, or other CP state.

ADC 0.30.4 does not restore consumer groups. If gateway authorization depends on consumer groups, use database restoration instead of declarative restoration.

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.8.23, 3.9.19–3.9.21, or 3.10.0–3.10.2, also restore its saved enforce_service_publishing value. For 3.10.5–3.10.7, restore its saved environment.
    • Recreate every required non-default gateway group with its saved common fields. Also send enforce_service_publishing for 3.8.23, 3.9.19–3.9.21, 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.7.
    • Do not send fields that the source version does not accept. type is create-only. If its 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. Create a Dashboard token in the restored CP that can list gateway groups and read, create, update, and delete all ADC-supported resource types being restored. Provide it to ADC and verify connectivity:

    export ADC_TOKEN="{DASHBOARD_TOKEN}"
    adc ping --backend api7ee --server "https://{DASHBOARD_ADDR}"

  4. Before restoring each file, list the gateway groups in the Dashboard or API and verify the exact name of the intended group. The exported file is authoritative for ADC-supported resources in that group, so synchronization can delete remote resources that are missing from the file. Preview the changes against the matching gateway group:

    adc diff -f "api7ee-{GATEWAY_GROUP}-dump.yaml" \
      --backend api7ee \
      --server "https://{DASHBOARD_ADDR}" \
      --gateway-group "{GATEWAY_GROUP}" \
      --no-managed-by-label

    Review the generated diff.yaml file and stop if it contains unexpected deletions or replacements. --no-managed-by-label prevents ADC from adding its ownership label during recovery, preserving the labels stored in the export.

  5. After reviewing the diff, sync the exported file to the matching gateway group. Repeat the preview and sync for every gateway group. Always specify --gateway-group; if neither this option nor ADC_GATEWAY_GROUP is set, ADC requests the group named default:

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

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