feat(route53): add failover routing support to RecordSet L2 construct

[0xdsqr]

Describe the feature

Add support for failover routing policies to the Route 53 RecordSet L2 construct.

Currently, only the L1 CfnRecordSet exposes the Failover property, which allows users to configure PRIMARY and SECONDARY record sets for DNS failover.
The L2 construct (RecordSet and its subclasses like ARecord) does not expose this functionality, requiring users to use low-level overrides such as:

const record = new route53.ARecord(this, 'ARecord', {
  zone,
  target: route53.RecordTarget.fromIpAddresses('1.2.3.4'),
});
const cfnRecord = record.node.defaultChild as route53.CfnRecordSet;
cfnRecord.addPropertyOverride('Failover', 'PRIMARY');
cfnRecord.addPropertyOverride('HealthCheckId', myHealthCheck.healthCheckId);

This feature would provide first-class failover support in the L2 constructs by adding a failover property to RecordSetProps:

new route53.ARecord(this, 'PrimaryFailover', {
  zone,
  target: route53.RecordTarget.fromIpAddresses('1.2.3.4'),
  healthCheck: myHealthCheck,
  failover: route53.Failover.PRIMARY,
});

Use Case

This feature enables developers to define Route 53 DNS failover at the L2 construct level, without resorting to low-level CloudFormation overrides.

Today, the Route 53 RecordSet L2 construct only exposes routing policies such as weighted, latency, and geoLocation.
By adding native failover support, developers can configure active–passive and disaster recovery routing patterns directly in CDK — without using weights as a workaround for availability control.

Proposed Solution

Add a new optional property failover?: 'PRIMARY' | 'SECONDARY' to the RecordSetProps and RecordSetOptions interfaces, allowing developers to define failover routing policies directly at the L2 level.

When specified, the CDK will automatically pass the value through to the underlying CfnRecordSet.Failover property during synthesis.

The construct should also include built-in validation and best-practice guidance:

• Prevent combining failover with other routing policies such as weight, geoLocation, or multiValueAnswer.
• Warn when a PRIMARY record is created without a healthCheck.
• For alias records, warn when EvaluateTargetHealth is not set to true, since this is required for failover alias behavior.
• Automatically generate a deterministic SetIdentifier prefix (e.g., FAILOVER_PRIMARY_ID_ / FAILOVER_SECONDARY_ID_) when omitted.

Example usage:

new route53.ARecord(this, 'PrimaryFailover', {
  zone,
  target: route53.RecordTarget.fromIpAddresses('1.2.3.4'),
  healthCheck: myHealthCheck,
  failover: route53.Failover.PRIMARY,
});

new route53.ARecord(this, 'SecondaryFailover', {
  zone,
  target: route53.RecordTarget.fromIpAddresses('5.6.7.8'),
  failover: route53.Failover.SECONDARY,
});

This approach provides parity with the L1 CfnRecordSet, while improving developer experience and safety through higher-level validation and type safety.

Other Information

No response

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

AWS CDK Library version (aws-cdk-lib)

2.214

AWS CDK CLI version

2.1028

Environment details (OS name and version, etc.)

nixos

[pahud]

Hi @0xdsqr,

Thank you for this well-structured feature request and the accompanying PR #35909! This is a valuable addition to the Route53 L2 constructs.

[0xdsqr]

Thanks @pahud! Everything should be ready for maintainer review now, I’ve run the integration tests and generated the blueprint. It looks like the CI failure might require a maintainer to re-run it.

cc @harshawsharma