Migrate API7 Gateway to a New Cluster

A cluster migration moves an API7 Gateway deployment to new infrastructure without changing the Control Plane (CP) or Data Plane (DP) version. It applies to moving between datacenters or cloud providers, or to refreshing infrastructure, without combining that work with a product upgrade. The source cluster remains available while an independent target cluster is built from a restored database backup and validated; an external load balancer then shifts traffic in controlled stages.

Request continuity depends on the capacity and health of both clusters, the load balancer, connection draining, upstream behavior, and stateful dependencies. It is not guaranteed by the two-cluster topology alone. 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 the Migration

Preparation establishes the target environment, rollback boundary, and acceptance criteria before production state or traffic moves.

1. Confirm that the source and target CPs and DPs use the same released product version.
2. Provision independent target compute, network, storage, and database capacity. Both clusters and the external load balancer must handle their assigned traffic throughout the migration and rollback window.
3. Save the source manifests, values, image tags, certificates, external dependency configuration, and deployment automation.
4. Create a database-native backup and restore it into an isolated database. Verify representative CP resources before the production migration. See Backup and Restoration.
5. Define the traffic stages, observation period, acceptance criteria, abort thresholds, rollback owner, rollback deadline, and source-cluster retention period.
6. Rehearse the migration and rollback with production-like configuration, representative public and authenticated traffic, and the production load-balancer behavior.

Freeze Rollback-Relevant Writes

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

Before the freeze begins, define and rehearse how any write that resumes later will be applied to both clusters or reconciled before traffic can return to the source cluster. Record every permitted 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

The target cluster stays outside production traffic until its data, components, and request behavior pass validation.

1. Stop or isolate every target CP component that could access the target database.

2. Take the final source database backup and restore it into the independent target database. Verify the restored schema and representative resources before starting the target CP.

3. Start the target CP with the same product version as the source cluster. Confirm the Dashboard, Admin API, DP Manager, license, IAM policies, gateway groups, and integrations are healthy.

4. In the target Dashboard, open Gateway Settings and set DP Manager Address to the target DP Manager endpoint that the target DPs can reach.

5. For each gateway group, open Gateway Instances, select Add Gateway Instance, and generate a target deployment script. Use the target-generated connection values and mTLS material:

   • For Helm or Kubernetes, confirm the generated values set etcd.host[...] to the target DP Manager endpoints and use the generated TLS Secret.
   • For Docker Compose, confirm API7_DP_MANAGER_ENDPOINTS, API7_DP_MANAGER_CERT, API7_DP_MANAGER_KEY, and API7_CONTROL_PLANE_CA come from the target deployment script.

6. Start the target DPs outside the production load balancer, then validate the target and copied instance records separately:

   • Confirm each newly created target DP record reports Healthy and Compatible with no errors.
   • The restored database also contains copied source DP records. Their status initially reflects the age of the copied last heartbeat. Because those DPs do not heartbeat to the target CP, records that are not already Offline become LostConnection and then Offline as that timestamp ages. Remove copied records only after they report Offline.
   • Configure and test the readiness and liveness probes used by the target deployment and load balancer.

7. Send representative public and authenticated traffic directly to the target DPs. Verify plugins, upstreams, logs, metrics, caching, rate limiting, health checks, and external dependencies.

Shift Production Traffic

Start with a small, plan-defined portion of production traffic. A typical sequence is 5–10%, 25%, 50%, and 100% target traffic, but use percentages and observation periods validated for the production load balancer and capacity. Keep enough source capacity available for rollback.

At every stage:

• compare response codes, latency, logs, upstream health, resource use, and plugin behavior with the source baseline;
• confirm both clusters have sufficient capacity;
• verify connection draining and load-balancer health behavior;
• check stateful dependencies and rate-limit behavior; and
• stop the shift when an abort threshold is reached.

Increase target traffic only after the previous stage passes. Move all production traffic to the target DPs only after every acceptance criterion is satisfied.

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 copy target database changes back to the source database.

If a traffic-only rollback is unsafe, keep the clusters isolated and follow the incident plan. Preserve the target database and logs for investigation.

Complete the Migration

Continue monitoring the target cluster through the defined observation period. Keep rollback-relevant writes frozen through the traffic-only rollback deadline. If writes must resume earlier, keep the tested reconciliation process active for every new write, and return traffic to the source cluster only after those writes are reconciled. Resuming unreconciled writes ends the traffic-only rollback window.

Record final acceptance and decommission the source CP, DPs, and database only after the rollback deadline passes, monitoring and alerting are confirmed, and retained backups have been restore-tested.

Operational Considerations

The following dependencies require explicit validation because the database restore and traffic shift do not synchronize their runtime state automatically.

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. Use a shared Redis deployment only after testing every stateful plugin for compatibility with both clusters; otherwise, quantify and accept the temporary state differences while traffic is split.

Ingress Controller

API7 Ingress Controller can update routes and upstream endpoints after the final backup. Plan how the target cluster receives those updates, and verify its routes and upstreams against current Kubernetes resources before shifting traffic. See Ingress Controller Resource Updates.

Target Connection Material

DP configuration must point to the target CP and use connection material issued for that target. Before adding a target DP to the load balancer, check its CP endpoint, gateway group, certificates, and connection logs.