Skip to main content

Migrate a gateway or upgrade its runtime

Enterprise Tier

A gateway's runtime can be upgraded in place or moved to a different data plane, for example to relocate a project to another region or cloud, or to retire an old cluster. Because the gateway's URL and its project mapping stay fixed through the change, the migration is transparent to the applications calling it. This guide covers the migration sequence and what keeps it non-disruptive.

The gateway is a durable record: its customer-facing URL and its one-to-one project mapping do not change when the underlying runtime is upgraded or moved. What changes is the data plane that provisions the runtime behind it. The sequence is designed so that a working runtime is always serving traffic, and cutover happens only once the replacement is ready.

Persona: Platform operator with data-plane operations access, working in the Admin Dashboard and coordinating the routing or DNS change.

Estimated time: 30--60 minutes, plus DNS propagation and drain time.

Outcomes​

By the end of this guide:

  • A gateway's runtime is upgraded in place, or its serving data plane is changed, without changing the gateway's URL.
  • The project-to-gateway mapping is unchanged throughout.
  • In-flight requests are drained rather than dropped during cutover.

Prerequisites​

  • Administrator access to the Admin Dashboard, with data-plane operations permissions.
  • For a migration between data planes, a target data plane already deployed and registered. See Deploy and register a data plane.
  • Control of the routing or DNS layer that resolves the gateway's hostname, so cutover can be performed.

Step 1: Provision the target runtime​

  1. Start the upgrade in place, or begin a migration by having the target data plane provision a runtime for the gateway.
  2. During a migration, allow both the source and target data planes to run a runtime for the gateway concurrently.

Running both runtimes at once means the existing endpoint keeps serving throughout preparation, so there is no window in which the gateway is unavailable.

Step 2: Cut over once the target reports ready​

  1. Wait until the target runtime reports ready.
  2. Cut over at the routing or DNS layer, pointing the gateway's hostname at the target runtime.

Cutover is a routing change, not a change to the gateway record. The customer-facing URL is the same before and after, so applications need no reconfiguration and no new keys.

Step 3: Drain and retire the source runtime​

  1. Allow the source runtime to drain its in-flight requests rather than terminating it immediately.
  2. Retire the source runtime once it has drained.

Draining is what makes the cutover non-disruptive: requests already in progress on the old runtime complete, while new requests land on the target.

What stays fixed​

Throughout an upgrade or migration:

  • The customer-facing URL does not change.
  • The project-to-gateway mapping does not change.
  • Existing API keys continue to work, because they are scoped to the project and the gateway, not to the runtime behind them.

This stability is the point of separating the durable gateway from the runtime that serves it. Distributing projects across data planes by region or cloud, which migration makes possible, is covered in Load balance across regional deployments.

What to do next​

Where to go next

Load balance across regional deployments

Distribute projects and traffic across data planes by region or cloud.

Manage multiple gateways on a data plane

Operate the gateways on the source and target data planes.