Data Plane Rolling Upgrade

A rolling upgrade replaces Data Plane (DP) nodes after the target Control Plane (CP) is healthy. Target nodes are added and validated before source nodes are drained, allowing API requests to continue when capacity, health checks, load balancing, connection draining, and rollback are correctly configured.

Prepare for the Rollout

1. Confirm the exact source and target versions. For an LTS upgrade from this version, follow Upgrade from 3.9 LTS to 3.10 LTS; otherwise, confirm the combination in the release notes or with API7 Support.
2. Complete and validate the target CP upgrade. Confirm every source DP is allowed to connect temporarily and does not report Incompatible or an unexpected compatibility error.
3. Record the desired and ready replica counts for each gateway group's DP deployment. Reserve enough capacity to add target nodes before draining source nodes.
4. Validate load-balancer health checks, connection draining, readiness probes, traffic monitoring, and the rollback path.
5. Save the source DP values, manifests, certificates, image tags, and immutable pre-upgrade database backup.
6. Generate target DP configuration and certificates from the target CP. Build new values for the installation method (Docker or Kubernetes) from the target package defaults, and pin the exact api7/api7-ee-3-gateway image.

Roll Out the Target Data Planes

1. Keep the management write freeze in effect. Do not introduce target-only configuration while source DPs remain unless the path-specific procedure explicitly coordinates that change.

2. Deploy one target DP as a separate canary outside the production load balancer.

3. Wait for the canary to report Healthy and Compatible with no compatibility errors. Send representative public and authenticated traffic directly to it and verify plugins, upstreams, logs, metrics, and health checks.

4. Configure the production rollout for add-before-drain replacement:

   • For Helm or Kubernetes, update the reviewed gateway chart and image values. Configure the rollout so surge capacity starts and becomes ready before a source pod can become unavailable.
   • For container-hosted DPs, start a separate target container from the reviewed target configuration. Do not restart or remove the corresponding source container until the target container passes validation and enters the load balancer.

5. Add a target node to the production fleet and wait until it is ready, registered, and passing traffic checks.

6. Add the target node to the load balancer and observe response codes, latency, logs, upstream health, and plugin-specific metrics.

7. Drain and stop one source node only after the target replacement passes validation.

8. Repeat the add, validate, and drain sequence until every node in the gateway group is upgraded, then continue with the remaining gateway groups.

9. If target nodes cannot safely serve traffic, remove them from the load balancer and return traffic to retained source nodes. Follow the path-specific rollback before using source DPs when target-only configuration has been written.

Complete the Rollout

Confirm every production DP reports Healthy and Compatible with no errors. Run the path-specific traffic and observation checks, remove the canary, and restore the production autoscaling policy only after the main rollout is accepted.

Keep source artifacts and the immutable backup according to the retention plan. Resume Dashboard, Admin API, ADC, and automation writes only after the rollout passes its acceptance criteria. Resuming unreconciled writes ends the backup-based rollback window because restoring the pre-upgrade backup would discard every later write. If the rollback plan must remain available through a later deadline, keep writes frozen or keep the tested reconciliation process active until that deadline passes.