Amazon Route53 Construct Library

To add a public hosted zone:

AWSCDK::Route53::PublicHostedZone.new(self, "HostedZone", {
    zone_name: "fully.qualified.domain.com",
})

To add a private hosted zone, use PrivateHostedZone. Note that enable_dns_hostnames and enable_dns_support must have been enabled for the VPC you're configuring for private hosted zones.

vpc = nil # AWSCDK::EC2::VPC


zone = AWSCDK::Route53::PrivateHostedZone.new(self, "HostedZone", {
    zone_name: "fully.qualified.domain.com",
    vpc: vpc,
})

Additional VPCs can be added with zone.addVpc().

Adding Records

To add a TXT record to your zone:

my_zone = nil # AWSCDK::Route53::HostedZone


AWSCDK::Route53::TxtRecord.new(self, "TXTRecord", {
    zone: my_zone,
    record_name: "_foo",
     # If the name ends with a ".", it will be used as-is;
    # if it ends with a "." followed by the zone name, a trailing "." will be added automatically;
    # otherwise, a ".", the zone name, and a trailing "." will be added automatically.
    # Defaults to zone root if not specified.
    values: [
        "Bar!",
        "Baz?",
    ],
    ttl: AWSCDK::Duration.minutes(90),
})

To add a NS record to your zone:

my_zone = nil # AWSCDK::Route53::HostedZone


AWSCDK::Route53::NsRecord.new(self, "NSRecord", {
    zone: my_zone,
    record_name: "foo",
    values: [
        "ns-1.awsdns.co.uk.",
        "ns-2.awsdns.com.",
    ],
    ttl: AWSCDK::Duration.minutes(90),
})

To add a DS record to your zone:

my_zone = nil # AWSCDK::Route53::HostedZone


AWSCDK::Route53::DsRecord.new(self, "DSRecord", {
    zone: my_zone,
    record_name: "foo",
    values: [
        "12345 3 1 123456789abcdef67890123456789abcdef67890",
    ],
    ttl: AWSCDK::Duration.minutes(90),
})

To add an A record to your zone:

my_zone = nil # AWSCDK::Route53::HostedZone


AWSCDK::Route53::ARecord.new(self, "ARecord", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_ip_addresses("1.2.3.4", "5.6.7.8"),
})

To add an A record for an EC2 instance with an Elastic IP (EIP) to your zone:

instance = nil # AWSCDK::EC2::Instance

my_zone = nil # AWSCDK::Route53::HostedZone


elastic_ip = AWSCDK::EC2::CfnEIP.new(self, "EIP", {
    domain: "vpc",
    instance_id: instance.instance_id,
})
AWSCDK::Route53::ARecord.new(self, "ARecord", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_ip_addresses(elastic_ip.ref),
})

To create an A record of type alias with target set to another record created outside CDK:

This function registers the given input i.e. DNS Name(string) of an existing record as an AliasTarget to the new ARecord. To register a target that is created as part of CDK use this instead.

Detailed information can be found in the documentation.

my_zone = nil # AWSCDK::Route53::HostedZone


target_record = "existing.record.cdk.local"
record = AWSCDK::Route53::ARecord.from_a_record_attributes(self, "A", {
    zone: my_zone,
    record_name: "test",
    target_dns: target_record,
})

To add an AAAA record pointing to a CloudFront distribution:

require 'aws-cdk-lib'

my_zone = nil # AWSCDK::Route53::HostedZone
distribution = nil # AWSCDK::CloudFront::CloudFrontWebDistribution

AWSCDK::Route53::AaaaRecord.new(self, "Alias", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_alias(AWSCDK::Route53Targets::CloudFrontTarget.new(distribution)),
})

To add an HTTPS record:

require 'aws-cdk-lib'

my_zone = nil # AWSCDK::Route53::HostedZone
distribution = nil # AWSCDK::CloudFront::CloudFrontWebDistribution

# Alias to CloudFront target
AWSCDK::Route53::HttpsRecord.new(self, "HttpsRecord-CloudFrontAlias", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_alias(AWSCDK::Route53Targets::CloudFrontTarget.new(distribution)),
})
# ServiceMode (priority >= 1)
AWSCDK::Route53::HttpsRecord.new(self, "HttpsRecord-ServiceMode", {
    zone: my_zone,
    values: [AWSCDK::Route53::HttpsRecordValue.service({alpn: [AWSCDK::Route53::Alpn.H3, AWSCDK::Route53::Alpn.H2]})],
})
# AliasMode (priority = 0)
AWSCDK::Route53::HttpsRecord.new(self, "HttpsRecord-AliasMode", {
    zone: my_zone,
    values: [AWSCDK::Route53::HttpsRecordValue._alias("service.example.com")],
})

Geolocation routing can be enabled for continent, country or subdivision:

my_zone = nil # AWSCDK::Route53::HostedZone


# continent
AWSCDK::Route53::ARecord.new(self, "ARecordGeoLocationContinent", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_ip_addresses("1.2.3.0", "5.6.7.0"),
    geo_location: AWSCDK::Route53::GeoLocation.continent(AWSCDK::Route53::Continent::EUROPE),
})

# country
AWSCDK::Route53::ARecord.new(self, "ARecordGeoLocationCountry", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_ip_addresses("1.2.3.1", "5.6.7.1"),
    geo_location: AWSCDK::Route53::GeoLocation.country("DE"),
})

# subdivision
AWSCDK::Route53::ARecord.new(self, "ARecordGeoLocationSubDividion", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_ip_addresses("1.2.3.2", "5.6.7.2"),
    geo_location: AWSCDK::Route53::GeoLocation.subdivision("WA"),
})

# default (wildcard record if no specific record is found)
AWSCDK::Route53::ARecord.new(self, "ARecordGeoLocationDefault", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_ip_addresses("1.2.3.3", "5.6.7.3"),
    geo_location: AWSCDK::Route53::GeoLocation.default,
})

To enable weighted routing, use the weight parameter:

my_zone = nil # AWSCDK::Route53::HostedZone


AWSCDK::Route53::ARecord.new(self, "ARecordWeighted1", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_ip_addresses("1.2.3.4"),
    weight: 10,
})

To enable latency based routing, use the region parameter:

my_zone = nil # AWSCDK::Route53::HostedZone


AWSCDK::Route53::ARecord.new(self, "ARecordLatency1", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_ip_addresses("1.2.3.4"),
    region: "us-east-1",
})

To enable failover routing, use the failover parameter:

my_zone = nil # AWSCDK::Route53::HostedZone


health_check = AWSCDK::Route53::HealthCheck.new(self, "HealthCheck", {
    type: AWSCDK::Route53::HealthCheckType::HTTP,
    fqdn: "example.com",
    port: 80,
    resource_path: "/health",
    failure_threshold: 3,
    request_interval: AWSCDK::Duration.seconds(30),
})

AWSCDK::Route53::ARecord.new(self, "ARecordFailoverPrimary", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_ip_addresses("1.2.3.4"),
    failover: AWSCDK::Route53::Failover::PRIMARY,
    health_check: health_check,
    set_identifier: "failover-primary",
})

AWSCDK::Route53::ARecord.new(self, "ARecordFailoverSecondary", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_ip_addresses("5.6.7.8"),
    failover: AWSCDK::Route53::Failover::SECONDARY,
    set_identifier: "failover-secondary",
})

To enable multivalue answer routing, use the multivalue_answer parameter:

my_zone = nil # AWSCDK::Route53::HostedZone


AWSCDK::Route53::ARecord.new(self, "ARecordMultiValue1", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_ip_addresses("1.2.3.4"),
    multi_value_answer: true,
})

To enable IP-based routing, use the cidr_routing_config parameter:

my_zone = nil # AWSCDK::Route53::HostedZone


cidr_collection = AWSCDK::Route53::CfnCIDRCollection.new(self, "CidrCollection", {
    name: "test-collection",
    locations: [
        {
            cidr_list: ["192.168.1.0/24"],
            location_name: "my_location",
        },
    ],
})

AWSCDK::Route53::ARecord.new(self, "CidrRoutingConfig", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_ip_addresses("1.2.3.4"),
    set_identifier: "test",
    cidr_routing_config: AWSCDK::Route53::CIDRRoutingConfig.create({
        collection_id: cidr_collection.attr_id,
        location_name: "test_location",
    }),
})

To use the default CIDR record, call the route53.CidrRoutingConfig.default. This sets the location_name to *. The collection_id is still required.

my_zone = nil # AWSCDK::Route53::HostedZone


cidr_collection = AWSCDK::Route53::CfnCIDRCollection.new(self, "CidrCollection", {
    name: "test-collection",
    locations: [
        {
            cidr_list: ["192.168.1.0/24"],
            location_name: "my_location",
        },
    ],
})

AWSCDK::Route53::ARecord.new(self, "DefaultCidrRoutingConfig", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_ip_addresses("5.6.7.8"),
    set_identifier: "default",
    cidr_routing_config: AWSCDK::Route53::CIDRRoutingConfig.with_default_location_name(cidr_collection.attr_id),
})

To specify a unique identifier to differentiate among multiple resource record sets that have the same combination of name and type, use the set_identifier parameter:

my_zone = nil # AWSCDK::Route53::HostedZone


AWSCDK::Route53::ARecord.new(self, "ARecordWeighted1", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_ip_addresses("1.2.3.4"),
    weight: 10,
    set_identifier: "weighted-record-id",
})

Warning It is not possible to specify set_identifier for a simple routing policy.

Constructs are available for A, AAAA, CAA, CNAME, MX, NS, SRV and TXT records.

Use the CaaAmazonRecord construct to easily restrict certificate authorities allowed to issue certificates for a domain to Amazon only.

Health Checks

See the Route 53 Health Checks documentation for possible types of health checks.

Route 53 has the ability to monitor the health of your application and only return records for healthy endpoints. This is done using a HealthCheck construct.

In the following example, the ARecord will be returned by Route 53 in response to DNS queries only if the HTTP requests to the example.com/health endpoint return a 2XX or 3XX status code.

In case, when the endpoint is not healthy, the ARecord2 will be returned by Route 53 in response to DNS queries.

my_zone = nil # AWSCDK::Route53::HostedZone


health_check = AWSCDK::Route53::HealthCheck.new(self, "HealthCheck", {
    type: AWSCDK::Route53::HealthCheckType::HTTP,
    fqdn: "example.com",
    port: 80,
    resource_path: "/health",
    failure_threshold: 3,
    request_interval: AWSCDK::Duration.seconds(30),
})

AWSCDK::Route53::ARecord.new(self, "ARecord", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_ip_addresses("1.2.3.4"),
    health_check: health_check,
    weight: 100,
})
AWSCDK::Route53::ARecord.new(self, "ARecord2", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_ip_addresses("5.6.7.8"),
    weight: 0,
})

Replacing existing record sets (dangerous!)

Use the delete_existing prop to delete an existing record set before deploying the new one. This is useful if you want to minimize downtime and avoid "manual" actions while deploying a stack with a record set that already exists. This is typically the case for record sets that are not already "owned" by CloudFormation or "owned" by another stack or construct that is going to be deleted (migration).

N.B.: this feature is dangerous, use with caution! It can only be used safely when delete_existing is set to true as soon as the resource is added to the stack. Changing an existing Record Set's delete_existing property from false -> true after deployment will delete the record!

my_zone = nil # AWSCDK::Route53::HostedZone


AWSCDK::Route53::ARecord.new(self, "ARecord", {
    zone: my_zone,
    target: AWSCDK::Route53::RecordTarget.from_ip_addresses("1.2.3.4", "5.6.7.8"),
    delete_existing: true,
})

Cross Account Zone Delegation

If you want to have your root domain hosted zone in one account and your subdomain hosted zone in a different one, you can use CrossAccountZoneDelegationRecord to set up delegation between them.

In the account containing the parent hosted zone:

parent_zone = AWSCDK::Route53::PublicHostedZone.new(self, "HostedZone", {
    zone_name: "someexample.com",
})
cross_account_role = AWSCDK::IAM::Role.new(self, "CrossAccountRole", {
    # The role name must be predictable
    role_name: "MyDelegationRole",
    # The other account
    assumed_by: AWSCDK::IAM::AccountPrincipal.new("12345678901"),
})
parent_zone.grant_delegation(cross_account_role)

To restrict the records that can be created with the delegation IAM role, use the optional delegated_zone_names property in the delegation options, which enforces the route53:ChangeResourceRecordSetsNormalizedRecordNames condition key for record names that match those hosted zone names. The delegated_zone_names list may only consist of hosted zones names that are subzones of the parent hosted zone.

If the delegated zone name contains an unresolved token, it must resolve to a zone name that satisfies the requirements according to the documentation: https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/specifying-conditions-route53.html#route53_rrset_conditionkeys_normalization

All letters must be lowercase. The DNS name must be without the trailing dot. Characters other than a–z, 0–9, - (hyphen), _ (underscore), and . (period, as a delimiter between labels) must use escape codes in the format \three-digit octal code. For example, \052 is the octal code for character *.

This feature allows you to better follow the minimum permissions privilege principle:

beta_cross_account_role = nil # AWSCDK::IAM::Role

prod_cross_account_role = nil # AWSCDK::IAM::Role
parent_zone = AWSCDK::Route53::PublicHostedZone.new(self, "HostedZone", {
    zone_name: "someexample.com",
})
parent_zone.grant_delegation(beta_cross_account_role, {
    delegated_zone_names: ["beta.someexample.com"],
})
parent_zone.grant_delegation(prod_cross_account_role, {
    delegated_zone_names: ["prod.someexample.com"],
})

In the account containing the child zone to be delegated:

sub_zone = AWSCDK::Route53::PublicHostedZone.new(self, "SubZone", {
    zone_name: "sub.someexample.com",
})

# import the delegation role by constructing the roleArn
delegation_role_arn = AWSCDK::Stack.of(self).format_arn({
    region: "",
     # IAM is global in each partition
    service: "iam",
    account: "parent-account-id",
    resource: "role",
    resource_name: "MyDelegationRole",
})
delegation_role = AWSCDK::IAM::Role.from_role_arn(self, "DelegationRole", delegation_role_arn)

# create the record
AWSCDK::Route53::CrossAccountZoneDelegationRecord.new(self, "delegate", {
    delegated_zone: sub_zone,
    parent_hosted_zone_name: "someexample.com",
    delegation_role: delegation_role,
})

Delegating the hosted zone requires assuming a role in the parent hosted zone's account. In order for the assumed credentials to be valid, the resource must assume the role using an STS endpoint in a region where both the subdomain's account and the parent's account are opted-in. By default, this region is determined automatically, but if you need to change the region used for the AssumeRole call, specify assume_role_region:

sub_zone = AWSCDK::Route53::PublicHostedZone.new(self, "SubZone", {
    zone_name: "sub.someexample.com",
})

# import the delegation role by constructing the roleArn
delegation_role_arn = AWSCDK::Stack.of(self).format_arn({
    region: "",
     # IAM is global in each partition
    service: "iam",
    account: "parent-account-id",
    resource: "role",
    resource_name: "MyDelegationRole",
})
delegation_role = AWSCDK::IAM::Role.from_role_arn(self, "DelegationRole", delegation_role_arn)

AWSCDK::Route53::CrossAccountZoneDelegationRecord.new(self, "delegate", {
    delegated_zone: sub_zone,
    parent_hosted_zone_name: "someexample.com",
    delegation_role: delegation_role,
    assume_role_region: "us-east-1",
})

Add Trailing Dot to Domain Names

In order to continue managing existing domain names with trailing dots using CDK, you can set addTrailingDot: false to prevent the Construct from adding a dot at the end of the domain name.

AWSCDK::Route53::PublicHostedZone.new(self, "HostedZone", {
    zone_name: "fully.qualified.domain.com.",
    add_trailing_dot: false,
})

Enabling DNSSEC

DNSSEC can be enabled for Hosted Zones. For detailed information, see Configuring DNSSEC signing in Amazon Route 53.

Enabling DNSSEC requires an asymmetric KMS Customer-Managed Key using the ECC_NIST_P256 key spec. Additionally, that KMS key must be in us-east-1.

kms_key = AWSCDK::KMS::Key.new(self, "KmsCMK", {
    key_spec: AWSCDK::KMS::KeySpec::ECC_NIST_P256,
    key_usage: AWSCDK::KMS::KeyUsage::SIGN_VERIFY,
})
hosted_zone = AWSCDK::Route53::HostedZone.new(self, "HostedZone", {
    zone_name: "example.com",
})
# Enable DNSSEC signing for the zone
hosted_zone.enable_dnssec({kms_key: kms_key})

The necessary permissions for Route 53 to use the key will automatically be added when using this configuration. If it is necessary to create a key signing key manually, that can be done using the KeySigningKey construct:

hosted_zone = nil # AWSCDK::Route53::HostedZone
kms_key = nil # AWSCDK::KMS::Key

AWSCDK::Route53::KeySigningKey.new(self, "KeySigningKey", {
    hosted_zone: hosted_zone,
    kms_key: kms_key,
    key_signing_key_name: "ksk",
    status: AWSCDK::Route53::KeySigningKeyStatus::ACTIVE,
})

When directly constructing the KeySigningKey resource, enabling DNSSEC signing for the hosted zone will be need to be done explicitly (either using the CfnDNSSEC construct or via another means).

Accelerated Recovery

Route 53 accelerated recovery for managing public DNS records is designed to achieve a 60-minute Recovery Time Objective (RTO) in the event of service unavailability in the US East (N. Virginia) Region. When enabled on a Route 53 public hosted zone, you will be able to resume making changes to DNS records in the public hosted zone within approximately 60 minutes after AWS detects that operations in the US East (N. Virginia) Region are impaired.

This feature is only available for public hosted zones.

AWSCDK::Route53::PublicHostedZone.new(self, "HostedZone", {
    zone_name: "example.com",
    accelerated_recovery_enabled: true,
})

For more information, see Enabling accelerated recovery for managing public DNS records.

Imports

If you don't know the ID of the Hosted Zone to import, you can use the HostedZone.fromLookup:

AWSCDK::Route53::HostedZone.from_lookup(self, "MyZone", {
    domain_name: "example.com",
})

HostedZone.fromLookup requires an environment to be configured. Check out the documentation for more documentation and examples. CDK automatically looks into your ~/.aws/config file for the [default] profile. If you want to specify a different account run cdk deploy --profile [profile].

new MyDevStack(app, 'dev', {
  env: {
    account: process.env.CDK_DEFAULT_ACCOUNT,
    region: process.env.CDK_DEFAULT_REGION,
  },
});

If you know the ID and Name of a Hosted Zone, you can import it directly:

zone = AWSCDK::Route53::HostedZone.from_hosted_zone_attributes(self, "MyZone", {
    zone_name: "example.com",
    hosted_zone_id: "ZOJJZC49E0EPZ",
})

Alternatively, use the HostedZone.fromHostedZoneId to import hosted zones if you know the ID and the retrieval for the zone_name is undesirable. Note that any records created with a hosted zone obtained this way must have their name be fully qualified

zone = AWSCDK::Route53::HostedZone.from_hosted_zone_id(self, "MyZone", "ZOJJZC49E0EPZ")

You can import a Public Hosted Zone as well with the similar PublicHostedZone.fromPublicHostedZoneId and PublicHostedZone.fromPublicHostedZoneAttributes methods:

zone_from_attributes = AWSCDK::Route53::PublicHostedZone.from_public_hosted_zone_attributes(self, "MyZone", {
    zone_name: "example.com",
    hosted_zone_id: "ZOJJZC49E0EPZ",
})

# Does not know zoneName
zone_from_id = AWSCDK::Route53::PublicHostedZone.from_public_hosted_zone_id(self, "MyZone", "ZOJJZC49E0EPZ")

You can import a Private Hosted Zone with PrivateHostedZone.fromPrivateHostedZoneId and PrivateHostedZone.fromPrivateHostedZoneAttributes methods:

private_zone_from_attributes = AWSCDK::Route53::PrivateHostedZone.from_private_hosted_zone_attributes(self, "MyPrivateZone", {
    zone_name: "example.local",
    hosted_zone_id: "ZOJJZC49E0EPZ",
})

# Does not know zoneName
private_zone_from_id = AWSCDK::Route53::PrivateHostedZone.from_private_hosted_zone_id(self, "MyPrivateZone", "ZOJJZC49E0EPZ")

You can use CrossAccountZoneDelegationRecord on imported Hosted Zones with the grant_delegation method:

cross_account_role = AWSCDK::IAM::Role.new(self, "CrossAccountRole", {
    # The role name must be predictable
    role_name: "MyDelegationRole",
    # The other account
    assumed_by: AWSCDK::IAM::AccountPrincipal.new("12345678901"),
})

zone_from_id = AWSCDK::Route53::HostedZone.from_hosted_zone_id(self, "MyZone", "zone-id")
zone_from_id.grant_delegation(cross_account_role)

public_zone_from_id = AWSCDK::Route53::PublicHostedZone.from_public_hosted_zone_id(self, "MyPublicZone", "public-zone-id")
public_zone_from_id.grant_delegation(cross_account_role)

private_zone_from_id = AWSCDK::Route53::PrivateHostedZone.from_private_hosted_zone_id(self, "MyPrivateZone", "private-zone-id")
private_zone_from_id.grant_delegation(cross_account_role)

VPC Endpoint Service Private DNS

When you create a VPC endpoint service, AWS generates endpoint-specific DNS hostnames that consumers use to communicate with the service. For example, vpce-1234-abcdev-us-east-1.vpce-svc-123345.us-east-1.vpce.amazonaws.com. By default, your consumers access the service with that DNS name. This can cause problems with HTTPS traffic because the DNS will not match the backend certificate:

curl: (60) SSL: no alternative certificate subject name matches target host name 'vpce-abcdefghijklmnopq-rstuvwx.vpce-svc-abcdefghijklmnopq.us-east-1.vpce.amazonaws.com'

Effectively, the endpoint appears untrustworthy. To mitigate this, clients have to create an alias for this DNS name in Route53.

Private DNS for an endpoint service lets you configure a private DNS name so consumers can access the service using an existing DNS name without creating this Route53 DNS alias This DNS name can also be guaranteed to match up with the backend certificate.

Before consumers can use the private DNS name, you must verify that you have control of the domain/subdomain.

Assuming your account has ownership of the particular domain/subdomain, this construct sets up the private DNS configuration on the endpoint service, creates all the necessary Route53 entries, and verifies domain ownership.

require 'aws-cdk-lib'


vpc = AWSCDK::EC2::VPC.new(self, "VPC")
nlb = AWSCDK::ElasticLoadBalancingv2::NetworkLoadBalancer.new(self, "NLB", {
    vpc: vpc,
})
vpces = AWSCDK::EC2::VPCEndpointService.new(self, "VPCES", {
    vpc_endpoint_service_load_balancers: [nlb],
})
# You must use a public hosted zone so domain ownership can be verified
zone = AWSCDK::Route53::PublicHostedZone.new(self, "PHZ", {
    zone_name: "aws-cdk.dev",
})
AWSCDK::Route53::VPCEndpointServiceDomainName.new(self, "EndpointDomain", {
    endpoint_service: vpces,
    domain_name: "my-stuff.aws-cdk.dev",
    public_hosted_zone: zone,
})