Hostnames and high availability
A hostname is the address an application calls. It belongs to the data plane that answers for it, not to the project that uses it, and that one fact explains the rest of this page: why you cannot create a hostname from the Admin Console, why several projects can safely share one, and why high availability is two addresses behind one name rather than a load balancer we run for you. Data planes and projects ship today, and hostname selection and shared hostnames are planned for the 2026 Q3 release.
What a hostname is
A hostname is a DNS name a data plane answers for, declared by the operator in that data plane's own configuration.
It is immutable once exposed: it is added and removed, never renamed. A data plane may expose several hostnames, and several data planes may expose the same one.
Hostnames have no relationship to projects. Any hostname a project has selected can serve that project, because each request resolves to its project from the API key that made it, never from the Host header it arrived on.
Where a hostname comes from
Not from the Admin Console. No surface in Agent Router creates a hostname, because a name the management plane invented is a name nothing guarantees a data plane actually answers for. A hostname exists because a data plane says it does.
It comes into being through the data plane's own configuration, and three things have to line up:
- The declaration. The name is listed in that data plane's Helm values, among the hostnames the installation exposes.
- The certificate. Its SANs cover every hostname that data plane exposes, so adding one to a data plane already serving others reissues or extends the certificate. That lead time belongs to your certificate authority, and it is stated before you commit rather than discovered after the rollout.
- DNS. An A record points the name at that data plane's address.
Once the chart is applied, the data plane reports the hostnames it exposes on its next call home, and the management plane records what it reported. Only then can a project select it, and the selection list shows exposed hostnames only, so it can never produce a name that nothing serves.
There is no rename and no delete button. Retiring a hostname is a chart change plus a certificate reissue plus a DNS removal. To move a project to a different name, the operator exposes the new one, the project administrator adds it to the selection and drops the old one, and the operator then retires the old exposure. Agent Router gates each step and hands over the instructions; it does not perform them.
Selection: how a project gets served
A project selects the hostnames it should be served on. It is a literal list of names, and it never names a data plane.
Selecting a hostname begins serving the project there at the next configuration pull. Dropping one zeroizes that project's configuration on the hostname at the next pull; until that pull lands, the project's keys still admit there.
Two rules keep the sides apart:
- Only a project-side administrator changes a selection. It is the only path by which a project's serving surface widens — no operator action anywhere else in your estate can add a hostname to a project.
- Only an operator exposes a hostname, and exposing one never decides who is served on it.
A project with no hostname selected is allowed — staging projects run this way — but it is served nowhere, and Agent Router says so rather than leaving it silent.
Several projects on one hostname
Sharing is normal, and it is safe because isolation comes from the credential rather than the address.
Each request resolves to its own project by its own API key, with that project's models, policy, budgets, and attribution. Call a hostname your project has not selected and the request is refused with 403 hostname_not_selected, naming the hostnames you can use.
This is what lets a platform team expose one name for a whole estate, or one per environment or per team, without provisioning a separate address for every project.
High availability: two addresses, one name
Several data planes exposing the same hostname is how Agent Router does high availability. Nothing is provisioned in front of the data planes — the failover happens at the DNS layer, and you choose the topology.
bar.example.com. 300 IN A 3.120.44.17 ; dp-eks-fr-1
bar.example.com. 300 IN A 52.14.88.203 ; dp-eks-us-1
Because both data planes answer for the same name, a GSLB does not have to rewrite a Host header on failover. The configuration served for the hostname is the same on both, so either one can serve any project that selected it.
Agent Router gives you three things and takes no position on how you run DNS:
- The records, ready to copy.
- A health-check contract —
HTTPS GET /healthzagainst each data plane's address, accepting 2xx only, matching"status":"ready", at a 10-second interval with a threshold of 3. - Per-data-plane evidence that the two are actually equivalent.
Whether both addresses run in rotation or one is held in reserve is your choice. A data plane serving zero requests is not a fault; it is a DNS decision.
The HA verification receipt
For any DNS topology, the Admin Console answers whether the pair is genuinely interchangeable, on four readings:
| Reading | What it answers |
|---|---|
| Convergence | Does every data plane exposing this hostname hold the current revision of every project selecting it? Convergence is per hostname, not a bundle version — versions are not comparable across data planes. |
| Health checks | Is each data plane passing against the contract above? |
| Request attribution | How much traffic each data plane served. Zero on one side is a topology choice, not a failure. |
| Divergence | Do the data planes serving this hostname actually agree? |
Divergence and drift are different questions, and both persist rather than clearing themselves. Drift is one data plane against the configuration the management plane sent it. Divergence is whether the data planes behind one hostname agree with each other. A difference somebody chose — a management-plane override on one of them — is reported with its cause rather than treated as a fault, because a receipt that reported convergence alone would call two data planes identical while their effective configuration differed.
Reachable and verified
Two words that look similar and answer different questions:
- Reachable is a property of the hostname alone: DNS resolves, TLS terminates, and a data plane answers. It is shared by every project that selects the name.
- Verified is per project and hostname: a first successful request observed on that hostname and attributed to that project by the credential that made it.
Verified is never inherited. A hostname is reachable once, and each project still earns its own proof of life on it.
Terms introduced on this page
Terms below appear only on this page.
| Term | Meaning |
|---|---|
| Selection | The list of hostnames a project should be served on. A literal list of names, chosen from the project side, that never names a data plane. |
| Convergence | Whether every data plane exposing a hostname holds the current revision of every project selecting it. Read per hostname; revisions are not comparable across data planes. |
| Divergence | Whether the data planes exposing one hostname agree with each other. A difference somebody chose is reported with its cause rather than treated as a fault. |
| Drift | One data plane measured against the configuration the management plane sent it. Distinct from divergence, and it persists rather than clearing itself. |
| Reachable | A property of a hostname alone: DNS resolves, TLS terminates, and a data plane answers. Shared by every project that selects the name. |
| Verified | Per project and hostname: a first successful request observed on that hostname and attributed to that project by the credential that made it. Never inherited from another project. |