Weight records to balance traffic

Spread the answers for one name across several addresses with weighted records in Edge DNS, from Azion Console, the Azion CLI, or the API.

Last updated

View as Markdown Agent setup

You can weight records to balance traffic in Edge DNS from Azion Console, the Azion CLI, or the Azion API. Several records share one name and type, and each answer carries the value of one of them, chosen in proportion to its weight. To add a record that answers with all of its values at once, refer to Add, edit, or delete a record instead.

Select your interface once. The prerequisites and every task below show only that path.

Prerequisites

  • The Azion CLI installed and authorized.
  • The ID of the zone. azion list dns-zone prints it in the ID column.
  • A personal token and curl.
  • The id of the zone. A GET request to https://api.azion.com/v4/workspace/dns/zones returns each zone with its id.
  • For every endpoint and field of the API, refer to the Azion API reference.

Add the weighted records

This example adds three A records on the name lb, one per address, with weights 50, 20, and 30. Over many answers, 192.0.2.21 carries about half of them, 192.0.2.22 a fifth, and 192.0.2.23 the rest. Replace the addresses with your own, and example.com with your domain.

Each record uses a TTL of 20 seconds, so resolvers choose again sooner. A short TTL also makes resolvers ask more often, and every query counts toward your plan’s included usage.

To add the three records with the Azion CLI, run one command per record. Replace <zone-id> with the ID of your zone:

Shell
01azion create dns-record --zone-id <zone-id> --name lb --type A --rdata 192.0.2.21 --ttl 20 --policy weighted --weight 50 --description "origin weight 50"
02azion create dns-record --zone-id <zone-id> --name lb --type A --rdata 192.0.2.22 --ttl 20 --policy weighted --weight 20 --description "origin weight 20"
03azion create dns-record --zone-id <zone-id> --name lb --type A --rdata 192.0.2.23 --ttl 20 --policy weighted --weight 30 --description "origin weight 30"

Each command prints the ID of its record:

Created DNS record with ID 100780

The CLI uses --weight and --description only when --policy is weighted. Never include the domain in --name: Edge DNS adds it.

To check the records, list the records of the zone:

azion list dns-record --zone-id <zone-id>

The list shows the three records on lb, each with its own ID:

Text
01ID NAME TYPE TTL RDATA
02…
03100188 lb A 20 192.0.2.21
04100189 lb A 20 192.0.2.22
05100190 lb A 20 192.0.2.23
06…

The zone holds the three weighted records. Record their IDs: a later change to a weight uses them.

To add the first record with the Azion API, send a POST request to the zone’s records endpoint. Replace <zone-id> with the id of your zone and [TOKEN VALUE] with your personal token:

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 '{"name":"lb","type":"A","rdata":["192.0.2.21"],"ttl":20,"policy":"weighted","weight":50,"description":"origin weight 50"}'

A 201 returns the record:

JSON
01{
02 "state": "executed",
03 "data": {
04 "id": 100188,
05 "description": "origin weight 50",
06 "name": "lb",
07 "ttl": 20,
08 "type": "A",
09 "rdata": ["192.0.2.21"],
10 "policy": "weighted",
11 "weight": 50
12 }
13}

Send the same request twice more, with the same name, type, ttl, and policy. Change only the value, the weight, and the description:

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 '{"name":"lb","type":"A","rdata":["192.0.2.22"],"ttl":20,"policy":"weighted","weight":20,"description":"origin weight 20"}'
05
06curl -X POST https://api.azion.com/v4/workspace/dns/zones/<zone-id>/records \
07 -H "Authorization: Token [TOKEN VALUE]" \
08 -H "Content-Type: application/json" \
09 -d '{"name":"lb","type":"A","rdata":["192.0.2.23"],"ttl":20,"policy":"weighted","weight":30,"description":"origin weight 30"}'

Each request returns 201 with its record. The zone holds three weighted records on lb. Record each id: a later change to a weight uses it. A record sent without weight gets 255.

To add the first record in Azion Console:

Open the Edge DNS page

Access Azion Console > Edge DNS.

Open the zone

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

Select + Record

The Create Record drawer opens.

Enter the record name

In Name, enter lb. The Console shows your domain after the field and adds it for you, so never type the domain.

Keep the A record type

Keep Record Type set to A - IPv4 Address.

Set the TTL

In TTL (seconds), enter 20.

Enter the value

In Value, enter 192.0.2.21.

Select the weighted policy

In the Policy section, set Policy Type to Weighted.

Set the weight

In Weight, enter 50. The Console pre-fills 100.

(Optional) Describe the record

In Description, enter up to 45 characters that tell this record apart from the others on lb, such as origin weight 50.

Select Save

The Console shows Edge DNS Record has been created, and the record appears in the Records table with weighted in the Policy column.

Repeat the steps for the other two records. Keep Name lb, Record Type A, and the TTL, and change only the value and the weight: 192.0.2.22 with weight 20, then 192.0.2.23 with weight 30. The Records table then lists three lb rows.

The weighted policy works on A, AAAA, CNAME, ANAME, and MX records. A TXT or NS record with policy set to weighted is refused with 19017. For every field and its bounds, refer to Zones and records.

Check the weighted answers

Query Azion’s nameserver directly, without your resolver’s cache, to see which address it answers.

To query ns1.aziondns.net for the name, replace example.com with your domain:

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

The nameserver returns one address, the value of the record it chose:

192.0.2.21

Each answer carries one address, never the three. Run the query again right away and the same address returns: the nameserver answers from a cache that counts the record’s TTL down. Run it again after each 20-second TTL, over several minutes, and the other addresses appear. Over many answers, each address answers in proportion to its weight. For how the nameserver chooses, refer to How Edge DNS works.

A new 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 details, refer to Caching and propagation.

Take an address out of rotation

A record with weight 0 stays in the zone and is never answered. Set a weight of 0 to stop answers for an address without deleting its record, and restore the weight to bring it back. Before you delete a weighted record, set its weight to 0 first, as Best practices for Edge DNS explains.

To set a record’s weight to 0 with the Azion CLI, replace <zone-id> and <record-id> with the IDs of the zone and the record:

azion update dns-record --zone-id <zone-id> --record-id <record-id> --weight 0

The command confirms the update:

DNS record 100189 was updated

The record keeps its weighted policy, and its weight is 0. To check it, run azion describe dns-record --zone-id <zone-id> --record-id <record-id>, which prints Policy: weighted and Weight: 0.

To set a record’s weight to 0 with the Azion API, send a PATCH request with weight set to 0. Replace <zone-id> and <record-id> with the id of the zone and of the record:

Shell
01curl -X PATCH https://api.azion.com/v4/workspace/dns/zones/<zone-id>/records/<record-id> \
02 -H "Authorization: Token [TOKEN VALUE]" \
03 -H "Content-Type: application/json" \
04 -d '{"weight":0}'

A 200 returns the record with weight 0:

JSON
01{
02 "state": "executed",
03 "data": {
04 "id": 100190,
05 "description": "origin weight 30",
06 "name": "lb",
07 "ttl": 20,
08 "type": "A",
09 "rdata": ["192.0.2.23"],
10 "policy": "weighted",
11 "weight": 0
12 }
13}

A PATCH changes only the fields you send, so the record keeps its value and its policy.

To set a record’s weight to 0 in Azion Console:

Open the Edge DNS page

Access Azion Console > Edge DNS.

Open the zone

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

Open the record

Select the row of the record. The Edit Record drawer opens.

Set the weight to 0

In Weight, enter 0.

Select Save

The Console shows Edge DNS Record has been updated, and the Weight column of the row reads 0.

Resolvers that cached the address keep it until its TTL expires, and the change can take a few minutes to reach every nameserver. After that, the other records carry every answer for the name.

Next steps

How Edge DNS worksHow a weighted answer is chosen and cached.Zones and recordsEvery record field, its bounds, and its default.Add, edit, or delete a recordChange or remove the records of a zone.Troubleshoot Edge DNSFix a weighted record that returns one address.