1 | # Amazon Route53 Construct Library
|
2 |
|
3 |
|
4 | ---
|
5 |
|
6 | ![End-of-Support](https://img.shields.io/badge/End--of--Support-critical.svg?style=for-the-badge)
|
7 |
|
8 | > AWS CDK v1 has reached End-of-Support on 2023-06-01.
|
9 | > This package is no longer being updated, and users should migrate to AWS CDK v2.
|
10 | >
|
11 | > For more information on how to migrate, see the [_Migrating to AWS CDK v2_ guide][doc].
|
12 | >
|
13 | > [doc]: https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html
|
14 |
|
15 | ---
|
16 |
|
17 |
|
18 |
|
19 | To add a public hosted zone:
|
20 |
|
21 | ```ts
|
22 | new route53.PublicHostedZone(this, 'HostedZone', {
|
23 | zoneName: 'fully.qualified.domain.com',
|
24 | });
|
25 | ```
|
26 |
|
27 | To add a private hosted zone, use `PrivateHostedZone`. Note that
|
28 | `enableDnsHostnames` and `enableDnsSupport` must have been enabled for the
|
29 | VPC you're configuring for private hosted zones.
|
30 |
|
31 | ```ts
|
32 | declare const vpc: ec2.Vpc;
|
33 |
|
34 | const zone = new route53.PrivateHostedZone(this, 'HostedZone', {
|
35 | zoneName: 'fully.qualified.domain.com',
|
36 | vpc, // At least one VPC has to be added to a Private Hosted Zone.
|
37 | });
|
38 | ```
|
39 |
|
40 | Additional VPCs can be added with `zone.addVpc()`.
|
41 |
|
42 | ## Adding Records
|
43 |
|
44 | To add a TXT record to your zone:
|
45 |
|
46 | ```ts
|
47 | declare const myZone: route53.HostedZone;
|
48 |
|
49 | new route53.TxtRecord(this, 'TXTRecord', {
|
50 | zone: myZone,
|
51 | recordName: '_foo', // If the name ends with a ".", it will be used as-is;
|
52 | // if it ends with a "." followed by the zone name, a trailing "." will be added automatically;
|
53 | // otherwise, a ".", the zone name, and a trailing "." will be added automatically.
|
54 | // Defaults to zone root if not specified.
|
55 | values: [ // Will be quoted for you, and " will be escaped automatically.
|
56 | 'Bar!',
|
57 | 'Baz?',
|
58 | ],
|
59 | ttl: Duration.minutes(90), // Optional - default is 30 minutes
|
60 | });
|
61 | ```
|
62 |
|
63 | To add a NS record to your zone:
|
64 |
|
65 | ```ts
|
66 | declare const myZone: route53.HostedZone;
|
67 |
|
68 | new route53.NsRecord(this, 'NSRecord', {
|
69 | zone: myZone,
|
70 | recordName: 'foo',
|
71 | values: [
|
72 | 'ns-1.awsdns.co.uk.',
|
73 | 'ns-2.awsdns.com.',
|
74 | ],
|
75 | ttl: Duration.minutes(90), // Optional - default is 30 minutes
|
76 | });
|
77 | ```
|
78 |
|
79 | To add a DS record to your zone:
|
80 |
|
81 | ```ts
|
82 | declare const myZone: route53.HostedZone;
|
83 |
|
84 | new route53.DsRecord(this, 'DSRecord', {
|
85 | zone: myZone,
|
86 | recordName: 'foo',
|
87 | values: [
|
88 | '12345 3 1 123456789abcdef67890123456789abcdef67890',
|
89 | ],
|
90 | ttl: Duration.minutes(90), // Optional - default is 30 minutes
|
91 | });
|
92 | ```
|
93 |
|
94 | To add an A record to your zone:
|
95 |
|
96 | ```ts
|
97 | declare const myZone: route53.HostedZone;
|
98 |
|
99 | new route53.ARecord(this, 'ARecord', {
|
100 | zone: myZone,
|
101 | target: route53.RecordTarget.fromIpAddresses('1.2.3.4', '5.6.7.8'),
|
102 | });
|
103 | ```
|
104 |
|
105 | To add an A record for an EC2 instance with an Elastic IP (EIP) to your zone:
|
106 |
|
107 | ```ts
|
108 | declare const instance: ec2.Instance;
|
109 |
|
110 | const elasticIp = new ec2.CfnEIP(this, 'EIP', {
|
111 | domain: 'vpc',
|
112 | instanceId: instance.instanceId,
|
113 | });
|
114 |
|
115 | declare const myZone: route53.HostedZone;
|
116 | new route53.ARecord(this, 'ARecord', {
|
117 | zone: myZone,
|
118 | target: route53.RecordTarget.fromIpAddresses(elasticIp.ref),
|
119 | });
|
120 | ```
|
121 |
|
122 | To add an AAAA record pointing to a CloudFront distribution:
|
123 |
|
124 | ```ts
|
125 | import * as cloudfront from '@aws-cdk/aws-cloudfront';
|
126 |
|
127 | declare const myZone: route53.HostedZone;
|
128 | declare const distribution: cloudfront.CloudFrontWebDistribution;
|
129 | new route53.AaaaRecord(this, 'Alias', {
|
130 | zone: myZone,
|
131 | target: route53.RecordTarget.fromAlias(new targets.CloudFrontTarget(distribution)),
|
132 | });
|
133 | ```
|
134 |
|
135 | Constructs are available for A, AAAA, CAA, CNAME, MX, NS, SRV and TXT records.
|
136 |
|
137 | Use the `CaaAmazonRecord` construct to easily restrict certificate authorities
|
138 | allowed to issue certificates for a domain to Amazon only.
|
139 |
|
140 | To add a NS record to a HostedZone in different account you can do the following:
|
141 |
|
142 | In the account containing the parent hosted zone:
|
143 |
|
144 | ```ts
|
145 | const parentZone = new route53.PublicHostedZone(this, 'HostedZone', {
|
146 | zoneName: 'someexample.com',
|
147 | crossAccountZoneDelegationPrincipal: new iam.AccountPrincipal('12345678901'),
|
148 | crossAccountZoneDelegationRoleName: 'MyDelegationRole',
|
149 | });
|
150 | ```
|
151 |
|
152 | In the account containing the child zone to be delegated:
|
153 |
|
154 | ```ts
|
155 | const subZone = new route53.PublicHostedZone(this, 'SubZone', {
|
156 | zoneName: 'sub.someexample.com',
|
157 | });
|
158 |
|
159 | // import the delegation role by constructing the roleArn
|
160 | const delegationRoleArn = Stack.of(this).formatArn({
|
161 | region: '', // IAM is global in each partition
|
162 | service: 'iam',
|
163 | account: 'parent-account-id',
|
164 | resource: 'role',
|
165 | resourceName: 'MyDelegationRole',
|
166 | });
|
167 | const delegationRole = iam.Role.fromRoleArn(this, 'DelegationRole', delegationRoleArn);
|
168 |
|
169 | // create the record
|
170 | new route53.CrossAccountZoneDelegationRecord(this, 'delegate', {
|
171 | delegatedZone: subZone,
|
172 | parentHostedZoneName: 'someexample.com', // or you can use parentHostedZoneId
|
173 | delegationRole,
|
174 | });
|
175 | ```
|
176 |
|
177 | ## Imports
|
178 |
|
179 | If you don't know the ID of the Hosted Zone to import, you can use the
|
180 | `HostedZone.fromLookup`:
|
181 |
|
182 | ```ts
|
183 | route53.HostedZone.fromLookup(this, 'MyZone', {
|
184 | domainName: 'example.com',
|
185 | });
|
186 | ```
|
187 |
|
188 | `HostedZone.fromLookup` requires an environment to be configured. Check
|
189 | out the [documentation](https://docs.aws.amazon.com/cdk/latest/guide/environments.html) for more documentation and examples. CDK
|
190 | automatically looks into your `~/.aws/config` file for the `[default]` profile.
|
191 | If you want to specify a different account run `cdk deploy --profile [profile]`.
|
192 |
|
193 | ```text
|
194 | new MyDevStack(app, 'dev', {
|
195 | env: {
|
196 | account: process.env.CDK_DEFAULT_ACCOUNT,
|
197 | region: process.env.CDK_DEFAULT_REGION,
|
198 | },
|
199 | });
|
200 | ```
|
201 |
|
202 | If you know the ID and Name of a Hosted Zone, you can import it directly:
|
203 |
|
204 | ```ts
|
205 | const zone = route53.HostedZone.fromHostedZoneAttributes(this, 'MyZone', {
|
206 | zoneName: 'example.com',
|
207 | hostedZoneId: 'ZOJJZC49E0EPZ',
|
208 | });
|
209 | ```
|
210 |
|
211 | Alternatively, use the `HostedZone.fromHostedZoneId` to import hosted zones if
|
212 | you know the ID and the retrieval for the `zoneName` is undesirable.
|
213 |
|
214 | ```ts
|
215 | const zone = route53.HostedZone.fromHostedZoneId(this, 'MyZone', 'ZOJJZC49E0EPZ');
|
216 | ```
|
217 |
|
218 | You can import a Public Hosted Zone as well with the similar `PubicHostedZone.fromPublicHostedZoneId` and `PubicHostedZone.fromPublicHostedZoneAttributes` methods:
|
219 |
|
220 | ```ts
|
221 | const zoneFromAttributes = route53.PublicHostedZone.fromPublicHostedZoneAttributes(this, 'MyZone', {
|
222 | zoneName: 'example.com',
|
223 | hostedZoneId: 'ZOJJZC49E0EPZ',
|
224 | });
|
225 |
|
226 | // Does not know zoneName
|
227 | const zoneFromId = route53.PublicHostedZone.fromPublicHostedZoneId(this, 'MyZone', 'ZOJJZC49E0EPZ');
|
228 | ```
|
229 |
|
230 | ## VPC Endpoint Service Private DNS
|
231 |
|
232 | When you create a VPC endpoint service, AWS generates endpoint-specific DNS hostnames that consumers use to communicate with the service.
|
233 | For example, vpce-1234-abcdev-us-east-1.vpce-svc-123345.us-east-1.vpce.amazonaws.com.
|
234 | By default, your consumers access the service with that DNS name.
|
235 | This can cause problems with HTTPS traffic because the DNS will not match the backend certificate:
|
236 |
|
237 | ```console
|
238 | curl: (60) SSL: no alternative certificate subject name matches target host name 'vpce-abcdefghijklmnopq-rstuvwx.vpce-svc-abcdefghijklmnopq.us-east-1.vpce.amazonaws.com'
|
239 | ```
|
240 |
|
241 | Effectively, the endpoint appears untrustworthy. To mitigate this, clients have to create an alias for this DNS name in Route53.
|
242 |
|
243 | Private DNS for an endpoint service lets you configure a private DNS name so consumers can
|
244 | access the service using an existing DNS name without creating this Route53 DNS alias
|
245 | This DNS name can also be guaranteed to match up with the backend certificate.
|
246 |
|
247 | Before consumers can use the private DNS name, you must verify that you have control of the domain/subdomain.
|
248 |
|
249 | Assuming your account has ownership of the particular domain/subdomain,
|
250 | this construct sets up the private DNS configuration on the endpoint service,
|
251 | creates all the necessary Route53 entries, and verifies domain ownership.
|
252 |
|
253 | ```ts nofixture
|
254 | import { Stack } from '@aws-cdk/core';
|
255 | import { Vpc, VpcEndpointService } from '@aws-cdk/aws-ec2';
|
256 | import { NetworkLoadBalancer } from '@aws-cdk/aws-elasticloadbalancingv2';
|
257 | import { PublicHostedZone, VpcEndpointServiceDomainName } from '@aws-cdk/aws-route53';
|
258 |
|
259 | const stack = new Stack();
|
260 | const vpc = new Vpc(stack, 'VPC');
|
261 | const nlb = new NetworkLoadBalancer(stack, 'NLB', {
|
262 | vpc,
|
263 | });
|
264 | const vpces = new VpcEndpointService(stack, 'VPCES', {
|
265 | vpcEndpointServiceLoadBalancers: [nlb],
|
266 | });
|
267 | // You must use a public hosted zone so domain ownership can be verified
|
268 | const zone = new PublicHostedZone(stack, 'PHZ', {
|
269 | zoneName: 'aws-cdk.dev',
|
270 | });
|
271 | new VpcEndpointServiceDomainName(stack, 'EndpointDomain', {
|
272 | endpointService: vpces,
|
273 | domainName: 'my-stuff.aws-cdk.dev',
|
274 | publicHostedZone: zone,
|
275 | });
|
276 | ```
|