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

Backup and Restoration

Before starting any upgrade, please back up your database data first.

You can use the following two methods to back up your database data used in API7 Gateway.

  1. Use the native tools provided by the database to back up data. This allows you to quickly import the backed-up data into a new database for immediate recovery.
  2. Use the ADC tool to back up ADC-supported gateway configuration, including services, routes, plugins, and consumers, in declarative configuration files.

It is recommended to use both methods simultaneously, as this provides greater flexibility when restoring data in case of the following issues.

danger

If data is corrupted, please try database-level restoration first, otherwise use a new database and update your previous configurations using the stored declarative configuration files.

Database Backup​

Database-Native Backup​

API7 Gateway uses PostgreSQL database by default. Using PostgreSQL's native commands, you can use the pg_dump command to back up data in plain text, directory, and other formats. For example, the command to back up in directory format:

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.

Declarative File Backup​

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 its name, description, type, labels, and enforce_service_publishing values. Also save the 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 gateway-group records, deployment configuration, CP-DP connection material, or Ingress Controller admin keys in the dump. ADC 0.30.4 also does not export consumer groups, so database backup is required to recover them.

  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:

    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 Database​

To restore API7 Gateway data from database backup, you need to prepare a new database first, using PostgreSQL as an example.

  1. Modify the database connection address to the new database in the CP (Dashboard and DP-Manager) configuration file:

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

    Restart the CP.

  2. Restore the previously backed-up data:

    pg_restore -U api7ee -C -d api7ee api7ee_backup_20250523/
    • -U: Specifies the database connection username. This user needs sufficient permissions to create and restore the database.
    • -C: Create the target database first, then connect to the database for restoration.
    • -d: Specifies the target database name.

  3. Use the previously stored local deployment scripts or configuration files for Gateway Instance to redeploy the nodes in the DP.

Restore from Declarative Configuration​

danger

If you encounter issues and need to roll back, please try database restoration first. Only use declarative configuration restoration as a last resort if your data is corrupted.

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

First, restore your deployed API7 Gateway (CP & DP) to the original version's configuration and image tag, and connect it to your newly prepared database. Then, use the ADC tool to restore your previous configurations.

  1. Using the saved recovery inventory, restore the gateway-group records before syncing:

    • Update the existing default gateway group with its saved name, description, labels, and enforce_service_publishing values.
    • Recreate every required non-default gateway group with its saved name, description, type, labels, and enforce_service_publishing values.
    • Do not send type when updating the default group because it is create-only. If the saved value 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. 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 each exported file against its 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 conf.yaml file created for Gateway Instance.
  2. Source code of custom plugins.
  3. Deployment scripts and other files used when deploying API7 Gateway instances.

These files are tied to your business and deployment environment. The absence of these files could impact data restoration in case of issues.

It is recommended to store these files on the platform where you deploy API7 Gateway for centralized management.