--- name: azion-create-an-azion-custom-domain description: >- Give a workload a free azion.app hostname that Azion serves over HTTPS, from Azion Console, the Azion CLI, or the API. --- # Create an Azion custom domain You can give a [workload](/en/documentation/platform/workloads/) a free hostname under `azion.app` from Azion Console, the [Azion CLI](/en/documentation/devtools/cli/), or the API. To serve a domain you own, such as `www.example.com`, refer to [Add a custom domain to a workload](/en/documentation/guides/platform/migration/configure-a-domain/) instead. The Azion custom domain is a hostname you choose, in the form `.azion.app`, such as `my-custom-name.azion.app`. It differs from the workload domain, the `.map.azionedge.net` hostname that Azion generates when it creates the workload. The workload stores the Azion custom domain as one entry of its domains, beside any domain you own. The Azion custom domain is available at no additional cost. --- Choose an interface. Each task below shows the prerequisites and steps for your choice. ## Prerequisites - A workload on the production infrastructure whose deployment names an application. A staging workload takes no Azion custom domain. To create the workload and its deployment, refer to [Workloads quickstart](/en/documentation/platform/workloads/quickstart/). - A name that no other workload holds under `azion.app`. **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, authorized with your account. The commands on this page match Azion CLI 4.23.0. - The workload ID, which `azion create workload` prints as `Created Workload with ID `. **API** - A personal token, sent in the `Authorization` header as `Token [TOKEN VALUE]`. To create one, refer to [Personal tokens](/en/documentation/fundamentals/personal-tokens/). - `curl` or another HTTP client. - The workload ID, which `azion create workload` prints as `Created Workload with ID `. --- ## Add the Azion custom domain to the workload The workload answers on the Azion custom domain once the full hostname is in its domains. You choose only the name: the suffix `.azion.app` is fixed. **Console** In Azion Console, the **Domains** section of the workload form holds the **Custom Domain** switch, described as "You can use an free azion.app domain." The **Create Workload** form carries the same switch and field, so you can also set the name when you create a workload. To add the Azion custom domain to an existing workload: 1. **Open the Workloads page** Access [Azion Console](https://console.azion.com/) > **Workloads**. 2. **Open the workload** Select the production workload. Its edit form opens. 3. **Turn on Custom Domain** In the **Domains** section, turn on **Custom Domain**. The **Azion Custom Domain** field appears. 4. **Enter the name** In **Azion Custom Domain**, enter the name, such as `my-custom-name`. The field appends `.azion.app`. 5. **Save the workload** Select **Save**. Azion Console shows "Your workload has been updated". The workload lists `.azion.app` in its domains. **CLI** To add the Azion custom domain with the Azion CLI, save a JSON file with the workload ID and the `domains` list, here as `azion-app.json`. Keep every domain the workload already lists in the same list: ```json { "id": , "domains": [".azion.app"] } ``` Update the workload with the file: ```bash azion update workload --file azion-app.json ``` The command prints the ID of the updated workload: ```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 lists the Azion custom domain in `domains`, apart from the workload domain: ```json { "domains": [".azion.app"], … "workload_domain": ".map.azionedge.net" } ``` **API** To add the Azion custom domain with the API, send a `PATCH` request to the workload. Keep every domain the workload already lists in the same `domains` list: ```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": [".azion.app"] }' ``` The API accepts the update, and the workload then lists `.azion.app` in `domains`. The API stores the name with the case you send, so `My-Site.azion.app` reads back as `My-Site.azion.app`. The change is refused in four cases, each with its own message: - **A second `azion.app` hostname on the same workload.** A workload holds one, whether the list repeats a name or carries two names: `Duplicated usage of suffix in alternate_domains: 'azion.app'.` - **A name that another workload holds.** An `azion.app` name belongs to one workload and is not shared between accounts or configurations: `The custom hostname is not available.` - **A wildcard name**, such as `*.azion.app`: `The domain does not conform to the format defined in RFC 1035.` - **A staging workload.** The Console turns off the **Custom Domain** switch and makes it unavailable, and the CLI and the API return `Custom hostname is not available in the environment 'Staging Infrastructure'.` For the causes and fixes, refer to [Troubleshoot Workloads](/en/documentation/platform/workloads/troubleshooting/). --- ## Open the Azion custom domain The Azion custom domain needs no DNS record from you and no certificate of yours. With `tls.certificate` set to `null`, the default, the workload serves HTTPS with the Azion SAN certificate, which covers the Azion custom domain and the workload domain. For more information, refer to [How Workloads works](/en/documentation/platform/workloads/how-it-works/). A workload change takes several minutes to reach all of Azion's distributed infrastructure. Until the change arrives, a request to `https://.azion.app` answers `404` with Azion's HTML error page. Requests can receive the old or the new configuration for a while, so repeat a request until the answers agree. Once the change propagates, a request to `https://.azion.app` reaches the application in the workload's deployment and returns its response, such as `200`. --- ## Next steps - [Add a custom domain to a workload](/en/documentation/guides/platform/migration/configure-a-domain.md): Serve the same workload on a domain you own, beside the Azion custom domain. - [Bind a firewall to a workload](/en/documentation/guides/application-security/firewall-and-waf/firewall-protect-your-domain.md): Inspect the requests that reach the Azion custom domain before the application answers them. - [Workload settings](/en/documentation/platform/workloads/settings.md#domains): Look up every rule the domains field follows and the error each one returns. - [Troubleshoot Workloads](/en/documentation/platform/workloads/troubleshooting.md): Find why a hostname is refused or a workload still answers 404.