Custom domains

Every service is reachable on the service hostname GraphPilot issues for it, <subdomain>.<label>.graphpilot.cloud (see the hostname label; older services keep <subdomain>.graphpilot.cloud). You can add one of your own, so requests go to api.your-company.com instead. Both keep working: adding yours does not switch GraphPilot’s hostname off. The portal calls that one the platform hostname.

Plans Jet (Starter) and above Permission service:edit

What you need

• A paid plan. Glider (Free) includes no custom domains. Paid plans include an allowance of them, counted across every service and every organization your billing account funds, not per service. See pricing, and Billing and usage for how many you use.
• Permission to edit the service. Ask an administrator of your organization if the page shows the hostnames but offers no actions.
• A domain your organization has verified. This is the part people miss, so it has a section of its own below.

Verify the domain once per organization

Before any service can answer on api.your-company.com, your organization has to prove it controls the domain. That happens once, at the organization level, by creating a TXT record.

1. Open Settings → Domains in your organization, or start from the service’s Settings → Domains: select Add domain, and if nothing is verified yet the dialog offers Verify a domain, which opens the same dialog, so you do not have to change pages.

2. Enter the domain and create the TXT record it shows you with your DNS provider.

3. Wait for the state to become verified. Until then the domain appears in the service’s domain picker but cannot be chosen.

Verifying covers everything below it. Verify your-company.com once, and every service in the organization can use your-company.com itself, api.your-company.com, api.eu.your-company.com, and anything else under it. You do not verify a hostname per service.

The reverse also holds: verifying only api.your-company.com covers that hostname and what sits under it, and nothing else. If you expect to add more hostnames later, verify the registrable domain rather than one subdomain.

A verified domain is what stops a hijack

A hostname that points at GraphPilot but belongs to nobody could otherwise be claimed by whoever noticed it first. That is why the check is on ownership rather than on whether the DNS record happens to exist, and why evil-your-company.com is not covered by a verified your-company.com: the match is on a label boundary, not on how the name ends.

Attach the hostname

1. Open the service’s Settings → Domains and select Add domain.

2. In the Add a custom domain dialog, pick the verified domain and type the subdomain in front of it. The full hostname is shown as you type.

3. Leave the subdomain empty to use the verified domain itself, including a registrable domain such as your-company.com.

4. Select Add domain.

If your allowance is used up, the page says so. To use a different hostname, remove one you no longer need first: Remove is in the hostname’s menu.

Create one DNS record

The hostname appears in the list as Waiting for DNS, and shortly after, the records you can create appear underneath it. They take a moment: the certificate has to be requested before the records are known.

You will usually be offered more than one record. Create one of them, not all of them. Which one fits depends on where the hostname sits in your zone:

Record	Use it when
CNAME	The hostname is a subdomain, such as api.your-company.com. Usually the one you want.
A / AAAA	The hostname is a zone root, such as your-company.com. DNS does not permit a CNAME there, so this is the only option.

An A record comes with several values. Those are anycast addresses for the same hostname, not alternatives to each other: create one record per value.

Check what your provider published:

dig +short CNAME api.your-company.com
dig +short A your-company.com

What the statuses mean

Status	Meaning
Waiting for DNS	GraphPilot cannot see your record yet. Nothing happens until it appears.
Verifying	GraphPilot can see your record, and the certificate is being issued.
Active	Serving.
Failed	Verification did not succeed; the reason is shown on the hostname, and Retry verification starts it again.
Disabled	Switched off, not serving.

Checks run in the background, so the page updates on its own while a hostname is still settling. A record that was only just created can take a while to become visible everywhere, which is normal and needs nothing from you.

Make it the primary hostname

A new hostname never arrives as the primary one, because it has no certificate yet and promoting it would take the service off the air. Once it is Active, use Set as primary in the hostname’s menu.

Switch off the platform hostname

Once another hostname is active and primary, choose Disable in the platform hostname’s menu and confirm with Switch it off. After that the service answers only on your own domains, so make sure everything that calls it has been moved over first.

The platform hostname cannot be removed, only switched off. To bring it back, choose Enable in its menu. It is set up again, with nothing to do on your side, and answers once it is Active. Disable is unavailable while it is the primary hostname or the only active one, and the menu says which.

Troubleshooting

“Your organization has not verified a domain that covers …” The domain, not the hostname, is what gets verified. Check Settings → Domains in your organization: the entry has to be verified, not pending, and it has to be the hostname itself or something it sits under.

A domain shows as verified in the portal but cannot be selected. Domains verified before the identity provider required proof of control are listed as needing verification again. Verify the domain once more and it becomes selectable.

”… is already attached to a service” Hostnames are unique across all of GraphPilot. If you used this one on another service, remove it there first.

The record was created but the hostname stays on “Waiting for DNS”. Confirm with dig that the record is published, and that it is one of the records the page offered. A CNAME on a zone root is refused by DNS itself and will never appear.

A hostname was removed but still answers. Removal starts a deployment that takes the hostname and its certificate off the edge. It keeps answering until that deployment finishes.

Related

• Edge locations: a custom domain is served from the same network and changes nothing about routing, caching or invalidation.
• Request signing, which your origin should verify whichever hostname the request arrived on.