--- 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/). > **Tip** > > This page carries separate instructions for API v4 and API v3. To find out which apply to your account, refer to [Verify your account migration](/en/documentation/guides/application-security/access-and-compliance/verify-account-migration/). --- ## 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](/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/). - 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 - 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/). - 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 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/). - 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.` --- ## 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](/en/documentation/guides/application-security/access-and-compliance/verify-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. **Console** To list a hostname on a domain in Azion Console: 1. **Open Domains** Access [Azion Console](https://console.azion.com/) > **Domains**. 2. **Start a domain** Select **+ Domain**, or select an existing domain to edit it. 3. **Name the domain** Enter a name. The name identifies the entry on the account and is not a hostname. 4. **Choose the environment** In **Environment Type**, select **Global Edge Network** for production or **Staging Network** for a test environment. 5. **Select the application and the firewall** In **Applications**, select your application. In **Firewall**, select your firewall. 6. **List the hostnames** In **CNAME**, list the hostnames you serve, one per line. 7. **Decide on the Azion address** 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. 8. **Select the certificate** In **Digital Certificate**, select **Azion SAN** or a certificate of your own. 9. **Save the domain** Select **Save**. **API v3** To create the domain with API v3, send a `POST` to `/domains`. The request carries the header `Accept: application/json; version=3`, and `` is the ID of the application the domain serves: ```bash curl --request POST \ --url https://api.azionapi.net/domains \ --header 'Accept: application/json; version=3' \ --header 'Content-Type: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --data '{ "name": "my-domain", "cnames": ["www.example.com"], "cname_access_only": false, "digital_certificate_id": null, "edge_application_id": }' ``` | Key | What it carries | | ------------------------ | ----------------------------------------------------------------------------------- | | `name` | The name of the entry on the account. It is not a hostname | | `cnames` | The hostnames the domain serves | | `cname_access_only` | `false` keeps the Azion address reachable; `true` answers only the listed hostnames | | `digital_certificate_id` | `null` selects the **Azion SAN** certificate | | `edge_application_id` | The ID of the application the domain serves | The response returns the domain as Azion stored it, with its Azion address in `domain_name`: ```json { "results": { "id": 1234567, "name": "my-domain", "cnames": ["www.example.com"], "cname_access_only": false, "digital_certificate_id": null, "edge_application_id": 1234567890, "is_active": true, "domain_name": "xxxxxxxxxx.map.azionedge.net" } } ``` For every field, refer to [Domains](/en/documentation/platform/workloads/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.