Skip to main content

Move a data plane to declared hostnames

Enterprise Tier

Before 0.7.0 the management plane stored a data plane's address, written through SetDataplaneURL or the Admin Console, and each project gateway carried its own URL. From 0.7.0 a data plane declares its hostnames in its serve-helm values instead, and the stored calls are deprecated. A data plane crosses over the moment its chart lists the first name, so the list has to be complete in that one change.

Persona: Platform operator with access to the data plane's Helm values or tare identity file and to the Admin Console.

Estimated time: 15 to 30 minutes per data plane, plus one configuration poll.

Outcomes​

By the end of this guide:

  • The data plane's chart declares every hostname it serves, and the Admin Console lists each one as declared in the chart.
  • No project gateway on the data plane carries a hostname the chart does not declare, so later gateway edits are not refused.
  • The rollback path is known: removing the key returns the data plane to its stored address.

Prerequisites​

  • The data plane runs 0.7.0 or later. Upgrading to 0.7.0 with untouched values keeps it on the stored address and changes nothing about where it serves, so the upgrade itself is safe to take first. See Upgrade a self-hosted data plane.
  • The values file the data plane was installed with, for a Helm or GitOps install. tare installs carry their values in the release.

What changes when the first name is declared​

There are 3 things that change on the data plane the moment its chart declares at least one hostname:

  1. The declared names replace the stored address everywhere: in the Admin Console, in the readiness probe, and in the address the console prints.
  2. CreateProjectGateway, UpdateProjectGateway, and SetProjectGatewayURL accept only a hostname the data plane declared. Any other hostname is refused with FailedPrecondition naming global.gateway.hostnames. A console or API edit that resends a gateway's own unchanged URL is refused the same way when that hostname is missing from the list.
  3. SetDataplaneURL no longer copies the data plane's address onto its default gateway. It still records the address, which the data plane uses again only if the key is removed from its chart.

A data plane whose chart declares nothing keeps the pre-0.7 behavior for all three, so each data plane crosses over on its own schedule.

Step 1: inventory the names in use​

  1. In the Admin Console, open Directory → Data Planes and select the data plane.
  2. Read the addresses it lists. While the chart declares nothing, the page lists the stored address first, then the URL of each project gateway on the data plane, each tagged set through the management plane. The page also offers the serve-helm values that declare the same addresses.
  3. Add any hostname callers reach the data plane on that the page does not show, such as a client-facing failover name that DNS points at this data plane.
  4. Choose the name callers should use and put it first. The console prints the first name wherever it shows a single address.

The same list is available from the API, through the call that lists a data plane's hostnames. Each entry carries a source of chart or management-plane.

Step 2: declare the complete list in one change​

Declare every name from Step 1 at once. A partial list turns the gate on for the names left out, and the next edit of a gateway carrying one of them is refused.

With tare:

tare upgrade /path/to/data-plane-credentials.json \
  --gateway-hostname=ai.acme.example.com \
  --gateway-hostname=proxy.acme.example.com \
  --gateway-hostname=bedrock-team.acme.example.com

With Helm or GitOps, add the list to the values file and apply it with that file:

global:
  gateway:
    hostnames:
      - ai.acme.example.com
      - proxy.acme.example.com
      - bedrock-team.acme.example.com
helm upgrade tars "oci://${PRIVATE_IMAGE_REGISTRY}/serve-helm" -f values.yaml

Each name keeps the DNS record, certificate, and load balancer route it already has. A name added for the first time needs all three; see Declare the hostnames a data plane serves.

Step 3: confirm the crossover​

  1. Read the rendered declaration:

    kubectl -n tars-system get configmap tars-gateway-declaration -o jsonpath='{.data.gateway-hostnames}'

  2. After the data plane's next configuration poll, reload its page in the Admin Console. The rows no longer carry the set through the management plane tag.

  3. Check the readiness probe on each name. On a data plane on 0.7.0 or later the probe answers for the whole data plane:

    curl -s https://ai.acme.example.com/healthz/membership
    {"status":"ready","dataplane":"dp-prod-use1"}

  4. Run tare doctor /path/to/data-plane-credentials.json --only gateway and clear any warning that the certificate does not cover a declared name.

Draining a data plane​

An explicit empty list is different from leaving the key out. It declares that the data plane serves no hostname: the management plane retires every name it recorded for the data plane, the readiness probe answers 404 on every address, and the three gateway URL calls go back to the pre-0.7 behavior for that data plane.

tare upgrade /path/to/data-plane-credentials.json --gateway-hostname=""

Use it only to take a data plane out of DNS rotation on purpose. Shift DNS away from the data plane before draining it, because a caller whose DNS still points at a drained data plane gets no route.

Rollback​

Remove global.gateway.hostnames from the values file and upgrade, or upgrade with Helm without the key. The data plane goes back to the address stored for it through SetDataplaneURL and answers its readiness probe there. The stored address is never deleted by declaring hostnames, so nothing has to be re-entered.

A plain helm upgrade without the values file has the same effect by accident. Keep the list in the values file applied on every upgrade.

Deprecation timeline​

SetDataplaneURL, its SetWorkspaceURL alias, SetProjectGatewayURL, and the url field of CreateProjectGateway and UpdateProjectGateway are deprecated in 0.7.0. They keep working until no supported data plane predates 0.7.0, because a data plane before 0.7.0 cannot declare hostnames. Keep using SetDataplaneURL for such a data plane until it is upgraded. The Admin Console on 0.7.0 no longer has a field that writes either URL. See Deprecations.

Where to go next

Declare the hostnames a data plane serves

The rules for the list, DNS, certificates, routes, and the certificate probe.

Upgrade a self-hosted data plane

The upgrade order and what each release asks of it.