# Backup and Restoration Before every upgrade, create both a database-native backup and a declarative export of each gateway group with [ADC](https://docs.api7.ai/api7-gateway/reference/adc.md). 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 every backup artifact until the rollback deadline passes. caution Database-native backups contain credentials and CA private keys in a form the Control Plane can decrypt. Encrypt backups at rest and in transit with operator-controlled keys, strictly limit and audit access, and retain them only as long as required. 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[​](#database-backup "Direct link to Create Backups") Create the database-native backup first, export every gateway group's declarative configuration, and save the deployment files required to restore the CP and DPs. ### Create a Database-Native Backup[​](#database-native-backup "Direct link to 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[​](#declarative-file-backup "Direct link to Export Declarative Configuration") Use the [ADC tool](https://docs.api7.ai/api7-gateway/reference/adc.md) 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 version | Common fields | Additional field | | ---------------------------------------------- | ------------------------------------------- | ---------------------------- | | 3.8.23–3.8.24, 3.9.19–3.9.23, 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.10 | `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. [Create a Dashboard token](https://docs.api7.ai/api7-gateway/reference/obtain-dashboard-token.md) 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](https://github.com/api7/adc/blob/main/docs/README.md). ### Back Up Deployment Files[​](#back-up-deployment-files "Direct link to Back Up Deployment Files") Save the following deployment-specific files with the database backup and ADC exports. File names depend on the deployment method and patch version: 1. The CP deployment files, component image tags, database configuration, and references to required credentials: * **Bundled control-plane Docker Compose stack:** Save the Compose file and environment variables, `dashboard_conf/conf.yaml`, `dp_manager_conf/conf.yaml`, and `developer_portal_conf/conf.yaml`. For enabled optional components, also save `api_usage_conf/conf.yaml` or `api7-ee-file-server-config.yaml`, as applicable. Starting in version 3.10.5, also save `developer_portal_fe_conf/config.yaml` when the Developer Portal frontend profile is enabled. * **Standalone Developer Portal Docker Compose:** Save the Portal API `backend_conf/conf.yaml` and frontend `frontend_conf/config.yaml`, plus the Portal token and authentication keys. The backend must use the existing control-plane database, while the frontend has a separate authentication and session database; keep recoverable backups of both databases. * **RPM, version 3.10.1:** Follow the instructions and systemd units shipped with the bundle. Save every referenced configuration and environment file, certificate, private key, and connection parameter instead of assuming the layout used by later patch releases. * **RPM, versions 3.10.2 through 3.10.6:** Save `/usr/local/api7/dashboard/conf/dashboard.yaml`, `/usr/local/api7/dp-manager/conf/dp-manager.yaml`, and the standalone Console configuration `/usr/local/api7/dashboard/conf/console.env`. * **RPM, version 3.10.7 or later:** Save `/usr/local/api7/dashboard/conf/dashboard.yaml` and `/usr/local/api7/dp-manager/conf/dp-manager.yaml`. The Console is embedded in the Dashboard binary, so these versions do not install `console.env` or a separate `api7ee-console` service. * **Kubernetes / OpenShift with Helm:** Save each CP release's values, command-line overrides, rendered manifests, and referenced ConfigMaps and Secrets. Preserve recovery material from any external secret manager separately. 2. The `config.yaml` file or deployment values used for each gateway instance, together with referenced certificates, private keys, and connection parameters. 3. Source code of custom plugins. 4. Deployment scripts and other files used to deploy API7 Gateway instances. Store these files in an access-controlled backup system and verify that operators can retrieve them during a rollback rehearsal. ## Data Restoration and Rollback[​](#data-restoration-and-rollback "Direct link to Data Restoration and Rollback") Restore from the database backup whenever possible. Use declarative restoration only when complete database recovery is unavailable. ### Restore from Database[​](#restore-from-database "Direct link to 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. Set the PostgreSQL administrative role used for recovery. This role needs `CREATEDB`, permission to assign `api7ee` as the database owner, and authority to grant privileges on the target database's `public` schema: ``` export POSTGRES_ADMIN_USER="YOUR_POSTGRES_ADMIN_USER" ``` 2. Use that role to create an empty target database that is not reachable by the running CP, assign the application role as owner, and grant it access to the `public` schema: ``` createdb -U "${POSTGRES_ADMIN_USER}" \ --owner=api7ee \ api7ee_restored psql -U "${POSTGRES_ADMIN_USER}" \ -d api7ee_restored \ -c 'GRANT ALL ON SCHEMA public TO api7ee;' ``` 3. Restore the backup as the application role. Stop at the first error so a partial restore is not mistaken for a successful recovery: ``` pg_restore --exit-on-error \ -U api7ee \ -d api7ee_restored \ api7ee_backup_20250523/ ``` 4. Verify the restored source version, schema, and representative resources before allowing any CP component to connect. 5. 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" ``` 6. Start one Dashboard replica with the source-version image and validate it before restoring the remaining CP replicas and DP Managers. 7. 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-from-declarative-configuration "Direct link to 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. 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](https://docs.api7.ai/api7-gateway/reference/adc.md) 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.8.24, 3.9.19–3.9.23, or 3.10.0–3.10.2, also restore its saved `enforce_service_publishing` value. For 3.10.5–3.10.10, 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.8.24, 3.9.19–3.9.23, 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.10. * 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](https://docs.api7.ai/api7-gateway/how-to-guides/ops/multi-gateway-group.md). 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.