Create an Azion custom domain

Give a workload a free azion.app hostname that Azion serves over HTTPS, from Azion Console, the Azion CLI, or the API.

Last updated

View as Markdown Agent setup

You can give a workload a free hostname under azion.app from Azion Console, the Azion CLI, or the API. To serve a domain you own, such as www.example.com, refer to Add a custom domain to a workload instead.

The Azion custom domain is a hostname you choose, in the form <your-name>.azion.app, such as my-custom-name.azion.app. It differs from the workload domain, the <id>.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.
  • A name that no other workload holds under azion.app.
  • 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 <workload-id>.
  • A personal token, sent in the Authorization header as Token [TOKEN VALUE]. To create one, refer to Personal tokens.
  • curl or another HTTP client.
  • The workload ID, which azion create workload prints as Created Workload with ID <workload-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.

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
01{
02 "id": <workload-id>,
03 "domains": ["<your-name>.azion.app"]
04}

Update the workload with the file:

azion update workload --file azion-app.json

The command prints the ID of the updated workload:

Updated Workload with ID <workload-id>

To confirm the change, describe the workload:

azion describe workload --workload-id <workload-id> --format json

This excerpt of the output lists the Azion custom domain in domains, apart from the workload domain:

JSON
01{
02 "domains": ["<your-name>.azion.app"],
03 …
04 "workload_domain": "<id>.map.azionedge.net"
05}

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:

Shell
01curl --request PATCH \
02 --url https://api.azion.com/v4/workspace/workloads/<workload-id> \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "domains": ["<your-name>.azion.app"]
08}

The API accepts the update, and the workload then lists <your-name>.azion.app in domains.

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:

Open the Workloads page

Access Azion Console > Workloads.

Open the workload

Select the production workload. Its edit form opens.

Turn on Custom Domain

In the Domains section, turn on Custom Domain. The Azion Custom Domain field appears.

Enter the name

In Azion Custom Domain, enter the name, such as my-custom-name. The field appends .azion.app.

Save the workload

Select Save.

Azion Console shows “Your workload has been updated”. The workload lists <your-name>.azion.app in its 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.

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.

A workload change takes several minutes to reach all of Azion’s distributed infrastructure. Until the change arrives, a request to https://<your-name>.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://<your-name>.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 workloadServe the same workload on a domain you own, beside the Azion custom domain.Bind a firewall to a workloadInspect the requests that reach the Azion custom domain before the application answers them.Workload settingsLook up every rule the domains field follows and the error each one returns.Troubleshoot WorkloadsFind why a hostname is refused or a workload still answers 404.