Add a custom domain
Serve an app on a hostname you own, or on every name below one with a wildcard, with a certificate obtained for it automatically.
Adding a domain does not require a redeploy: the machine's agent asks for the app's hostnames every
few seconds and starts serving the new one. Replace app-id with the app's id and
example.com with your domain.
Prerequisites
- Permission for
deploy:ManageDomainon the app (to add, re-check and remove a domain).deploy:DescribeAppshows the domains. Withoutdns:GetZonethe panel does not show whether a hosted zone is delegated. - Access to the domain's DNS, unless the domain is inside one of your organization's hosted zones in DNS.
Add the domain
- Open the app, then choose the Domains tab.
- Under Domains and certificates, for Add a domain you own, enter the hostname, for
example
shop.example.com. - Choose Add domain. The domain is listed with its DNS and certificate badges and, unless the platform answers for it, the record to create.
dcloud deploy domains add app-id --domain shop.example.comPOST /deploy/api/apps/3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601/domains
{ "domain": "shop.example.com" }resource "dcloud_app_domain" "shop" {
app_id = dcloud_app.web.id
domain = "shop.example.com"
}The domain is refused when:
- it is not a bare hostname with at least two labels (400,
Domain must be a bare host (no protocol or path)orUse a domain such as app.example.com, or *.example.com for every subdomain); - it is, encloses or sits under the platform's own domain (400,
<domain> is the platform's own domain); - another organization holds it, or a name overlapping it, as a hosted zone or a custom domain
(409,
<domain> is already a custom domain on this platform, held by another organization, or… overlaps …); - it is already attached to an app (409);
- the app is being deleted (409,
The app is being deleted).
Point DNS at the app
When the domain sits inside one of your organization's hosted zones at the moment you add it, there
is nothing to create: the platform writes an ALIAS record (TTL 60) into that zone, and the
Deutsche Cloud nameservers answer with whichever machine currently serves the app. The panel then shows
Answered by your hosted zone, and a Zone delegated badge, or Zone not delegated /
Delegation not confirmed while your registrar does not yet name the platform nameservers. If the
zone has no record answering for the app (the domain was added before the zone existed, or the record
was replaced), the panel asks for an ALIAS onto the app's default host in that zone; removing and
re-adding the domain writes it for you.
Elsewhere, create the record the panel names under Create this record at your DNS provider:
- Below the apex, a
CNAMEonto the app's default host, which keeps answering when the machine changes. - At the apex, which cannot be a
CNAME, anArecord to the machine's address (shown after the first deployment). It has to be updated if the app moves. - For a wildcard, a
CNAMEnamed*.example.comonto the default host.
Beside the record the panel shows what DNS answers right now and what is known about the certificate, each with its explanation, and checks again every 15 seconds while the app has a machine. Re-check checks one domain on demand and records when it last resolved to the app.
| Field | API value | Console badge | Meaning |
|---|---|---|---|
| DNS | ok |
Resolves here | Resolves to the machine, or is a CNAME onto the default host |
| DNS | mismatch |
Points somewhere else | Resolves to another address |
| DNS | missing |
No record | Nothing answered, or the hosted zone answering for it is not delegated |
| DNS | unknown |
Nothing to compare yet | No machine serves the app yet, or the platform answers for the name and the check could not see it |
| Certificate | pending |
Certificate pending | Not issued yet: no machine, DNS not right yet, or the machine has not reported on the name |
| Certificate | active |
Certificate active | A valid certificate is served for the name |
| Certificate | failed |
Certificate failed | The served certificate does not verify, or issuance failed; the cause is shown |
| Certificate | unavailable |
No certificate (plain HTTP) | The platform runs on a local domain and serves plain HTTP |
| Certificate | on-demand |
Certificate per name, on first request | A wildcard: each name is issued on its first request; the names served so far are listed |
For an app behind a load balancer the balancer, not the machine, holds the certificate. A name is added to it once the name resolves to the balancer, at the next deployment or the daily renewal; see Scale an app.
Wildcard domains
*.example.com serves every name exactly one label below example.com (a.example.com, not
a.b.example.com, and not example.com itself: add the apex as its own domain). The machine
obtains a certificate for each name the first time it is requested, which takes a few seconds for
that first visitor. The machine only asks for names its app's domains cover, so pointing an
unrelated name at it gets no certificate. Only one leading *. label is accepted. The panel checks
DNS at a name under the wildcard and lists the names the machine has served certificates for.
Remove a domain
Choose the delete icon beside the domain, then Remove, or run
dcloud deploy domains remove app-id domain-id, with the domain's id from
dcloud deploy domains list app-id. An ALIAS record the platform wrote
into your hosted zone is removed with it; a record at another DNS provider is not touched.
Result
Once DNS points at the app, the machine requests the certificate, usually within a minute, and the
app answers on the domain over HTTPS. dcloud deploy apps routing app-id shows the same
DNS and certificate state as the panel.
Related
- Scale an app, for domains behind a load balancer
POST /deploy/api/apps/{id}/domains·dcloud deploy domains add·dcloud_app_domain