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 LTS releases, use Choose an LTS Upgrade Path; otherwise, confirm the combination in the release notes or an API7 Support plan.
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 every gateway group. 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. An orchestrator-managed rolling update is acceptable only when its surge and unavailable-capacity settings preserve this ordering.
5. Add a target node to the production release 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 until the rollback deadline passes. Resume Dashboard, Admin API, ADC, and automation writes only after the named decision owner records final acceptance.