# Fail a name over with a health check

Attach an uptime check to an A, AAAA or CNAME record set, so the name answers failover values while its target is down.

Replace _zone-id_ with the id of your hosted zone, and _check-id_ with the id of an uptime check
that watches the primary target.

## How it behaves

- While the uptime check is down, the nameservers answer the set's failover values; when it is up
  again, the set's own values. A paused check, or one in any other state, is not down.
- With no failover values, the set's own values are answered whatever the check says.
- A health-checked set is served with a TTL of at most 60 seconds, so resolvers see the switch
  soon. The stored TTL is not changed.
- Health checks go on `A`, `AAAA` and `CNAME` sets only. A routed set takes a check per variant
  instead (see [Route by weight or location](route-by-weight-or-location.md)), and an `ALIAS`
  follows its target.
- Deleting the uptime check removes it from the set; the set's own values are then always answered.

## Prerequisites

- An uptime check for the primary target, created under **Monitoring** (`monitoring:CreateCheck`).
- Permission for `dns:ChangeRecords` on the zone.
- In the console, also `dns:ListZones` to open **Hosted zones** (without it the page shows an
  access-denied notice), `dns:GetZone` to open the zone (without it the zone's page is not found),
  and `monitoring:DescribeChecks` to choose a check. Without it, or without any check, the dialog
  says "Create an uptime check under Monitoring to fail this name over when its target goes down."

## Attach the health check

**Console**
1. Open the zone. On the **Records** tab, choose **Add record**, or **Edit record** in the row's
   actions menu.
2. Enter the **Name**, a **Type** of `A`, `AAAA` or `CNAME`, and the primary **Values, one per
   line**.
3. Under **Health check**, choose the uptime check.
4. For **Failover values, one per line**, enter the values to answer while the check is down.
5. Choose **Add** (or **Save**).

The table shows the set's values, then "checked by _check name_; fails over to …".

**CLI**
```sh
dcloud dns records set zone-id --name www --type A --values 192.0.2.10 \
  --health-check-id check-id --failover-values 198.51.100.20
```

**API**
```http
POST /dns/api/zones/zone-id/records
{ "name": "www", "type": "A", "values": ["192.0.2.10"],
  "healthCheckId": "0b6f4a8e-3c2d-4e1f-9a7b-5c6d7e8f9a0b", "failoverValues": ["198.51.100.20"] }
```

**Terraform**
```hcl
resource "dcloud_dns_record" "www" {
  zone_id         = dcloud_dns_zone.main.id
  name            = "www"
  type            = "A"
  values          = ["192.0.2.10"]
  health_check_id = "check-id"
  failover_values = ["198.51.100.20"]
}
```

To remove the check, choose **None (always answer the values above)** under **Health check** and
save, or in the API send `"healthCheckId": null` with `"failoverValues": []`.

## When the record is refused

All with `400`:

- "Only A, AAAA and CNAME records can have a health check".
- "Uptime check not found" when the check is not one of your organization's.
- "Failover values need a health check" when you send failover values without a check, including
  an edit that removes the check but keeps the stored failover values.
- "Failover: 198.51.100.300 is not an IPv4 address" for a failover value in the wrong format.
- "A CNAME has exactly one failover value".
- "A routed set takes health checks per variant, not a failover health check".

## Related

- [Route by weight or location](route-by-weight-or-location.md)
- `dns.records.set` · `dcloud dns records set` · `dcloud_dns_record`
