Plan an API7 Gateway Upgrade

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.

1. Confirm the exact source and target versions and the applicable path-specific guide or release notes.
2. Inventory the production topology, database engine, CP and DP replicas, gateway groups, plugins, identity providers, upstreams, automation, and external stateful dependencies. For Kubernetes deployments, account for Ingress Controller resource updates.
3. Review every operator-impacting change between the source and target releases.
4. Build new target manifests from the target package defaults. Pin explicit image and chart versions and reapply reviewed production settings.
5. Define the change owner, observation period, acceptance criteria, abort thresholds, rollback owner, and rollback deadline.
6. 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.

Ingress Controller Resource Updates

caution

This warning applies only if you use API7 Ingress Controller to manage gateway resources.

The controller can update these resources even when no one changes configuration in the Dashboard or Admin API. Account for these automatic updates when preparing backups, migrating to another cluster, or rolling back an upgrade.

API7 Ingress Controller watches Kubernetes resources and synchronizes gateway configuration through the CP. Application rollouts, autoscaling, Pod restarts, and rescheduling can change backend endpoints and trigger upstream updates without anyone editing a route.

If the supported upgrade procedure keeps the CP available for configuration writes, Ingress Controller can continue synchronizing resources. Follow the write restrictions in the selected upgrade procedure: CP high availability does not remove restrictions required for database migration.

For PostgreSQL, pg_dump creates a consistent snapshot even while updates continue. Updates after that snapshot are not included in the backup. ADC exports taken separately can represent a different point in time. Restoring a successful backup therefore does not guarantee that routes and upstreams match the current Kubernetes state.

For deployments managed by Ingress Controller:

1. Identify controller-managed resources and other configuration writers, including ADC jobs and GitOps workflows. Record when the database backup and ADC exports were taken, and preserve the Kubernetes resource definitions alongside the immutable source backup.
2. For a dual-cluster upgrade, updates to the source cluster after the backup are not automatically included in the target cluster. Plan and test how to synchronize subsequent changes. Confirm the controller targets the intended CP and validate the target routes and upstreams against current Kubernetes resources before shifting traffic.
3. For restoration or rollback, the backup can contain obsolete backend addresses. Rehearse how to synchronize controller-managed resources after the CP accepts writes again. Check controller logs, verify gateway upstreams against current Kubernetes endpoints, and test affected routes before declaring recovery complete. Reconcile changes from other configuration writers separately.

If the CP becomes unavailable or rejects configuration writes, endpoint updates cannot reach the gateway. Existing DP nodes continue using their last received configuration, which can cause requests to fail if the configured Pod IP addresses are no longer available. Account for backend endpoint changes during any planned CP write interruption.

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.