Docs Domains Secondary records

Secondary records

Secondary records, aka backup or failover records, allow more precise behavior when it comes to handling inactive or offline hosts.

Normally, all eligible host records are used for DNS responses. However, there are times when it makes more sense to hide a record until another record becomes ineligible.

Secondary records are most often paired with Monitoring. It’s also possible to use them with the active/inactive state. state can be toggled via both the API and UI.

To use secondary records with monitoring, start by configuring the monitoring at Routing -> Monitors -> Add Monitor.

; Configured monitors:
Name: Primary server
URI : https://192.0.2.11/
Hostname: www.your-domain.com

Name: Backup server
URI : https://192.0.2.22/
Hostname: www.your-domain.com

Then, create the host records at Domains -> your-domain.com -> Add Host, associating them with each monitor and setting the role.

; Configured hosts:
www.your-domain.com  A  192.0.2.11  Monitor=Primary server  Role=Primary
www.your-domain.com  A  192.0.2.22  Monitor=Backup server   Role=Secondary

In this example, as long as 192.0.2.11 remains online, only that record will be served. If it goes offline, then 192.0.2.22 will be served instead.

A couple key notes:

  • Primary and secondary records are automatically associated using the FQDN and record type (www.your-domain.com plus A). No extra configuration is required to associate primary and secondary records.

  • Per the prior point, A and AAAA are processed independently. ALIAS is also valid. As elsewhere, we recommend using A and AAAA or ALIAS, but don’t mix ALIAS with A or AAAA.

  • It’s valid to have 2+ primary and/or 2+ secondary records. As long as at least 1 primary record remains available, secondary records will remain hidden. If all primary records go offline, then all secondary records will be unhidden together.

  • If any records within a primary + secondary set are monitored, then all records need to be monitored.

As noted at the top, it’s also valid to configure primary + secondary records without monitoring at all, instead toggling the active/inactive state of the records.

For example, one could mark the primary record as inactive when putting an app into maintenance mode. The secondary record could be pointed to a separate server with a static “under maintenance” message. When maintenance is finished, simply reactivate the primary record and traffic will return to the primary host.

Interaction with Monitoring’s failsafe

Monitoring has a failsafe mode whereby if all records are offline, it treats everything as online. In the case of all primary and all secondary records being offline, the primary records will be restored and the secondary records will be hidden.

Monitoring’s failsafe only looks at records with monitors. If some records have monitoring and some don’t, the failsafe will behave unexpectedly, most often causing the primary record to stick and the secondary to never be used.