Plan an API7 Gateway Upgrade

Plan an API7 Gateway upgrade by confirming the supported version path, selecting deployment strategies, preparing backups, and rehearsing rollback.

An API7 Gateway upgrade starts with a supported source-to-target version path. That path defines the exact artifacts, compatibility changes, migration rules, and rollback contract. The deployment strategies on this page explain how to carry out the Control Plane (CP) and Data Plane (DP) changes after the path is confirmed.

For an LTS-to-LTS upgrade, begin with Choose an LTS Upgrade Path. For a patch or adjacent minor-version upgrade, confirm the exact combination in the release notes or an API7 Support plan.

Prepare the Upgrade

Preparation establishes the source state, target manifests, acceptance criteria, and recoverable rollback point before production changes begin.

Confirm the exact source and target versions and the applicable path-specific guide or release notes.
Inventory the production topology, database engine, CP and DP replicas, gateway groups, plugins, identity providers, upstreams, automation, and external stateful dependencies.
Review every operator-impacting change between the source and target releases.
Build new target manifests from the target package defaults. Pin explicit image and chart versions and reapply reviewed production settings.
Define the change owner, observation period, acceptance criteria, abort thresholds, rollback owner, and rollback deadline.
Rehearse the complete upgrade and rollback with a restored production-like database, representative configuration, and public and authenticated traffic.

Back Up and Restore-Test Data

Create a database-native backup before every upgrade and restore it into an isolated database. Verify the restored source version and representative CP resources before treating the backup as authoritative.

Also export each gateway group's declarative configuration with ADC. ADC is a secondary configuration check: it does not include users, roles, API products, audit data, or every other CP resource, so it does not replace the database backup.

Keep the immutable source backup, source manifests, certificates, charts, and images until the rollback deadline passes. A backup taken after the CP migration is a target-version snapshot and cannot replace the source backup required for a full rollback.

Choose the Control Plane Strategy

The CP is upgraded before the DPs. Choose the strategy supported by the exact version path and production topology.

Strategy	When it fits	Production impact	Rollback basis
In-place CP upgrade	Reuse the current database and avoid provisioning a second complete cluster.	Dashboard and Admin API are unavailable while source CP processes are stopped and the target CP starts. Existing DPs can continue proxying when the version path permits the mixed-version window.	Stop the target CP and restore the immutable source backup into a new database before restoring source binaries.
Dual-cluster upgrade	Run independent source and target clusters and shift traffic gradually.	Requires two production-capable clusters, independent databases, an external load balancer, and a write freeze or tested reconciliation plan.	Traffic can return to the source cluster only while rollback-relevant writes stayed frozen or were reconciled.

Upgrade the Data Plane

After an in-place CP upgrade, use a Data Plane rolling upgrade to replace source nodes once the target CP is healthy and the mixed-version compatibility gate passes. Add and validate target capacity before draining source nodes. Each target node must report Healthy and Compatible, pass direct representative traffic, and enter the production load balancer before a source node is removed. For dual-cluster, follow the target-DP and traffic-shifting sequence in the pair-specific guide.

The in-place sequence is:

Upgrade Considerations

These requirements apply across strategies unless a path-specific guide imposes a stricter rule:

Keep management writes frozen from the final source backup until acceptance or rollback is complete.
Never run source and target CP versions against the same database.
Treat mixed CP and DP versions as a temporary state allowed only by the exact version path.
Test custom plugins, NGINX snippets, authentication, logging, metrics, caching, rate limiting, upstream health checks, and automation against the target release.
Preserve sufficient source capacity and artifacts to execute the documented rollback before the deadline.
Do not rely on helm rollback or --atomic to reverse a database migration.

Confirm Acceptance and Rollback

Before ending the write freeze, verify the target versions, CP resources, DP compatibility reports, public and authenticated traffic, logs, metrics, database health, and every path-specific acceptance criterion.

If an abort threshold is reached, keep writes frozen and execute the predefined rollback. Resume writes only after the named decision owner records acceptance or confirms that rollback and any required reconciliation are complete.

Continue with the Applicable Guide

LTS-to-LTS: choose the exact LTS upgrade path and follow its pair-specific procedure.
Patch or adjacent minor version with in-place CP: confirm the exact supported combination, follow Control Plane In-Place Upgrade, then complete Data Plane Rolling Upgrade.
Patch or adjacent minor version with two clusters: confirm the exact supported combination, then follow Dual-Cluster Upgrade for target deployment and traffic shifting.
Backup and recovery details: Backup and Restoration.