Install & Compatibility
Where this runs
tested against v1.204.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 58MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 7.2s · import 0.000s · 59MB
60MB installed
● package 60MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
✓ from aws_cdk import aws_route53 as route53
✗ from aws_cdk.aws_route53 import HostedZone
While direct import works, aliasing `aws_route53` to `route53` is the conventional CDK v1 pattern for better readability and consistency.
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()
cdk --version
Debug
Known issues
breakingAWS 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`).fixMigrate 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.
affects: All v1 versions (1.x.x)
gotchaWhen 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.fixAlways 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.
affects: All v1 versions (1.x.x)
gotchaUpdating 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.fixFor 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`.
affects: All v1 versions (1.x.x)
Errors
Common errors & fixes
No hosted zone found with ID: Z1234567XXXXXXXXXX
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.
fixValidate 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
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.
fixEnsure 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.
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.
fixEnsure 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.`.
Upgrade
Version history
1.204.0latest on PyPI · released Jun 19, 2023
Audit
Dependencies
aws-cdk.corerequiredCore CDK constructs and app management for CDK v1.