Skip to main content

Move a project to another data plane

Enterprise Tier

A project moves to another data plane by being served from both for a while: the target data plane declares the same hostname and is labelled with the project, DNS moves to it, and the label on the source data plane is removed. The hostname and the API keys stay the same throughout, so applications need no change.

A project names no data plane, and a key names no hostname: a key resolves to its project on every data plane labelled with that project. Two data planes of one organization may declare the same hostname. Together those two facts make a move a sequence of label and DNS changes, with both data planes able to serve the project in between. Upgrading a data plane in place is a different operation, covered in Upgrade a self-hosted data plane.

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

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

Outcomes​

By the end of this guide:

  • The project is served from the target data plane under the hostname applications already call.
  • The source data plane no longer serves the project, and was drained before its label was removed.
  • No key was reissued and no application was reconfigured.

Prerequisites​

  • Administrator access to the Admin Console, with data-plane operations permissions.
  • A target data plane on 0.7.0 or later, deployed and registered. See Deploy and register a data plane.
  • Control of the DNS record for the hostname applications call.
  • A certificate on the target data plane's load balancer that covers that hostname.

Step 1: declare the hostname on the target data plane​

  1. Add the hostname applications call to the target data plane's global.gateway.hostnames, or pass it with tare upgrade --gateway-hostname. See Declare the hostnames a data plane serves.
  2. Confirm the target data plane's page in the Admin Console lists the hostname, and that the certificate reading beside it covers the name.

Both data planes now declare the hostname. DNS still points at the source data plane, so no traffic moves yet.

Step 2: label the target data plane with the project​

  1. On the target data plane's page, open Project labels and add the project.
  2. Wait until the label reads config pulled. The target data plane now holds the project's current configuration.

A target data plane that already serves another project accepts the label only once it reports 0.7.0 or later.

Step 3: move DNS to the target data plane​

  1. Point the hostname's DNS record at the target data plane's load balancer, or shift its weight there.
  2. Wait out the record's TTL.
  3. Confirm the label on the target data plane reads verified, which means it answered a request for the project.

Step 4: drain the source data plane​

Confirm no traffic for the project still reaches the source data plane. Request attribution is per data plane, so filter request logs or usage by the source data plane, or query the request-log stats with group_by=dataplane and a start_time after the TTL expired. A count that stays above zero means a client still resolves the old record or calls the source data plane by another name.

Step 5: remove the label from the source data plane​

  1. On the source data plane's page, open Project labels and remove the project.
  2. If the source data plane no longer serves anything under the hostname, remove the hostname from its global.gateway.hostnames as well.

The source data plane drops the project's configuration on its next configuration update. Removing the label first and moving DNS second would refuse the project's callers on the source data plane with 403 until DNS moved.

What stays fixed​

Throughout the move:

  • The hostname applications call does not change.
  • Existing API keys continue to work, because a key belongs to the project, not to a data plane or a hostname.
  • The project's configuration does not change. Both data planes receive the same project revision, and the label on each shows which revision it holds.

Rate-limit counters do not move: each data plane counts only the traffic it sees, so callers meet a fresh window on the target data plane.

Data planes before 0.7.0​

A data plane before 0.7.0 cannot declare hostnames, and two project gateways cannot share a hostname. Move a project gateway between such data planes with SetProjectGatewayWorkspace over the admin API, after provisioning the target's DNS record and certificate, and cut DNS over immediately afterward: between the move and the DNS change, requests to the hostname reach the source data plane, which no longer serves it, and are refused. Upgrading the target data plane to 0.7.0 first allows the sequence above instead.

Where to go next

Serve a project from two data planes

Keep both data planes labelled to run a high-availability pair.

Manage a data plane's addresses and projects

Operate the labels on the source and target data planes.

Plan high availability and disaster recovery

Use a move as part of a broader resilience plan.

Load balance across regional deployments

Distribute model backends and traffic across regions.