Manage a data plane's addresses and projects
Enterprise Tier
A data plane's page in the Admin Console answers two questions: which addresses the data plane serves, and which projects it serves on them. The addresses come from the data plane's own Helm values and are read only in the console. The projects are the data plane's project labels, which a platform administrator edits on the same page.
A data plane serves every project labelled on it, on every hostname it declares. Adding a project to a data plane is a label, not a new hostname: several projects share the data plane's hostnames, and each request resolves to its project from its API key.
Persona: Platform operator with data-plane operations access, working in the Admin Console.
Estimated time: 10 to 15 minutes.
Outcomes
By the end of this guide:
- The addresses a data plane reports, and where each comes from, can be read.
- The certificate serving each address can be checked.
- Projects can be added to and removed from the data plane, with each label's progress read.
Prerequisites
- Administrator access to the Admin Console, with data-plane operations permissions. Attaching a project to a gateway, detaching one, and deleting a gateway with a project-owner credential are deprecated in 0.7.0 and need a platform administrator from 0.9.0. Until then a project owner can still make these changes while the gateway serves only projects they own; once it serves another owner's project, a project-owner credential answers
403. Automation that does this with a project-owner credential moves to an administrator credential before 0.9.0. - A data plane deployed and registered. See Deploy and register a data plane.
Step 1: read the addresses the data plane reports
- In the Admin Console, open Directory → Data Planes and select the data plane.
- Read its addresses. Each row is one address callers can use, in the order the data plane's chart lists them. The first is the address the consoles print wherever they show a single one.
An address comes from one of two places:
- The data plane's chart. A data plane on 0.7.0 or later lists its hostnames under
global.gateway.hostnamesin its serve-helm values and reports them on every configuration poll. These rows cannot be edited in the console: adding or retiring one is a change to the values followed bytare upgradeorhelm upgrade. See Declare the hostnames a data plane serves. - The management plane. A data plane whose chart declares no hostnames, including every data plane before 0.7.0, lists the address stored for it with
SetDataplaneURL, followed by its project gateway URLs. These rows are tagged set through the management plane, and the page offers the serve-helm values that declare the same addresses. See Move a data plane to declared hostnames.
A data plane with no address reads This data plane reports no address. One that has never called home reads as newly installed. A data plane that reports no address serves the projects labelled on it, but no caller can reach them.
Step 2: check the certificate serving each address
A data plane on 0.7.0 or later reads the certificate serving each declared hostname and reports, beside the address, whether the certificate covers it, how long it has left, the issuer, the names it carries, and where the reading was taken. An address the data plane could not reach reads as not observed and names the openssl command to read it by hand; that leaves the data plane healthy. Data planes before 0.7.0 show no reading.
Where the data plane cannot reach the endpoint that terminates TLS, the chart's global.gateway.certificateProbe key names another address or turns the reading off. tare doctor --only gateway reads the same certificate from the cluster. See Declare the hostnames a data plane serves.
Step 3: edit the projects the data plane serves
- On the data plane's page, open the Project labels panel.
- Add a project to serve it from this data plane, or remove one to stop serving it here.
Each label shows three steps: label applied, config pulled (with the revision the data plane holds and the one it picks up next), and verified (when the data plane first answered a request for that project). A label stuck at config pulled points at the data plane's configuration poll; one stuck before verified means no request for the project has reached this data plane yet.
Two rules apply to the edits:
- A second project on a data plane needs the data plane to report 0.7.0 or later. An older data plane refuses the label and names the version it needs.
- Removing the last label that serves a project is refused unless the removal is acknowledged, and an acknowledged removal records
PROJECT_SERVED_NOWHEREin the audit log.
The full procedure, including the API calls, is in Serve a project from a data plane.
Delete a data plane
Deleting a data plane is refused while it is the only one serving a project. The refusal names up to ten of those projects and the total. Label each named project on another data plane, or remove its label from this one and tell its owners that it is served nowhere, then delete the data plane again. A data plane whose projects are all served elsewhere is deleted as before.
Deleting the data plane withdraws the management plane's state and its credential. The cluster empties itself only when the data plane next polls for configuration and receives the zeroize directive; a data plane that never polls again keeps serving what it holds.
Spread projects across data planes
Placing a project in a region or cloud is a label on a data plane that runs there. Serving one project from several data planes for availability is covered in Serve a project from two data planes. Balancing model backends across regions is a separate concern, covered in Load balance across regional deployments.
Where to go next
Move a project to another data plane
Serve the project from a new data plane under the same hostname, then remove the old label.
Serve a project from two data planes
Optional Enterprise high availability behind one hostname.
Understand guardrail enforcement on shared capacity
On shared capacity, each project's guardrails apply only to its own traffic.
Plan high availability and disaster recovery
Topology and recovery planning across data planes.