AWS CDK Route 53 Constructs (v1)

1.204.0 · maintenance · verified Thu Apr 16

The `aws-cdk-aws-route53` library is a part of AWS Cloud Development Kit (CDK) v1, providing higher-level constructs for Amazon Route 53. It enables developers to define Route 53 resources such as hosted zones and various record types using familiar programming languages. While still available, CDK v1 is in maintenance mode, with its end-of-support reached on June 1, 2023. The current version is 1.204.0, and it adheres to a release cadence that has slowed significantly since the release of CDK v2 (`aws-cdk-lib`).

Common errors

```
No hosted zone found with ID: Z1234567XXXXXXXXXX
```
cause The provided hosted zone ID for an `AWS::Route53::RecordSet` resource is incorrect or does not exist in the AWS account where the stack is being deployed.

fix Validate the `HostedZoneId` value against your AWS Route 53 console. Ensure your AWS credentials are correct and you are deploying to the intended account/region. If using `HostedZone.fromLookup()`, ensure appropriate AWS credentials are available during `cdk synth`.
```
No hosted zones named "domain.com" found
```
cause CloudFormation cannot identify the hosted zone name defined for the `HostedZoneName` property. This often happens if the domain name is missing a trailing period or doesn't exist.

fix Ensure the `HostedZoneName` property includes a trailing period (e.g., `"domain.com."`) and that a hosted zone with that exact name exists in your AWS account. Use `aws route53 list-hosted-zones` to verify.
```
RRSet with DNS name a.domain.com is not permitted in zone domain-test.com.
```
cause The DNS value provided to the `Name` property of an `AWS::Route53::RecordSet` does not match the associated hosted zone. The `Name` must be a fully qualified domain name.

fix Ensure the `record_name` or `Name` property in your `RecordSet` construct is a fully qualified domain name that falls within the specified `zone`. For example, if your hosted zone is `example.com.`, a record name could be `a.example.com.`.

Warnings

breaking AWS CDK v1 (`aws-cdk.aws-route53`) reached its end-of-life on June 1, 2023. While still functional, it no longer receives updates or security patches. All new development should use AWS CDK v2 (`aws-cdk-lib`).
Fix: Migrate your CDK applications to AWS CDK v2. This involves changing import statements from `aws_cdk.aws_route53` to `aws_cdk_lib.aws_route53` and potentially updating construct usage due to API changes and feature flags. Refer to the official CDK v2 migration guide.
gotcha When defining CNAME records or looking up hosted zones by name, ensure that fully qualified domain names (FQDNs) are used and handle trailing dots consistently. Route 53 often treats names with and without trailing dots as identical but testing frameworks or specific APIs might require a trailing dot for exact matches.
Fix: Always use fully qualified domain names (e.g., `example.com.`) in `HostedZoneName` properties and be mindful of trailing dots in `record_name` and `domain_name` for `CnameRecord` and testing assertions.
gotcha Updating Route 53 record sets, especially for changes in routing policies or when using the `deleteExisting` property, can lead to unexpected behavior or require multiple deployment passes due to the underlying CloudFormation custom resource logic.
Fix: For complex updates to `RecordSet` properties, particularly routing policies, consider a staged deployment. Review CloudFormation change sets carefully. If `deleteExisting` causes issues (e.g., attempting to delete non-existent records in new regions), manually verify existing records or consider managing the lifecycle outside CDK for critical updates. For cross-account record management, consider `cdk-cross-account-route53`.

Install

pip install aws-cdk.aws-route53 Install with pip

Imports

PublicHostedZone

from aws_cdk import aws_route53 as route53

ARecord

from aws_cdk import aws_route53 as route53

RecordTarget

from aws_cdk import aws_route53 as route53

CnameRecord

from aws_cdk import aws_route53 as route53

HostedZone
wrong:
```
from aws_cdk.aws_route53 import HostedZone
```
correct:
```
from aws_cdk import aws_route53 as route53
```
While direct import works, aliasing `aws_route53` to `route53` is the conventional CDK v1 pattern for better readability and consistency.

Quickstart

This quickstart demonstrates how to create a public hosted zone and add A and CNAME records using `aws-cdk-aws-route53` within a CDK v1 application.

import os
from aws_cdk import core as cdk
from aws_cdk import aws_route53 as route53


class MyRoute53Stack(cdk.Stack):
    def __init__(self, scope: cdk.App, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        # Create a public hosted zone
        hosted_zone = route53.PublicHostedZone(
            self, "MyHostedZone",
            zone_name="example.com"
        )

        # Add an A record pointing to an IP address
        route53.ARecord(
            self, "MyARecord",
            zone=hosted_zone,
            target=route53.RecordTarget.from_ip_addresses("192.0.2.1", "198.51.100.1"),
            record_name="www"
        )

        # Add a CNAME record
        route53.CnameRecord(
            self, "MyCnameRecord",
            zone=hosted_zone,
            domain_name="www.example.com", # Must be a fully qualified domain name
            record_name="app"
        )

app = cdk.App()
MyRoute53Stack(app, "MyRoute53Stack",
               env=cdk.Environment(account=os.environ.get('CDK_DEFAULT_ACCOUNT', '123456789012'),
                                   region=os.environ.get('CDK_DEFAULT_REGION', 'us-east-1'))
               )
app.synth()

view raw JSON →