--- name: azion-add-a-custom-domain-to-a-workload description: >- 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. --- # Add a custom domain to a workload You can serve a [workload](/en/documentation/platform/workloads/) on a domain you own from Azion Console, the [Azion CLI](/en/documentation/devtools/cli/), or the API. For the free `azion.app` hostname instead, refer to [Create an Azion custom domain](/en/documentation/guides/application-development/getting-started/create-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 `.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](/en/documentation/platform/workloads/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](/en/documentation/platform/workloads/quickstart/). - A domain your account has permission to use, and access to its DNS records at your DNS provider or in [Edge DNS](/en/documentation/platform/edge-dns/). **Console** - Access to Azion Console. For more information, refer to [How to access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/). **CLI** - The [Azion CLI](/en/documentation/devtools/cli/), authorized with your account. This page matches Azion CLI 4.23.0. - The workload ID. `azion create workload` prints it as `Created Workload with ID `. **API** - A personal token for the `Authorization` header, in the form `Token [TOKEN VALUE]`. To create a token, refer to [Personal tokens](/en/documentation/fundamentals/personal-tokens/). - `curl` or another HTTP client. - The workload ID. `azion create workload` prints it as `Created Workload with ID `. --- ## 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: 1. **Open the Workloads page** Access [Azion Console](https://console.azion.com/) > **Workloads**. 2. **Open the workload** Select the workload that serves the application. Its edit form opens. 3. **Add a domain row** In the **Domains** section, select **Add Domain**. 4. **Enter the hostname** 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. 5. **Save the workload** Select **Save**. Azion Console shows "Your workload has been updated", and the **Domains** section lists the hostname. **CLI** 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: ```json { "id": , "domains": [""] } ``` Update the workload with the file: ```bash azion update workload --file domains.json ``` The command prints the ID of the workload it updated: ```text Updated Workload with ID ``` To confirm the change, describe the workload: ```bash azion describe workload --workload-id --format json ``` This excerpt of the output shows the hostname in `domains`, beside the workload domain: ```json { "domains": [""], … "workload_domain": ".map.azionedge.net", "workload_domain_allow_access": true } ``` **API** To list the domain with the API, send a `PATCH` request to the workload. The `domains` list holds every hostname the workload answers, including any it already lists: ```bash curl --request PATCH \ --url https://api.azion.com/v4/workspace/workloads/ \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "domains": [""] }' ``` The API accepts the update, and the workload then lists the hostname in `domains`. 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](/en/documentation/platform/workloads/troubleshooting/). --- ## 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 `.map.azionedge.net` | When [Edge DNS](/en/documentation/platform/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](/en/documentation/guides/platform/migration/point-domain-to-azion/). 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](/en/documentation/guides/application-security/tls-and-certificates/how-to-generate-a-lets-encrypt-certificate/) or [Upload a digital certificate](/en/documentation/guides/application-security/tls-and-certificates/digital-certificates/). --- ## 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: 1. **Open the Workloads page** Access [Azion Console](https://console.azion.com/) > **Workloads**. 2. **Open the workload** Select the workload that lists your hostname. Its edit form opens. 3. **Turn off Workload Domain Allow Access** 4. **Save the workload** Select **Save**. Azion Console shows "Your workload has been updated". **CLI** 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`: ```json { "id": , "workload_domain_allow_access": false } ``` Update the workload with the file: ```bash azion update workload --file close.json ``` The command prints the ID of the workload it updated: ```text Updated Workload with ID ``` **API** To close the workload domain with the API, send a `PATCH` request to the workload with `workload_domain_allow_access` set to `false`: ```bash curl --request PATCH \ --url https://api.azion.com/v4/workspace/workloads/ \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "workload_domain_allow_access": false }' ``` The API accepts the update. 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.` --- ## Next steps - [Point a domain to a workload](/en/documentation/guides/platform/migration/point-domain-to-azion.md): Create the DNS record for an apex domain or at your provider, and check that it resolves. - [Request a Let's Encrypt certificate](/en/documentation/guides/application-security/tls-and-certificates/how-to-generate-a-lets-encrypt-certificate.md): Serve HTTPS on your hostname with a certificate that Azion requests and renews. - [Bind a firewall to a workload](/en/documentation/guides/application-security/firewall-and-waf/firewall-protect-your-domain.md): Inspect the requests that reach your hostname with a firewall in the workload's deployment. - [Troubleshoot Workloads](/en/documentation/platform/workloads/troubleshooting.md): Find why a domain is refused, answers 404, or fails the TLS handshake.