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.
Last updated 18 November 2026View as Markdown
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,AAAAandCNAMEsets only. A routed set takes a check per variant instead (see Route by weight or location), and anALIASfollows 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:ChangeRecordson the zone. - In the console, also
dns:ListZonesto open Hosted zones (without it the page shows an access-denied notice),dns:GetZoneto open the zone (without it the zone's page is not found), andmonitoring:DescribeChecksto 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
- Open the zone. On the Records tab, choose Add record, or Edit record in the row's actions menu.
- Enter the Name, a Type of
A,AAAAorCNAME, and the primary Values, one per line. - Under Health check, choose the uptime check.
- For Failover values, one per line, enter the values to answer while the check is down.
- Choose Add (or Save).
The table shows the set's values, then "checked by check name; fails over to …".
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.20POST /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"] }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
Did this page help you?