Skip to main content

Provision a gateway for a project

Enterprise Tier

A gateway is a single inference endpoint, one customer-facing URL, provisioned by a data plane and mapped to exactly one project. Selecting a data plane on the project provisions its first gateway automatically: there is no separate top-level Gateways menu and no create-then-select flow. Attaching additional gateways for high availability is optional and covered later on this page.

A project owns the logical configuration (models, keys, policy); a gateway is the physical capacity that serves it. The two are separate on purpose, so the endpoint can later be upgraded or moved between data planes without the project's configuration or its URL changing.

Persona: Platform operator working in the Admin Console, with a data plane already available to provision on.

Estimated time: 10 to 20 minutes, plus reconciliation and DNS propagation.

Outcomes​

By the end of this guide:

  • The project is placed on a chosen data plane, and a gateway is auto-provisioned for it with the customer-facing URL applications will call.
  • By default the project has one gateway; each gateway still serves exactly one project. On Enterprise, additional gateways can optionally be attached later for high availability (see Optional: attach additional gateways for HA).
  • The gateway has reconciled and reports ready, and its URL is shown on the project.

Prerequisites​

Step 1: select a data plane on the project​

  1. In the Admin Console, open Projects and select the project.
  2. On the project, select the data plane that should host this project's gateway.
  3. Set the customer-facing URL that developers will call, for example https://bedrock-team.acme.example.com. Routing is by hostname, so each project's gateway carries its own hostname.

Selecting the data plane provisions the first gateway automatically. There is no separate create step in a top-level Gateways menu for that default path. Additional gateways are attached later only when high availability is configured (see Optional: attach additional gateways for HA). The data plane is shared provisioning capacity: it can provision and manage many gateways at once. Choosing which data plane hosts the gateway is how a project is placed in a particular region or cloud.

Step 2: confirm the gateway is ready​

  1. Watch the gateway's status as the data plane reconciles the desired configuration.
  2. Confirm the gateway reports ready and its URL is shown on the project.

Once ready, requests sent to the gateway's hostname, authenticated with a key issued for the project, resolve to that project's configuration and nothing else. Cross-project requests are refused: a key from another project returns 403, and a model the project has not been granted returns 404.

Each project gateway needs its own hostname​

Routing is by hostname, and the host part of a gateway URL is unique across every project gateway in the deployment. Two projects cannot share one hostname, so a data plane installed with a single hostname serves a single project until further hostnames are exposed on its ingress. A hostname already bound to another gateway is rejected rather than applied.

Adding a project to an existing data plane therefore needs three things for the new hostname:

  • A DNS record resolving it to the data plane's ingress address.
  • TLS coverage. A wildcard certificate on the shared domain covers every present and future project hostname with no further certificate work. Where a wildcard is not available, each hostname is added to a certificate as a subject alternative name, which is a reissue per certificate. The trade-off between the two shapes is set out in Gateway sets and DNS-level failover.
  • Registration of the hostname on the project's gateway, as in Step 1.

Planning the hostnames before projects are created avoids the sequence where a project exists, has models granted, and still cannot serve traffic.

"The administrator needs to complete the DP URL configuration"​

This message appears for a project whose gateway has no URL registered. It reports missing configuration, not a failed connection: no connection is being attempted, and no traffic reaches the project until a hostname is recorded for its gateway.

The usual trigger is a second project created on a deployment whose data plane exposes one hostname. That hostname belongs to the first project's gateway, the new project's gateway has none, so there is no endpoint to show for it.

Two ways forward:

  • Expose an additional hostname. Complete the DNS, TLS, and registration steps above for the new project. This is the durable answer for any deployment running more than one project.
  • Use the default project meanwhile. Where the message appears during an evaluation and the DNS or certificate work is not yet practical, the default project already holds the deployment's single hostname and is ready for traffic. Whether the deployment should expose further hostnames for project testing is a question for Tetrate.

The same message also appears when no data plane URL has been registered at all. That is a workspace-level setting rather than a project one, and it is cleared under System → Settings → Data planes. See The Data plane URL field.

Repoint existing clients​

If applications previously called the data plane's single shared workspace URL and are moving onto project gateways, the change is small and does not require new keys.

The shared workspace URL stops serving once the first project gateway has a URL

While no project gateway on the data plane has a URL, the data plane answers on the shared workspace URL with a default route to every model. Registering a URL on the first project gateway suppresses that default route, and the data plane then serves only project gateway hostnames. Applications still calling the shared workspace URL are no longer routed from that point, so repoint them in the same change window.

  1. Keep existing keys: the same key continues to work, so nothing needs to be re-issued.
  2. Repoint each application's base URL (or Host) from the shared workspace URL to the project's gateway hostname.
  3. Confirm the project is wired up: its gateway has a URL, DNS resolves that hostname to the data plane ingress, and the models the application uses are granted to the project.

Calling a project's models over the OpenAI-compatible API is covered on the developer side in Make an API call.

Optional: attach additional gateways for HA​

Most projects run with the single gateway provisioned in Steps 1 and 2. Attaching more members is an optional Enterprise high-availability step: it is not required for a working project.

Availability

Attaching more than one gateway to a project requires an Agent Router Enterprise release that includes multi-gateway projects, and the deployment must declare the Enterprise product line (DEPLOYMENT_PRODUCT=enterprise, chart-derived; the gate fails closed). This surface does not exist on Agent Router Service (SaaS).

When HA is needed, a project can attach several gateways at once. Every attached gateway receives the identical project configuration by construction (authentication, guardrails, and catalogs cannot diverge between members) which is what makes the members safe failover targets for one another. The full membership model, the health-probe contract, and the DNS failover pattern are covered in Gateway sets and DNS-level failover.

Attach​

  1. In the Admin Console, open the project and its Gateways tab.
  2. Choose Attach gateway and select an existing unattached gateway, or provision a new one on a target data plane (provisioning remains the only way a gateway is created).
  3. The new member appears with status syncing while it converges on the project's configuration. It is promoted to ready (and starts answering its membership probe) only once convergence is confirmed, so it cannot receive health-checked traffic half-configured.

The Gateways tab lists each member with its URL, status, health, configuration version, and last-seen time, so fleet consistency is verifiable at a glance.

Detach​

  1. Shift any client traffic away from the member first (via the DNS layer that fronts the members), and verify the drain through request attribution for the member's data plane. Attribution is per data plane, not per gateway: the count is only the member's own when no other serving gateway shares its data plane. The full verification procedure, including this caveat, is in the failover guide's runbook.
  2. Choose Detach on the member's row. The confirmation shows the request count for the member's data plane over the trailing hour: a fixed window, so traffic from before the DNS shift still counts toward it for up to an hour.
  3. The member is actively emptied (routes, credentials, and catalogs removed) and lands in a terminal state: detached (zeroized) (teardown confirmed) or detached (unreachable) (credentials revoked; verify decommissioning manually).

Detach is not delete: the gateway record survives, and the project is untouched. The ordered runbook, with the terminal-state interpretation, is in Gateway sets and DNS-level failover.

Since 0.3.0, deleting the last project gateway on a data plane does not switch off its project isolation: the data plane keeps refusing requests until a gateway is configured again.

The gateway cap​

The number of gateways a project can attach is capped: 10 by default, configurable per deployment. Attaching beyond the cap fails with a clear at-cap error rather than silently queueing; raising the cap is a deployment-configuration change, not a project setting.

Zero gateways is a valid state​

A project with no attached gateways remains a fully valid, fully configured project: keys, models, policy, and members are all retained, and the Gateways tab shows a "nothing serving" state. Use it to stage a project's configuration before capacity exists, or to drain a project to zero without tearing anything down. Attaching a gateway later (re)materializes the existing configuration.

Where to go next

Issue a project-scoped API key

Create a key that works only against this project's gateway.

Manage multiple gateways on a data plane

Review the gateways a single data plane manages after projects select it.

Grant MCP servers and profiles to a project

Expose tools through the same gateway.

Gateway sets and DNS-level failover

Optional Enterprise HA.