Custom domains and HTTPS

Everything on this page is under Configuration → Networking & Security. Changes here affect routing and the certificate only; the app's instances keep running.

The generated hostname

A new app without a domain of its own gets a hostname under apps.example.com: <prefix>-<resource group>-<app>.apps.example.com, where <prefix> is the first nine characters of the boundary's slug. A name that would be longer than 63 characters before the first dot is shortened and ends in a short hash. The Overview shows it as the app's URL. It stays the same when you change the app, until you give it a domain of your own.

Use your own domain

The Custom Domain Name field holds the app's primary hostname — the generated one until you change it.

1. Create the DNS record for your domain first — see DNS records.
2. Enter the domain, for example app.example.com: lowercase, without https://, a port or a path.
3. Choose Save.

Your domain becomes the primary hostname and replaces the generated one, which the app no longer answers on. To go back to a generated hostname, empty the field and save.

DNS records

You create the records at your DNS provider:

Your domain	Record
A subdomain, such as app.example.com	A CNAME to the app's generated hostname. Every name under apps.example.com leads to the platform, so the record keeps working after your domain has replaced the generated one.
An apex domain, such as example.com	An A record to the platform's public IP address — ask your platform administrator for it. An apex cannot have a CNAME.
A name under apps.example.com	None

While you enter a domain, the section lists the records under DNS records to create. Read them before you save: the list takes the app's current primary hostname as the CNAME target, and it treats only a two-label name such as example.com as an apex. For an apex under a longer suffix, such as example.co.uk, it suggests a CNAME; create the A record instead.

Additional domains

Under Additional domains, enter a domain and choose Add. Each domain is either:

• Serve app — the app answers on it as well as on the primary hostname;
• Redirect — a permanent redirect to the primary hostname that keeps the path and the query.

Remove a domain with the delete button on its row, and choose Save. Every additional domain needs its own DNS record, like the primary.

www and the apex

With Redirect www to apex on — the default — every apex domain the app serves also answers on its www. name, which redirects permanently to the apex. This applies to the primary hostname and to domains set to Serve app, never to the generated hostname. The www. names are worked out when you save, and need DNS records too. Turn the switch off to leave them out.

The platform knows an apex from the public suffix list, so example.co.uk counts as an apex and app.example.com does not.

Hostnames already in use

A hostname can belong to only one resource in the cluster at a time. The platform checks every name you save — the primary hostname, additional domains and www. names — against the apps and their slots, static web apps, container instances and function namespaces of every boundary, and refuses one that is taken: Hostname '<name>' is already in use by another resource.

Important

The check is first come, first served; it does not verify that you own the domain. A name an app stops using — for example its generated hostname once it has a domain of its own — is free for any other resource to take, and links to that name then lead there.

HTTPS

• Let's Encrypt SSL — on by default. The platform requests one certificate that covers the primary hostname, the additional domains and the www. names, and renews it. Your platform administrator decides which certificate authority issues it. The certificate is issued for all of the names together, so it is not issued while one of them fails validation — for example because its DNS record is missing.
• Let's Encrypt SSL off — the app has no certificate of its own. HTTPS is answered with a self-signed certificate, which browsers warn about, and the Overview shows TLS as Self-signed (browsers will warn).
• HTTP Only — the app is meant to be reached over plain HTTP, and gets no certificate. It turns Let's Encrypt SSL off.

Caution

With Let's Encrypt SSL off, the platform does not send visitors to HTTPS. Depending on the platform's ingress controller, the app then also answers plain, unencrypted HTTP on its hostnames, just as with HTTP Only. Keep Let's Encrypt SSL on for an app that handles sign-ins or other confidential data.

Certificate status

With Let's Encrypt SSL on, the section shows the certificate's state next to Certificate and refreshes it every 30 seconds:

State	Meaning
Issued — expires <date>	The certificate is in place
Issuing	The certificate authority is working on it
Pending	Requested, with no result yet
Failed	It could not be issued
NotFound	The certificate has not been created yet
Unknown	Its state could not be read

Under the state is the message of the certificate manager, word for word — it names what failed, such as a name that did not validate. Fix the cause, for example the DNS record; the platform keeps trying.

Slots

A slot has a generated hostname of its own, derived from the app's, and cannot have a domain of its own. It uses the app's HTTPS settings as they were when the slot was created — see Deployment slots.