ConfigurationRoutes and path prefixes

Routes and path prefixes

A route sends a hostname, or a path under it, to a deploy. Routes are how a custom domain reaches your application.

Before you start#

  • A verified domain. The hostname must be a domain your organisation has claimed and verified on the Domains page, or a subdomain of it. See Custom domains.
  • A publicly exposed deploy. The deploy needs Publicly expose this deploy (edge ingress) turned on, which requires its build to have a Container port. Traffic is routed to that port.

Any member of the organisation can attach and remove routes.

Attach a route#

  1. Open the deploy's routes

    In Deployments, choose Routes (the link icon) on the deploy. The Routes · name dialog lists existing routes.

  2. Choose the hostname

    Pick the verified domain under Domain, and optionally type a Subdomain such as app. Leave the subdomain empty to route the domain itself.

  3. Optionally add a path prefix

    Enter a Path prefix such as /api to route only that path. Leave it empty (or /) to route the whole host. The dialog previews the result, for example Routes app.example.com/api to this deploy.

  4. Attach it

    Choose Attach route. The dialog confirms Route attached and shows the DNS CNAME record to publish: its Type, Name and Target, each with a copy button.

  5. Publish the CNAME

    Add the record at your DNS provider. Once it resolves, the certificate is issued and the hostname serves HTTPS. See HTTPS and certificates.

DNS record
app.example.com.   CNAME   d0c43d3885064d9a.edge.devlyft.io.

Always copy the target from the dashboard, or from the route's cname_target field in the API. It's a digest of the hostname, so you can't work it out by hand. If the dialog shows DNS target pending…, the deploy isn't publishing edge DNS yet. Reopen Routes shortly.

Path prefixes: several deploys on one hostname#

You can split one hostname across deploys by path prefix, for example a web deploy on / and an API deploy on /api:

app.example.com/ → web (production, same location) app.example.com/api → api (production, same location)
  • One CNAME covers them all. The target is derived from the hostname, not the deploy, so every route on app.example.com uses the same record.
  • Same environment and location. One hostname resolves to one cluster, so all the deploys serving it must share an environment and a location. A route to a deploy elsewhere is rejected when you attach it.
  • Each deploy must stay exposed. A deploy that stops being exposed stops serving its paths. The hostname keeps working for the others.

Remove a route#

In the deploy's Routes dialog, choose Remove next to the route. The hostname stops sending traffic to that deploy. The CNAME target stays the same if you attach that hostname again, to this deploy or another, so you don't need to change DNS.

What isn't supported#

  • Wildcard hostnames (*.example.com) are rejected. Route each hostname you serve.
  • Hostnames outside your verified domains. Claim and verify the domain first.
  • One hostname across locations. Give each location its own hostname. See Locations.