Migrate Ingress from nginx to Envoy Gateway

Overview

The migration has five stages. nginx keeps serving traffic until you move DNS. Envoy Gateway is installed next to nginx first, so you can send it real traffic before any customer-facing change.

AWS (EKS) only. The migration is available on AWS clusters today. Azure and GCP support is on the roadmap.

Prerequisites

• An AWS EKS cluster on SeaGit in the Started state. Clusters on other providers, or clusters that are stopped, refuse each step.
• A cluster that runs the nginx ingress controller. Prepare fails when there is no nginx release to copy routes from.
• Room for two more pods. Envoy Gateway runs two replicas. On a full node group the new pods stay Pending, so add capacity first.
• Permission to update the cluster. The panel and the API both check it.
• Ingress annotations that Envoy can serve. Any blocker stops Move DNS to Envoy. See Ingress blockers.
• For the API only: an API key (sgt_…) or a Firebase ID token, plus your organization ID, cluster ID and account ID.

Migrate in the console

Open the cluster and find the ingress migration panel. The stage tracker at the top shows where the cluster is: NGINX, Envoy ready, Shifting traffic, DNS on Envoy, or Envoy only. The button for the next step is highlighted. Long-running steps show a progress banner with the step name and elapsed time, and the banner updates automatically, so you do not need to reload the page.

Step 1. Prepare Envoy

Click Prepare Envoy. SeaGit installs Envoy Gateway and its own load balancer, then converts every nginx Ingress into Gateway API HTTPRoute objects, so Envoy has the same hosts and paths. No traffic moves, so customers still reach nginx. The badge changes to NGINX · Envoy ready.

Undo: Abort migration removes Envoy and its routes, and nginx keeps everything. Re-run prepare is safe to repeat, for example after you add node capacity.

Step 2. Shift traffic to Envoy (canary)

This step is a canary deployment for your ingress. Under Send to Envoy, pick a share: 10%, 25%, 50% or 100%. nginx forwards that share of requests to Envoy through an nginx canary Ingress and serves the rest itself, while DNS stays where it is. Because the split happens inside the cluster, Envoy is tested with real requests and lowering the share does not wait on DNS caches. Wait, check your apps and error rates, then move to the next share. The badge reads Envoy 25% → 50% while a change is running and Envoy 25% when it is done.

Undo: the 0% button sends all traffic back to nginx. Abort migration is also available here.

Step 3. Send all traffic to Envoy

Choose 100%. Envoy now serves every request through nginx. This is the state where Move DNS to Envoy becomes available, and only when no blockers are listed.

Undo: lower the share with the 0% button, or use Abort migration.

Step 4. Choose the soak period

Next to Move DNS to Envoy is a Keep NGINX for list: 15 minutes, 1 hour (the default), 6 hours or 24 hours. This is how long nginx stays up after DNS moves. Pick a longer period when you want more time to watch Envoy under real traffic.

Step 5. Move DNS to Envoy

Click Move DNS to Envoy and confirm. Your hostnames now point at Envoy's load balancer. The step runs in the background and updates automatically. When it finishes, the stage reads DNS on Envoy and the countdown for the soak period starts.

Undo: Move DNS back to NGINX (confirm the dialog) points hostnames at nginx again. Envoy keeps running at 100%. Abort migration is no longer offered once DNS has moved.

Step 6. Finish and remove NGINX

When the soak period ends, Finish and remove NGINX becomes available. Finish first checks that every nginx Ingress can be converted, that Envoy serves the routes, and that DNS points at Envoy. Only then does it uninstall nginx and delete its load balancer. Confirm the dialog to start it.

Undo: none. Finish is the point of no return.

Step 7. Check your apps

After finish, confirm that your apps load through Envoy and that their TLS certificates are valid. The screenshots below show an app served through Envoy and the certificate for its host.

Check the migration status

The badge next to the cluster's ingress shows the state in one line:

Below the stage tracker, the panel lists blockers, the load balancer addresses, and the result of the last step. A failed step shows its error in a red banner.

The same information comes from the API. Send a GET request and read these fields:

• phase: none → prepared → shifting → soak → done
• weight: share of traffic on Envoy (0, 10, 25, 50 or 100)
• envoy_address and nginx_address: the load balancer addresses
• soak_until: when Finish becomes available
• pending: the queued step, with action and ts, or null when nothing is running
• allowed_actions: the actions the cluster accepts now
• blockers[]: each with namespace, ingress, annotation and reason
• last_action and last_action_error: the last step and why it was refused (empty when it succeeded)
• routes_settled and pending_sources: whether any route is still kept in step by the migration (see deploying apps)

Automate with the API

Each console step has an API action with the same effect. Every request goes to the same URL, and only the body changes. Replace the placeholders with your values:

• $ORG_ID: your organization ID
• $CLUSTER_ID: your cluster ID
• $ACCOUNT_ID: your account ID
• $API_KEY: your API key (sgt_…)

The request URL is https://seagit.com/api/org/$ORG_ID/clusters/$CLUSTER_ID/ingress-migration?accid=$ACCOUNT_ID. A POST returns 202 Accepted with the view, and the step runs in the background. Poll the GET request to see when it finishes.

curl -H "Authorization: $API_KEY" \
  "https://seagit.com/api/org/$ORG_ID/clusters/$CLUSTER_ID/ingress-migration?accid=$ACCOUNT_ID"

curl -X POST -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"prepare"}' \
  "https://seagit.com/api/org/$ORG_ID/clusters/$CLUSTER_ID/ingress-migration?accid=$ACCOUNT_ID"

curl -X POST -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"set_weight","weight":25}' \
  "https://seagit.com/api/org/$ORG_ID/clusters/$CLUSTER_ID/ingress-migration?accid=$ACCOUNT_ID"

curl -X POST -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"cutover","soak_seconds":86400}' \
  "https://seagit.com/api/org/$ORG_ID/clusters/$CLUSTER_ID/ingress-migration?accid=$ACCOUNT_ID"

curl -X POST -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"revert_dns"}' \
  "https://seagit.com/api/org/$ORG_ID/clusters/$CLUSTER_ID/ingress-migration?accid=$ACCOUNT_ID"

curl -X POST -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"finish"}' \
  "https://seagit.com/api/org/$ORG_ID/clusters/$CLUSTER_ID/ingress-migration?accid=$ACCOUNT_ID"

curl -X POST -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"abort"}' \
  "https://seagit.com/api/org/$ORG_ID/clusters/$CLUSTER_ID/ingress-migration?accid=$ACCOUNT_ID"

curl -X POST -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"sync"}' \
  "https://seagit.com/api/org/$ORG_ID/clusters/$CLUSTER_ID/ingress-migration?accid=$ACCOUNT_ID"

curl -X POST -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"install_gateway"}' \
  "https://seagit.com/api/org/$ORG_ID/clusters/$CLUSTER_ID/ingress-migration?accid=$ACCOUNT_ID"

# pending is null once the worker has answered
while true; do
  STATUS=$(curl -s -H "Authorization: $API_KEY" \
    "https://seagit.com/api/org/$ORG_ID/clusters/$CLUSTER_ID/ingress-migration?accid=$ACCOUNT_ID")
  if [ "$(echo "$STATUS" | jq -r '.data.pending')" = "null" ]; then
    echo "$STATUS" | jq '.data | {phase, weight, last_action_error}'
    break
  fi
  sleep 10
done

set_weight accepts only 0, 10, 25, 50 or 100. Any other value returns 400.

Try these requests in the API reference

Rolling back

After Move DNS back to NGINX, the stage returns to shifting traffic at 100%. Envoy keeps running, so you can move DNS to it again later. Reinstall the gateway sets up Envoy Gateway on a cluster that runs without nginx. It does not bring nginx back.

Troubleshooting

Frequently asked questions