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.
Select an interface. The prerequisites and the steps of each task follow your choice.
Prerequisites
- 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.
To list the domain with the Azion CLI, save a JSON file with the workload ID and the domains list, here as domains.json. The list holds every hostname the workload answers, including any it already lists:
Update the workload with the file:
The command prints the ID of the workload it updated:
To confirm the change, describe the workload:
This excerpt of the output shows the hostname in domains, beside the workload domain:
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.
To close the workload domain with the Azion CLI, save a JSON file with the workload ID and workload_domain_allow_access set to false, here as close.json:
Update the workload with the file:
The command prints the ID of the workload it 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.