Add a custom domain to a workload
List a domain you own on a workload, point its DNS record at the workload domain, and close the workload domain, from Azion Console, the CLI, or the API.
You can serve a workload on a domain you own from Azion Console, the Azion CLI, or the API. For the free azion.app hostname instead, refer to Create an Azion custom domain.
A custom domain, on this page, is a hostname of a domain you own, such as www.example.com. Every workload already answers on its workload domain, a hostname that Azion generates in the form <id>.map.azionedge.net. Serving your own hostname takes two changes: the workload lists the hostname, and a DNS record points the hostname at the workload domain.
An account that runs on API v3 with Domains lists its hostnames in the CNAME field of each domain instead. For more information, refer to Domains.
Prerequisites
Console
- A workload on the production infrastructure whose deployment names an application. A staging workload takes no custom domain. To create a workload and its deployment, refer to Workloads quickstart.
- A domain your account has permission to use, and access to its DNS records at your DNS provider or in Edge DNS.
- Access to Azion Console. For more information, refer to How to access Azion Console.
List the domain on the workload
A workload answers only the hostnames in its domains, so a DNS record alone does not reach your application. Each entry is one full hostname. A wildcard entry is refused with The domain does not conform to the format defined in RFC 1035.
Console
To list the domain in Azion Console:
Access Azion Console > Workloads.
Select the workload that serves the application. Its edit form opens.
In the Domains section, select Add Domain.
In Subdomain, enter the host part, such as www. In Domain, enter your domain, such as example.com, or select one of your active Edge DNS zones.
Select Save.
Azion Console shows “Your workload has been updated”, and the Domains section lists the hostname.
Two refusals stop the change. A domain your account has no permission for is refused with This account is not allowed to use the following CNAMEs: example.com., which names the domain. A staging workload refuses every custom domain with Custom hostname is not available in the environment 'Staging Infrastructure'. For the causes and fixes, refer to Troubleshoot Workloads.
Point the domain at the workload domain
Requests reach the workload once DNS resolves your hostname to it. Azion Console shows the workload domain in the Workload Domain field of the workload. The CLI and the API return it in workload_domain.
At your DNS provider, create a record for the hostname with these values:
| Field | Value |
|---|---|
| Name | Your hostname, such as www.example.com |
| Type | CNAME |
| Value | The workload domain, such as <id>.map.azionedge.net |
When Edge DNS holds the zone of your domain, create the record there instead. For an apex domain, the record at each kind of provider, and how to check resolution, refer to Point a domain to a workload.
Once resolvers pick up the record and the workload change propagates, requests to your hostname reach the application in the workload’s deployment. A workload change takes several minutes to reach all of Azion’s distributed infrastructure, and requests can receive the old or the new configuration meanwhile. Repeat a request until the answers agree.
HTTPS on your hostname needs a server certificate that covers it. The default Azion SAN certificate covers only the workload domain and the Azion Custom Domain. To get a certificate for your domain, refer to Request a Let’s Encrypt certificate or Upload a digital certificate.
Close the workload domain
With Workload Domain Allow Access on, the default, the workload also answers on its workload domain. Turn it off when the workload must answer only on your hostnames. Do it after your hostnames answer as expected, because a closed workload domain no longer serves your application.
Console
To close the workload domain in Azion Console:
Access Azion Console > Workloads.
Select the workload that lists your hostname. Its edit form opens.
Select Save.
Azion Console shows “Your workload has been updated”.
Once the change propagates, a request to the workload domain answers 404, while your hostnames keep serving. A workload with no hostname in its domains cannot close its workload domain. The change is refused with When the workload hostname access is blocked, the workload requires alternate domains or domains.
List the hostnames on a v3 domain
An account that runs on API v3 has Domains in place of workloads, and lists its hostnames in the CNAME field of the domain. To find out which model your account runs on, refer to Verify your account migration.
The rest of this page holds for a v3 domain as it is written. The DNS record you create points at the address the domain answers on. Closing the Azion address is the same decision under a different field name.
To list a hostname on a domain in Azion Console:
Access Azion Console > Domains.
Select + Domain, or select an existing domain to edit it.
Enter a name. The name identifies the entry on the account and is not a hostname.
In Environment Type, select Global Edge Network for production or Staging Network for a test environment.
In Applications, select your application. In Firewall, select your firewall.
In CNAME, list the hostnames you serve, one per line.
Leave CNAME access only off to keep the xxxxxxxxxx.map.azionedge.net address reachable, or turn it on to answer only the hostnames you listed.
In Digital Certificate, select Azion SAN or a certificate of your own.
Select Save.