Dual-Cluster Upgrade

A dual-cluster upgrade builds a target cluster alongside the source production cluster. Each cluster has its own Control Plane (CP), Data Plane (DP), and database. An external load balancer shifts traffic only after the target cluster passes isolated validation.

This strategy can preserve request continuity, but it does not synchronize management writes between the source and target databases. Freeze rollback-relevant writes before the final source backup. Keep them frozen until the rollback deadline passes, or resume them only under a tested reconciliation plan.

Prepare for Two Clusters

1. Confirm that the exact source-to-target path permits dual-cluster. Follow the pair-specific guide or obtain a topology-specific upgrade plan from API7 Support.
2. Reserve enough compute, network, and database capacity to run two production-capable clusters through the observation and rollback window.
3. Save the source manifests, values, certificates, images, external dependency configuration, and database backup.
4. Restore-test the source backup and verify representative CP resources before using it to create the target database.
5. Prepare load-balancer health checks, traffic stages, connection draining, monitoring, acceptance criteria, abort thresholds, rollback owner, and rollback deadline.
6. Define which writes are blocked, which synthetic validation writes are allowed, and how every permitted write will be removed, retained, or reconciled.

Upgrade with Two Clusters

The upgrade moves through a write freeze, isolated target validation, staged traffic shifting, and final acceptance or rollback.

Freeze Rollback-Relevant Writes

Announce the management maintenance window and block operator-, customer-, automation-, and integration-initiated writes through the CP, Dashboard, Admin API, Developer Portal, scheduled jobs, and direct database access.

Target migrations and disposable operational state, such as sessions and DP heartbeats, can remain target-only and be discarded during rollback. Preserve target audit records according to the retention policy and incident response plan. Record every permitted synthetic validation write and its cleanup or reconciliation action.

Keep the freeze in effect through the final source backup and target database restore. After the target CP is validated, writes can resume before the rollback deadline only under a tested reconciliation process. The process must record every rollback-relevant write and support reconciling the source database before traffic returns to the source cluster. Resuming unreconciled writes ends the traffic-only rollback window.

Build and Validate the Target Cluster

1. Provision an independent target database with production-appropriate capacity, availability, security, and backup settings.
2. Create a database-native backup of the frozen source database and restore it into the target database. Verify the restored source version and representative resources.
3. Deploy the target CP with the exact artifacts and database migration sequence required by the version path. Update every enabled CP image, including api7/api7-ee-3-integrated, api7/api7-ee-dp-manager, and any enabled Developer Portal backend, API usage, or file-server component. Do not run source and target CP versions against the same database unless the exact version path explicitly permits it.
4. Validate the target CP before starting target DPs. Check migration logs, resources, IAM, license state, integrations, and compatibility reports.
5. Deploy target DPs with the exact target api7/api7-ee-3-gateway image and verify each reports Healthy and Compatible with no errors.
6. Test representative public and authenticated traffic, custom plugins, upstreams, logging, metrics, caching, rate limiting, and external dependencies while the target cluster remains outside production traffic.

Shift Initial Traffic

Send a small, plan-defined portion of production traffic to the target DPs. Keep enough traffic and capacity on the source cluster for rollback.

Compare response codes, latency, logs, upstream health, plugin behavior, and resource utilization between clusters through the defined observation period. Stop the shift when an abort threshold is reached.

Increase Traffic Gradually

Increase target traffic only after the previous stage passes. Use the percentages and observation periods defined and rehearsed for the production deployment rather than treating example values as defaults.

At every stage:

• Confirm both clusters have sufficient capacity.
• Compare target behavior with the source baseline.
• Verify stateful dependencies and rate-limit behavior.
• Keep rollback-relevant writes frozen or reconciled.
• Record the decision to continue, hold, or roll back.

Complete the Traffic Move

Move all production traffic to the target DPs only after every acceptance criterion passes. Keep the source cluster available through the rollback deadline, but do not assume traffic can return safely after databases diverge.

Continue observing the target cluster and complete any planned cleanup or reconciliation for synthetic validation state.

Roll Back

Redirect traffic to the source DPs only when the source cluster remains healthy and rollback-relevant writes stayed frozen or the tested reconciliation procedure completed. Traffic redirection does not reverse target database writes.

If a traffic-only rollback is unsafe, keep the clusters isolated as required by the incident plan and restore the appropriate database backup before returning source components to service. Preserve the target database and logs for investigation.

Decommission the Source Cluster

Decommission the source CP, DPs, and database only after:

• the target observation period and rollback deadline pass;
• acceptance is recorded;
• monitoring and alerting are confirmed;
• required reconciliation is complete; and
• retained backups have been restore-tested.

Operational Considerations

Capacity, stateful dependencies, and request-continuity behavior determine whether traffic can shift and return safely.

Capacity

Both clusters and the external load balancer must handle their assigned traffic at every stage, including a return to the source cluster. Reserve capacity for health checks, connection draining, and target validation in addition to normal request load.

Stateful Plugins

Runtime metrics and stateful plugin data are not synchronized automatically. Rate-limit counters can be local to a DP or stored in Redis, and target releases can use new keys or serialization formats.

Use a shared Redis deployment only after testing every stateful plugin for cross-version compatibility. Otherwise, accept and quantify the temporary state differences created while traffic is split.

Request Continuity

Dual-cluster is designed to preserve request continuity, not guarantee zero downtime. Continuity depends on cluster capacity, load-balancer behavior, connection draining, upstream health, stateful dependencies, and successful validation.