# Route by weight or location

Let one record set answer from several variants, chosen per query by weight or by the client's country or continent.

Replace _zone-id_ with the id of your hosted zone. Routing works on `A`, `AAAA`, `CNAME`, `MX`, `TXT`
and `SRV` sets.

## How it behaves

**Weighted:** each answer is one variant, picked at random in proportion to its weight (0 to 255).
A variant with weight 0 is not answered while another has a weight above 0; when every weight is 0,
the variants are answered equally often. Use it for a canary or a blue/green switch.

**Geolocation:** the variant for the client's country, otherwise the variant for its continent
(`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`), otherwise the set's own `values`, the default. The
client's location comes from the EDNS Client Subnet its resolver sends, or else from the
resolver's own address; a resolver that sends no client subnet is located where it is itself. The
answer says which subnet it was made for, so resolvers cache it per subnet.

**Health checks:** any variant may name an uptime check (`healthCheckId`). While the check is down,
that variant is not answered; when every variant's check is down, all variants are answered. A set
with variant checks is served with a TTL of at most 60 seconds. A routed set cannot also have a
failover health check of its own.

Signed zones sign whichever variant is answered.

## Prerequisites

- Permission for `dns:ChangeRecords` on the zone.
- For variant health checks, uptime checks of your organization.

## Create a routed set

**Console:** not available. The console shows a routed set's variants but cannot create or change them; editing a routed set there keeps its routing.

**CLI**
```sh
dcloud dns records set zone-id --name www --type A --ttl 60 \
  --routing '{"policy":"weighted","variants":[{"id":"blue","weight":9,"values":["192.0.2.10"]},{"id":"green","weight":1,"values":["192.0.2.20"]}]}'
```

**API**
A weighted set that sends one answer in ten to `green`:

```http
POST /dns/api/zones/zone-id/records
{ "name": "www", "type": "A", "ttl": 60,
  "routing": { "policy": "weighted", "variants": [
    { "id": "blue", "weight": 9, "values": ["192.0.2.10"] },
    { "id": "green", "weight": 1, "values": ["192.0.2.20"] } ] } }
```

A geolocation set with a default for everyone else:

```http
POST /dns/api/zones/zone-id/records
{ "name": "api", "type": "CNAME", "values": ["eu.example.net"],
  "routing": { "policy": "geo", "variants": [
    { "id": "de", "country": "DE", "values": ["de.example.net"] },
    { "id": "us", "continent": "NA", "values": ["us.example.net"] } ] } }
```

Without `values`, the set's values are those of the first variant.

**Terraform**
```hcl
resource "dcloud_dns_record" "www" {
  zone_id = dcloud_dns_zone.main.id
  name    = "www"
  type    = "A"
  ttl     = 60
  routing = jsonencode({
    policy = "weighted"
    variants = [
      { id = "blue", weight = 9, values = ["192.0.2.10"] },
      { id = "green", weight = 1, values = ["192.0.2.20"] },
    ]
  })
}
```

To change the routing, send a new `routing` in an edit (`PUT …/records/{recordId}`); to remove it,
send `"routing": null`.

## Rules

- A weighted set has 1 to 20 variants, a geolocation set 1 to 50.
- Each variant has an `id` of 1 to 64 characters, unique in the set, and 1 to 100 values.
- A geolocation variant names exactly one of `country` (two letters, such as `DE`) or `continent`,
  and no two variants name the same place.

Refusals are `400`, for example "Only … records can be routed" for another type, "Two
variants are called "blue"", "Variant "de" names exactly one of a country or a continent", "Two
variants are for DE", "Variant "de": a CNAME has exactly one value", "Variant "blue": uptime check
not found", "A routed set takes health checks per variant, not a failover health check" and "An
ALIAS follows its target and cannot be routed".

Geolocation uses IP to Country Lite by [DB-IP](https://db-ip.com), licensed under
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

## Related

- [Fail a name over with a health check](fail-over-with-a-health-check.md)
- [Troubleshooting](troubleshooting.md)
- `dns.records.set` · `dcloud dns records set` · `dcloud_dns_record`
