Projects, data planes, and hostnames
Enterprise Tier
A project owns the configuration, a data plane serves it, and the hostnames the data plane declares are the addresses callers use. A platform administrator connects the two by labelling the data plane with the project.
How the pieces fit
- A project is the single configuration authority: models, keys, Model Context Protocol (MCP) access, guardrails, and members all belong to it.
- A data plane is the request-path deployment in the customer's cluster. From 0.7.0 it lists the hostnames it serves in its own Helm values, its declared hostnames, and reports them to the management plane.
- A project label connects the two. A data plane serves the configuration of every project labelled on it, one data plane and one hostname can serve several projects, and one project can be served by several data planes.
Agent Router ships no traffic steering. The DNS name callers use, the health checks, and the failover policy stay with the operator.
Which guide for which task
Deploy and register a data plane
Provision the data plane, install its credential, and connect it to the management plane.
Declare the hostnames a data plane serves
List the names, wire DNS and certificates, and move a data plane off its stored address.
Serve a project from a data plane
Label a data plane with a project and confirm it serves the project.
Manage a data plane's addresses and projects
Read the addresses and certificates a data plane reports and edit its project labels.
Move a project to another data plane
Serve the project from a new data plane under the same hostname.
Fail over between data planes
Serve one project from two data planes with customer-managed DNS failover.
Readiness probe and the /healthz contract
What the probe answers, and how to enable the published readiness contract.
Per-data-plane request attribution
Every request is attributed to the data plane that served it: the reporting data plane's identity, stamped server-side when its telemetry reaches the management plane, and the usage and request-log surfaces are filterable by data plane. Attribution is data-plane granularity, not per-gateway: a data plane can host gateways from several projects, and gateways co-located on one data plane share an attribution bucket. This is what makes failover auditable and drains verifiable:
- An audit trail survives failover: the record shows which data plane served each request, not just which project. When each member runs on its own data plane, that resolves the record to the member.
- An incident can be localized: filter usage or request logs by data plane and compare the members' data planes.
- A drain can be verified empirically before a detach (the detach runbook relies on this) provided the member's data plane hosts no other serving gateway, from any project. A shared data plane's counts include every co-located gateway; give a member a dedicated data plane if drain verification matters.
Two caveats. Attribution follows the data plane: migrating a gateway to a different data plane splits its request history across the two data-plane buckets. And requests recorded before data-plane attribution existed appear under an unattributed "" bucket rather than any data plane's.
Gateway sets before 0.7.0
Multi-gateway projects require an Agent Router Enterprise release that includes the multi-gateway projects capability, and the deployment itself must declare the Enterprise product line (DEPLOYMENT_PRODUCT=enterprise, derived from the installation charts; the gate fails closed, so a deployment that does not declare it behaves as Agent Router Service). On earlier releases a project maps to exactly one gateway and this section does not apply. This surface does not exist on Agent Router Service (SaaS).
Before 0.7.0 a project is served through gateways, and the project's attached gateways form its gateway set. On a data plane on 0.7.0 or later the project label replaces the gateway attachment, and the model below describes data planes before 0.7.0.
Identical by construction
A project is the single configuration authority; its attached gateways form its gateway set, whose members are interchangeable. Every member receives the identical project configuration (authentication and authorization, guardrails, and the model and Model Context Protocol (MCP) catalogs) generated from the same project state. Per-member variance is limited to identity, URL, name, and labels. Divergence of desired configuration between members is not reconciled after the fact; it is unrepresentable. There is no per-member override surface at all. Delivery, though, is by data-plane-initiated polling: at any instant the guarantee is identical desired configuration plus a bounded convergence window, during which members can serve different revisions of the same project configuration. Each member's configuration version and sync state are surfaced on the Gateways tab.
For security review this means the project, not the gateway, is the unit of review: no failover event can reach a boundary that was never part of the project's configuration, because there is no member on which a different rule set could exist. Reviewing the project's policy once covers every member it will ever have, including members attached after the review. The convergence window is the one nuance: after a security-tightening change, a client failing over to a member still catching up can observe the previous (looser) boundary until that member converges. Confirm every member reports the new configuration version before treating a tightened boundary as enforced fleet-wide, a check that is meaningful only for attached, reachable members with management-plane connectivity. Treat an empty configuration-version column as convergence unconfirmed, not as converged.
Membership states
Each member is in exactly one state, shown in the Status column of the project's Gateways tab:
| State | Meaning | Operational significance |
|---|---|---|
syncing | The member is converging on the project's current configuration version. | A freshly attached member that has never converged serves nothing and probes red. It cannot receive traffic prematurely. A previously ready member that is catching up to a config change keeps serving its last-known-good configuration and probes green. |
ready | The member has confirmed convergence on the project's current configuration version. | A valid traffic and failover target. Advertised in the project view with its configuration version and last-seen time. |
detached (zeroized) | Detach completed and the gateway acknowledged the final, emptied configuration: routes, credentials, and catalogs removed. | Teardown is confirmed. The listener may still be up; the probe is red (a true no-route 404, the probe path is exempt from gateway authorization). Client traffic on the drained hostname is rejected 403 unknown_host if the data plane hosts any other serving gateway, and gets a no-route 404 only when it hosts none. Expect 403s in client logs during a drain on a shared data plane. Nothing further is required. |
detached (unreachable) | Detach was requested but the gateway never acknowledged the zeroized configuration; the management plane revoked its identity as the backstop. | The gateway can no longer fetch project configuration or authenticate to the management plane, but its local teardown is unconfirmed. A partitioned-but-reachable gateway may still be serving its last-known configuration and answering its probe green. Remove its DNS record manually and verify decommissioning (see the detach runbook). |
A member is promoted from syncing to ready only on confirmed convergence, so no client ever reaches a half-configured gateway: until a new member is ready, its probe stays red and health-checked DNS never routes to it.
Zero gateways is a valid state
A project with zero attached gateways is a fully valid, fully configured project: keys, models, guardrails, and members are all retained. The Gateways tab shows a "nothing serving" state, which is a description, not an error. Use it deliberately:
- Stage before capacity exists. Configure a project completely (policy reviewed, keys issued) before any gateway is attached. Attaching the first gateway later materializes the already-reviewed configuration.
- Drain to zero safely. Detaching the last member leaves the project intact and re-attachable; nothing about the project is torn down with its capacity.