Migrate nameservers to Azion

Move the DNS of a domain to Edge DNS, test the zone, delegate the domain to Azion's nameservers, and point its hostnames at a workload.

Last updated

View as Markdown Agent setup

You can migrate the nameservers of a domain to Edge DNS from Azion Console, the Azion CLI, or the Azion API. Afterward, Azion’s nameservers answer every DNS query for the domain, and you manage its records at Azion instead of at your current provider.

The order of the work matters. Resolvers ask Azion only after your registrar delegates the domain, and they get NXDOMAIN for every name the zone does not hold. So you rebuild and test the zone first, and change the registrar last. Edge DNS hosts the zone, and a workload serves your application on the hostnames whose records point at it.

To point one hostname at a workload while your current provider keeps the DNS of the domain, refer to Point a domain to a workload instead.

Select your interface once. The prerequisites and the stages below show only that path.

Prerequisites

  • A domain you control, access to its registrar, and the list of records your current DNS provider serves for it.
  • The Edit Edge DNS permission, which requires View Edge DNS. Refer to Teams permissions.
  • A workload that serves your application. To create one, refer to the Workloads quickstart.
  • dig on your machine, for stages 3 and 6. To install it, refer to Query a zone with dig.

1. Create the zone of the domain

Edge DNS keeps the records of one domain in a zone. Use your domain in place of example.com throughout this guide.

To create the zone with the Azion CLI, run:

azion create dns-zone --name example-zone --domain example.com --active=true

The CLI returns the ID of the zone:

Created DNS zone with ID 1235

Keep the ID. Stage 4 uses it as <zone-id>.

To create the zone with the Azion API, send a POST request with the name and the domain. Replace [TOKEN VALUE] with your personal token:

Shell
01curl -X POST https://api.azion.com/v4/workspace/dns/zones \
02 -H "Authorization: Token [TOKEN VALUE]" \
03 -H "Content-Type: application/json" \
04 -d '{"name":"example-zone","domain":"example.com","active":true}'

The API answers 201 with the zone:

JSON
01{
02 "state": "executed",
03 "data": {
04 "id": 1234,
05 "name": "example-zone",
06 "domain": "example.com",
07 "active": true,
08 "nameservers": ["ns1.aziondns.net", "ns2.aziondns.com", "ns3.aziondns.org"],
09 "product_version": "2.0"
10 }
11}

Keep the id. Stage 5 uses it as <zone-id>, and stage 4 uses the nameservers array.

To create the zone in Azion Console:

Open the Edge DNS page

Access Azion Console > Edge DNS.

Select + Zone
Name the zone

In the General section, enter a Name that identifies the zone in lists, such as example-zone.

Enter the domain

In the Domain Name section, enter the root domain you migrate in Domain Name, such as example.com.

Keep Active turned on

In the Status section, leave Active on.

Select Create

The Console shows Your DNS zone has been created. To complete the setup, ensure the Azion nameservers are configured in your domain provider. and opens the Records tab of the zone. Stage 4 covers the nameservers.

The domain of a zone cannot change, and only one zone in Azion can host a domain. For every zone setting, refer to Create, edit, or delete a zone.

2. Copy the records of the domain

The zone answers only for the records you add to it. Export or list the records at your current DNS provider, then recreate them in Edge DNS before the registrar changes.

To copy the records:

  1. Leave out the NS and SOA records of the root domain. Edge DNS answers both for the zone itself, and the API refuses an NS record at @ with 19021.
  2. Add every other record to the zone with the same name, type, and value. For the steps in each interface, refer to Add, edit, or delete a record.
  3. Enter each name relative to the zone: www for www.example.com, and @ for example.com itself. Edge DNS adds the domain, so a name typed with the domain is served with the domain twice.

The zone now holds every name your domain answers for. For the value format of each record type, refer to Record types.

A CNAME record is refused at @ with 19005. If your current provider points the root domain at another hostname, use an ANAME record, as Point an apex domain with ANAME shows.

3. Test the zone at Azion’s nameservers

Query Azion’s nameserver directly before you touch the registrar. The query skips your resolver’s cache, so it shows what Edge DNS answers for the zone today.

To test a record, query ns1.aziondns.net for one of the names you added:

dig +short @ns1.aziondns.net www.example.com A

The nameserver returns the value of the record:

192.0.2.1

Run the same query for each name and type you copied, and compare each answer with your current provider. Without +short, the output header shows status: NOERROR and the aa flag, which marks an authoritative answer.

The first record of a zone can take a few minutes to be answered. If a query prints nothing, refer to A new record returns NXDOMAIN.

To see the nameservers the zone declares for itself, query its NS set:

dig +short @ns1.aziondns.net example.com NS

The zone lists the three Edge DNS nameservers:

Text
01ns3.aziondns.org.
02ns2.aziondns.com.
03ns1.aziondns.net.

The zone answers as your current provider does. The domain is ready to move.

4. Delegate the domain to Azion’s nameservers

Your registrar tells resolvers which nameservers answer for the domain. Replacing the current nameservers with Azion’s moves every query for the domain to Edge DNS.

Get the three nameservers from the interface you used in stage 1:

On the Zones page of Edge DNS, select Copy Nameserver Values. It copies the three names, joined by semicolons.

Run azion describe dns-zone --zone-id <zone-id>. The output lists the three names under Nameservers:.

Read the nameservers array of the zone, returned in stage 1.

To delegate the domain at your registrar:

  1. Open the nameserver settings of the domain at your registrar.
  2. Replace the current nameservers with all three Edge DNS nameservers: ns1.aziondns.net, ns2.aziondns.com, and ns3.aziondns.org.
  3. Save the change.

The registrar lists the three Edge DNS nameservers for the domain. Stage 6 checks when resolvers follow them.

If your registrar holds a DS record for the domain from your current provider, validating resolvers can reject the answers of Edge DNS. To fix it, refer to Validation fails after turning on DNSSEC.

5. Point the hostnames to the workload

A workload serves your application on the hostnames you add to it. You add each hostname of your domain to the workload, then create a CNAME record in the zone that points the hostname at the Azion domain of the workload.

Workloads replaces Domains. If your account still serves applications through Domains, follow the Domains steps in the Console panel or the API v3 steps in the API panel. For how a workload takes a hostname, refer to Workloads settings and Point a domain to a workload.

To point a hostname at a workload with API v4, first list your workloads:

Shell
01curl -X GET https://api.azion.com/v4/workspace/workloads \
02 -H "Authorization: Token [TOKEN VALUE]"

The response lists each workload with its hostnames in domains and its Azion domain in workload_domain:

JSON
01{
02 "count": 3,
03 "results": [
04 {
05 "id": "<workload-id>",
06 "name": "My workload",
07 "active": true,
08 …
09 "domains": ["xxxxxxx.azion.app"],
10 "workload_domain_allow_access": false,
11 "workload_domain": "xxxxxxxx.map.azionedge.net",
12 "product_version": "1.0"
13 },
14 …
15 ]
16}

Keep the id of the workload and its workload_domain. If domains lists none of your hostnames, send them in a PATCH request. Replace <workload-id> with the id:

Shell
01curl -X PATCH https://api.azion.com/v4/workspace/workloads/<workload-id> \
02 -H "Authorization: Token [TOKEN VALUE]" \
03 -H "Content-Type: application/json" \
04 -d '{"domains":["example.com","*.example.com"]}'

The domains field takes the list of hostnames the workload serves.

To create the CNAME record, send a POST request to the records of the zone. Replace <zone-id> with the id from stage 1:

Shell
01curl -X POST https://api.azion.com/v4/workspace/dns/zones/<zone-id>/records \
02 -H "Authorization: Token [TOKEN VALUE]" \
03 -H "Content-Type: application/json" \
04 -d '{"type":"CNAME","name":"www","rdata":["<your-workload>.map.azionedge.net"],"ttl":20,"description":"www record"}'

The API answers 201 with the record. The name is relative to the zone, rdata holds the workload domain, and ttl sets the time to live in seconds. Repeat the request for each hostname the workload serves.

If your account uses Domains with API v3, list your domains:

Shell
01curl -X GET https://api.azionapi.net/domains \
02 -H "Accept: application/json; version=3" \
03 -H "Authorization: Token [TOKEN VALUE]"

The response lists each domain with its hostnames in cnames and its Azion domain in domain_name:

JSON
01{
02 …
03 "results": [
04 {
05 "id": <domain-id>,
06 "name": "example.com CA1 DC-example.com",
07 "cnames": [],
08 "cname_access_only": true,
09 "digital_certificate_id": <digital-certificate-id>,
10 "edge_application_id": <edge-application-id>,
11 "is_active": true,
12 "domain_name": "xxxxxxxxxx.map.azionedge.net"
13 }
14 ]
15}

Keep the id of the domain and its domain_name. If cnames lists none of your hostnames, send them in a PATCH request. Replace <domain-id> with the id:

Shell
01curl -X PATCH https://api.azionapi.net/domains/<domain-id> \
02 -H "Accept: application/json; version=3" \
03 -H "Authorization: Token [TOKEN VALUE]" \
04 -H "Content-Type: application/json" \
05 -d '{"cnames":["example.com","*.example.com"]}'

To create the CNAME record with API v3, send a POST request to the records of the zone. Replace <zone-id> with the id from stage 1:

Shell
01curl -X POST https://api.azionapi.net/intelligent_dns/<zone-id>/records \
02 -H "Accept: application/json; version=3" \
03 -H "Authorization: Token [TOKEN VALUE]" \
04 -H "Content-Type: application/json" \
05 -d '{"record_type":"CNAME","entry":"www","answers_list":["xxxxxxxxxx.map.azionedge.net"],"description":"www record","ttl":20}'

In API v3, record_type is the type, entry is the name relative to the zone, and answers_list holds the values. The response returns the record:

JSON
01{
02 "results": {
03 "answers_list": ["xxxxxxxxxx.map.azionedge.net"],
04 "zone_id": <zone-id>,
05 "record_type": "CNAME",
06 "ttl": 20,
07 "policy": "simple",
08 "entry": "www",
09 "id": <record-id>,
10 "description": "www record"
11 }
12}

To point a hostname at a workload in Azion Console:

Open the Workloads page

Access Azion Console > Workloads.

Open the workload

Select the workload that serves your application.

Add your hostnames

In the Subdomain and Domain fields, add the hostnames of your domain. If the workload already lists them, keep them at hand.

Open the Edge DNS page

Access Azion Console > Edge DNS.

Open the records of the zone

On the Zones page, select the zone, then select the Records tab.

Select + Record
Enter the hostname

In Name, enter the hostname relative to the zone, such as www. Enter * for every name the zone does not list. The Console adds the domain for you.

Select the CNAME type

In Record Type, select CNAME - Canonical name.

Enter the Azion domain

In Value, enter the Azion domain of the workload, such as <your-workload>.map.azionedge.net.

(Optional) Set the TTL and the policy

Change TTL (seconds) and Policy Type if your record needs other values.

Select Save

The Console shows Edge DNS Record has been created. Repeat the record steps for each hostname the workload serves.

If your account uses Domains, add the hostnames there instead of on a workload:

Open the Domains page

Access Azion Console > Domains.

Open the domain

Select the domain that serves your application.

Add your hostnames

In the CNAME field, add the hostnames of your domain. If the domain already lists them, keep them at hand.

Then create each CNAME record in Edge DNS with the steps above, and enter the Azion domain of the domain in Value.

A record named * answers every name the zone does not list, so one record can send both www and blog to the workload. For the names a wildcard matches, refer to Match subdomains with a wildcard record.

A record whose name nobody queried before it existed answers within seconds. A change to an existing record can take a few minutes to reach every nameserver. For the reason, refer to How Edge DNS works.

6. Check the domain through a public resolver

A public resolver reaches Azion only through the delegation your registrar publishes. Querying one shows whether the internet already follows the change from stage 4.

To query a public resolver, run:

dig @8.8.8.8 www.example.com A

While the resolver does not follow the delegation yet, the header can read NXDOMAIN with no answer:

Text
01;; ->>HEADER<<- opcode: QUERY, status: NXDOMAIN, id: 19090
02;; flags: qr rd ra; QUERY: 1, ANSWER: 0, AUTHORITY: 1, ADDITIONAL: 1
03…

The resolver may also return the records of your previous provider. Once it follows the delegation, it returns the same value that ns1.aziondns.net returned in stage 3. If it does not, refer to Public resolvers return NXDOMAIN while Azion’s nameservers answer.

Edge DNS now answers for your domain. From here on, you add and change its records in Edge DNS, not at your previous provider.

Next steps

Point an apex domain with ANAMESend the root domain itself to a workload.Turn on DNSSEC for a zoneSign the migrated zone and give the DS record to your registrar.Troubleshoot Edge DNSFix a zone or record that does not answer as expected.Install Massive RedirectRedirect many addresses at once when a domain migration changes them.