Skip to main content

Serve a project from a data plane

Enterprise Tier

A project becomes callable when a platform administrator labels a data plane with it. The data plane then serves the project's configuration on every hostname it declares, alongside any other project labelled on it, and each request resolves to its project from its API key. This page covers data planes on 0.7.0 or later; earlier data planes are covered in Data planes before 0.7.0.

A project owns the logical configuration (models, keys, policy); a data plane is the physical capacity that serves it. A project label joins the two and is the only thing that does: the project names no data plane and owns no hostname, so a project can be moved to other capacity, or served from several data planes at once, without its configuration or its keys changing.

Persona: Platform operator working in the Admin Console, with a data plane already deployed.

Estimated time: 5 to 10 minutes, plus one configuration update on the data plane.

Outcomes​

By the end of this guide:

  • A data plane is labelled with the project and serves the project's configuration on the hostnames it declares.
  • The label reads verified: the data plane has answered a request for the project.
  • Developers see the project's endpoints in the Developer Console.

Prerequisites​

Step 1: label a data plane with the project​

The label can be applied in either of two places:

  • From the data plane. In the Admin Console, open Directory → Data Planes, select the data plane, and open its Project labels panel. Search for the project and add it. A data plane with no labels reads Serving nothing, by design, which is the normal state of a newly installed data plane.
  • While creating the project. The Create Project wizard's Data planes step applies the same labels before the project is created. See Create and delete a project.

The same write is available over the admin API as AddDataplaneProject (POST /admin/v1/customers/{customer_id}/dataplanes/{dataplane_id}/projects).

The data plane picks the project's configuration up on its next configuration update. Labelling the first project on a data plane does not restart its gateway; a few seconds of errors can remain while the data plane loads the configuration.

A data plane already serving one project accepts a second label only once it reports 0.7.0 or later. An older data plane refuses the label, and the refusal names the version it needs. Upgrade the data plane and let it poll the management plane once before adding the second label.

Step 2: confirm the data plane serves the project​

Each label on the data plane's page shows its progress in three steps:

  1. Label applied. The management plane recorded the label.
  2. Config pulled. The data plane holds the project's configuration. The step shows the revision the data plane holds and the one it picks up next.
  3. Verified. The data plane answered a request for this project, with the time of the first one. A label is verified only by the project's own traffic; another project's requests on the same data plane never verify it, and applying a label again clears it until the next successful request.

The project's Data Planes tab shows the same reading from the project's side: each data plane carrying the label, the addresses it reports, and whether it has served the project yet. The admin API reads it as ListProjectDataplanes (GET /admin/v1/customers/{customer_id}/projects/{project_id}/dataplanes), which answers with an empty list for a project nothing serves.

Send a request with a key issued for the project to confirm the label reaches Verified. See Issue a project-scoped API key.

Several projects on one data plane​

A data plane serves every project labelled on it, on every hostname it declares, so several projects share one hostname with no further DNS or certificate work. The API key decides the project:

  • A key whose project is not labelled on the data plane is refused with 403 and category hostname_not_selected. See Gateway behavior.
  • A model the caller's own project has not been granted is refused with 400 model_not_found, the same answer an unknown model gets, even when another project on the same hostname serves that model.
  • GET /v1/models lists the caller's own project's models, and each project sees only its own MCP servers and profiles.

The address developers see​

The Developer Console lists every endpoint the project is served from: each declared hostname of each data plane labelled with the project. One key works on every endpoint on the list. Where the console prints a single Base URL, it uses, in order:

  1. The project endpoint URL, when an administrator has set one. It is display only, and Agent Router never routes on it. See Gateway sets and DNS-level failover.
  2. The preferred endpoint, which a project owner stars in the Address column of the project's Data Planes tab.
  3. Otherwise, the first hostname a serving data plane declares.

A data plane that declares several hostnames is reachable on all of them, so the operator lists the name callers should use first in the data plane's chart.

When a project has no address​

A project that no data plane serves is fully configured but not callable:

  • The Developer Console holds back the Base URL, the code samples, and the integration snippets, and tells developers that the project is ready but nothing is callable until a platform administrator labels a data plane with it.
  • The Admin Console shows an empty Base URL for the project.

A project labelled on a data plane that reports no address is in the same position for callers. The data plane's page then reads This data plane reports no address, and the fix is to declare its hostnames. See Declare the hostnames a data plane serves.

Remove a label​

Remove a label from the data plane's Project labels panel, or over the admin API with RemoveDataplaneProject. The data plane drops the project's configuration on its next configuration update.

Removing the last label that serves a project is refused, because the project's keys would then work nowhere. The API call accepts acknowledge_last_endpoint to remove it anyway; the response then reports served_nowhere, and the audit log records PROJECT_SERVED_NOWHERE naming the project and the data plane. Tell the project's owners before doing this.

Data planes before 0.7.0​

A data plane before 0.7.0 cannot declare hostnames. It serves projects through project gateways, and each gateway serves on the URL stored for it on the management plane:

  • The management plane stores one address per data plane (set with SetDataplaneURL) and one URL per project gateway (set with SetProjectGatewayURL or the url field of CreateProjectGateway and UpdateProjectGateway). All of these calls are deprecated in 0.7.0 and keep working until no supported data plane predates 0.7.0. The 0.7.0 Admin Console has no field that writes either URL, so they are set over the admin API.
  • Each gateway URL's hostname is unique, so every project on such a data plane needs a hostname of its own, with DNS and certificate coverage for it.
  • While no project gateway on the data plane has a URL, the data plane answers on its stored address with a default route to every model. Setting a URL on the first project gateway removes that default route, so applications still calling the stored address stop being routed and must be repointed to the gateway hostname in the same change window. Existing keys keep working.

Once the data plane is upgraded to 0.7.0, declaring its hostnames replaces the stored address and the gateway URLs. See Move a data plane to declared hostnames.

For high availability across data planes, see Serve a project from two data planes. The gateway set model that earlier releases use is in Gateway sets and DNS-level failover.

Where to go next

Issue a project-scoped API key

Create a key that resolves to this project on every endpoint that serves it.

Manage a data plane's addresses and projects

Read the addresses a data plane reports and the projects labelled on it.

Grant MCP servers and profiles to a project

Expose tools on the same endpoints.

Serve a project from two data planes

Optional Enterprise high availability behind one hostname.