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 business writes between databases. Keep rollback-relevant state frozen or use a tested reconciliation plan until the rollback deadline passes.

Prepare for Two Clusters

1. Confirm that the exact source-to-target path permits dual-cluster and obtain any required API7 Support plan.
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, audit records, and DP heartbeats, can remain target-only and be discarded during rollback. Record every permitted synthetic validation write and its cleanup or reconciliation action.

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. Never run source and target CP versions against the same database.
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.