@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
mdx 412 lines 16.1 KB
Raw
1 ---
2 title: DNS Adapters
3 description: Publish a custom domain's DNS records in Route 53, Cloudflare, or Hetzner DNS from any platform, and build an adapter for another DNS host.
4 ---
5
6 A custom domain has two parts. The platform that **serves** the hostname
7 (CloudFront, a load balancer, API Gateway, a Worker, a Fly App) issues or
8 attaches a certificate and tells you which DNS records it needs. The DNS
9 host that **publishes** the hostname's records is often somewhere else:
10 a domain registered with Cloudflare Registrar can point at an AWS website,
11 and a Route 53 zone can point at a Fly App.
12
13 A DNS adapter connects the two. Set `domain.dns` to the DNS host, and the
14 platform publishes its certificate-validation records and the records that
15 point the hostname at it through that host:
16
17 ```typescript
18 yield* AWS.Website.StaticSite("Site", {
19 path: "./dist",
20 domain: {
21 name: "app.example.com",
22 dns: Cloudflare.DNS.Adapter(),
23 },
24 });
25 ```
26
27 The stack's `providers` must include the DNS host's `providers()` layer
28 alongside the platform's, here `Layer.mergeAll(AWS.providers(),
29 Cloudflare.providers())`.
30
31 ## Built-in adapters
32
33 | Adapter | DNS host | Options |
34 | --- | --- | --- |
35 | `Cloudflare.DNS.Adapter()` | A Cloudflare zone | `zone` (zone id, zone name, or `Zone` resource), `proxied` |
36 | `AWS.Route53.Adapter()` | A Route 53 hosted zone | `hostedZoneId` |
37 | `Hetzner.DNS.Adapter()` | A Hetzner DNS zone | `zone` (zone id, zone name, or `Hetzner.Zone` resource) |
38
39 Each adapter infers the zone from every hostname by walking its parent
40 domains. Pass `zone` (or `hostedZoneId`) to pin it.
41
42 `Cloudflare.DNS.Adapter({ proxied: true })` sends the alias records through
43 Cloudflare's proxy. Validation and verification records are always
44 DNS-only. Cloudflare flattens a `CNAME` at the zone apex; Route 53 and
45 Hetzner can't, so an apex hostname on those hosts needs an AWS alias target
46 (Route 53) or an address target.
47
48 ## Where `dns` works
49
50 | Platform | `dns` omitted | Records published through the adapter |
51 | --- | --- | --- |
52 | `AWS.Website.*` sites and `AWS.Website.Router` | Route 53 | ACM validation `CNAME`s; each hostname aliased to CloudFront |
53 | `AWS.ECS.Service` load balancer `domain` | Route 53 | ACM validation `CNAME`s; each hostname aliased to the load balancer |
54 | `AWS.Lambda.Function` `domain` | Route 53 | ACM validation `CNAME`s; each hostname aliased to its API Gateway domain |
55 | `Cloudflare.Worker` and `Cloudflare.Website.*` | Native Worker custom domain | Custom-hostname ownership and certificate `TXT` records; a `CNAME` to your Cloudflare for SaaS zone |
56 | `Fly.Website.*` | You publish the records | The ACME challenge `CNAME`; `A`/`AAAA` records at the site |
57 | `Railway.Website.*` | You publish the records | The `CNAME` and verification `TXT` Railway requires |
58 | `Neon.Website.*` | You publish the records | A `CNAME` to the custom domain's target |
59 | `Prisma.Website.*` | You publish the records | A `CNAME` to the app's regional switchboard, published before the domain is registered |
60 | `Hetzner.Website.*` | An `A` record in `zone` | An `A` record at the server |
61
62 A plain string `domain` keeps each platform's default. Setting `dns` never
63 changes how the platform serves the hostname, only where its records live.
64
65 ### AWS websites and load balancers
66
67 `dns` sits next to the other `domain` fields:
68
69 ```typescript
70 const router = yield* AWS.Website.Router("Router", {
71 domain: {
72 name: "example.com",
73 aliases: ["www.example.com"],
74 dns: Cloudflare.DNS.Adapter({ zone: "example.com" }),
75 },
76 });
77 ```
78
79 ACM still issues the certificate. With Route 53 the certificate resource
80 publishes its own validation records. With any other host the composite
81 requests the certificate with `dnsValidation: "external"`, publishes the
82 validation `CNAME`s through the adapter, and waits for issuance with
83 `AWS.ACM.CertificateValidation` before CloudFront or the listener uses it.
84 Hostnames that sites attached to a `Router` bind onto its record set go
85 through the same adapter.
86
87 `AWS.ECS.Service` takes the same field on its load balancer domain:
88
89 ```typescript
90 yield* AWS.ECS.Service("Api", {
91 cluster,
92 image: "my-org/api:latest",
93 port: 3000,
94 loadBalancer: {
95 domain: { name: "api.example.com", dns: Cloudflare.DNS.Adapter() },
96 },
97 });
98 ```
99
100 ### Lambda Functions
101
102 Function URLs can't serve a custom hostname, so a Function's `domain`
103 composes an API Gateway v2 HTTP API in front of it, with a regional ACM
104 certificate and an API Gateway domain name per hostname. The HTTP API uses
105 payload format 2.0, the same event shape as a Function URL, so a `fetch`
106 handler works unchanged:
107
108 ```typescript
109 const api = yield* AWS.Lambda.Function("Api", {
110 main: "./src/handler.ts",
111 domain: {
112 name: "api.example.com",
113 dns: Cloudflare.DNS.Adapter({ zone: "example.com" }),
114 },
115 });
116 // api.domainUrl → "https://api.example.com"
117 ```
118
119 ### Cloudflare Workers on another DNS host
120
121 A Worker's native custom domain requires the hostname to be in a Cloudflare
122 zone. When the hostname's DNS lives in Route 53 or Hetzner, the Worker
123 serves it through
124 [Cloudflare for SaaS](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/worker-as-origin/)
125 on a Cloudflare zone you own, called the SaaS zone:
126
127 ```typescript
128 // Once per SaaS zone: an originless proxied record as the fallback origin.
129 const origin = yield* Cloudflare.DNS.Record("SaasOrigin", {
130 zoneId: saasZone.zoneId,
131 name: "customers.my-saas.com",
132 type: "AAAA",
133 content: "100::",
134 proxied: true,
135 });
136 const fallback = yield* Cloudflare.CustomHostname.FallbackOrigin(
137 "SaasFallback",
138 { zoneId: saasZone.zoneId, origin: origin.name },
139 );
140
141 yield* Cloudflare.Worker("Api", {
142 main: "./src/api.ts",
143 domain: {
144 name: "app.example.com",
145 zoneId: saasZone.zoneId,
146 cnameTarget: fallback.origin,
147 dns: AWS.Route53.Adapter(),
148 },
149 });
150 ```
151
152 Each hostname becomes a `Cloudflare.CustomHostname.CustomHostname` on the
153 SaaS zone. The adapter publishes its ownership and certificate `TXT`
154 records and a `CNAME` to `cnameTarget`, and the Worker gets a
155 `{hostname}/*` route on the SaaS zone. Cloudflare for SaaS must be enabled
156 on the zone; without it Cloudflare rejects the custom hostname with
157 `SaasQuotaNotAllocated`. This path doesn't support `redirects`, `previews`,
158 or apex hostnames, and the Worker's `url` stays its `workers.dev` URL.
159
160 With `dns` omitted, or set to `Cloudflare.DNS.Adapter()`, the Worker attaches
161 native custom domains exactly as before.
162
163 ### Fly, Railway, Neon, Prisma, and Hetzner websites
164
165 These platforms host no DNS, so without `dns` you publish the records their
166 custom-domain resources list. Use the object form of `domain` to publish
167 them through an adapter:
168
169 ```typescript
170 yield* Fly.Website.Vite("Web", {
171 domain: {
172 name: "app.example.com",
173 dns: AWS.Route53.Adapter(),
174 },
175 });
176 ```
177
178 On `Hetzner.Website.*`, `dns` replaces the `zone` prop, so the site can
179 also publish its `A` record in Cloudflare or Route 53.
180
181 ## What gets created
182
183 An adapter declares ordinary record resources of its own cloud, so they
184 appear in the plan and in state like any other resource:
185
186 | Adapter | Hostname aliases | Validation and verification records |
187 | --- | --- | --- |
188 | Cloudflare | `Cloudflare.DNS.Records` (`CNAME`), or `Cloudflare.DNS.RecordList` for addresses | `Cloudflare.DNS.RecordList` |
189 | Route 53 | `AWS.Route53.Record` (`A`/`AAAA` alias or `CNAME`), `AWS.Route53.Records` for a Router | `AWS.Route53.RecordList` |
190 | Hetzner | `Hetzner.DNS.RecordList` | `Hetzner.DNS.RecordList` |
191
192 Record ownership follows the rest of Alchemy:
193
194 - **Alias records** are owned by the stack. The first deploy refuses to
195 overwrite a record that already exists at a hostname unless you pass
196 `--adopt`. Removing the domain deletes the records.
197 - **Validation and verification records** are added next to any other
198 values at the same name and removed on destroy. ACM validation `CNAME`s
199 are the exception: ACM reuses one `CNAME` per name for every certificate,
200 so they stay in the zone when the certificate is deleted.
201
202 The Route 53 adapter declares the same resources, with the same logical
203 IDs, that AWS composites declared before `dns` existed, so upgrading a
204 stack that uses Route 53 plans no changes.
205
206 ## Switching DNS hosts
207
208 Changing `domain.dns` swaps the record resources: the next deploy creates
209 the records at the new host and deletes them from the old one, each through
210 its own provider. Update the domain's nameservers at the registrar once the
211 new records are in place.
212
213 ## How adapters work
214
215 `domain.dns` holds plain data, for example
216 `{ type: "Cloudflare.DNS", zone: "example.com" }`. That keeps it safe in any
217 resource's props, in state, and across the `alchemy dev` sidecar.
218
219 While the stack program runs, the platform resolves the adapter registered
220 for that `type`. Each DNS host's `providers()` layer registers its adapter.
221 The adapter's methods only declare resources. No provider calls an adapter
222 while it deploys, so destroying a stack or cleaning up an orphan needs
223 nothing but state and the record resources' own providers.
224
225 An adapter is three functions that declare record resources. Each receives
226 the zone and options from the user's `domain.dns` alongside its own
227 arguments:
228
229 | Function | Declares |
230 | --- | --- |
231 | `alias(id, { zone, name, target, ipv6? })` | Records pointing one hostname at a hostname target (`CNAME`, or a Route 53 alias when `target.route53Alias` is set) or an address target (`A`/`AAAA`) |
232 | `aliasSet(id, { zone, names?, target })` | A record set that other composites add hostnames to by binding `{ names }`, used by `AWS.Website.Router` |
233 | `records(id, { zone, records, retain? })` | Explicit records whose values usually come from another resource's outputs |
234
235 ## Build your own adapter
236
237 This walkthrough adds an adapter for a hypothetical "Acme DNS" API. Any
238 platform's `domain.dns` can then publish records there.
239
240 ### Write the record resource
241
242 An adapter declares resources, so your DNS host first needs a resource that
243 manages DNS records. The simplest one that covers every adapter function is
244 a **record list**: one resource that owns a list of
245 `{ name, type, value }` records. A list fits because platforms often don't
246 know how many records they need until deploy time. ACM, for example,
247 returns one validation record per hostname on the certificate.
248
249 ```typescript
250 // src/acme-dns/RecordList.ts
251 import { Resource } from "alchemy";
252 import type { DnsRecord } from "alchemy/DNS";
253
254 export interface RecordListProps {
255 /** Zone that owns the records. Inferred from each name when omitted. */
256 zone?: string;
257 /** Records to publish, e.g. `{ name: "www.example.com", type: "CNAME", value: "d123.cloudfront.net" }`. */
258 records: DnsRecord[];
259 }
260
261 export type RecordList = Resource<
262 "AcmeDns.RecordList",
263 RecordListProps,
264 { records: DnsRecord[] }
265 >;
266
267 export const RecordList = Resource<RecordList>("AcmeDns.RecordList");
268 ```
269
270 Its provider's `reconcile` creates each listed record and deletes the ones
271 it created before that are no longer listed; `delete` removes the records it
272 created. Build it as described in
273 [Custom Provider](/infrastructure-as-code/custom-provider).
274 `Cloudflare.DNS.RecordList` and `AWS.Route53.RecordList` are complete
275 references.
276
277 ### Write the data constructor
278
279 The constructor returns the plain data users put in `domain.dns`. Pick a
280 `type` that's unique to your adapter:
281
282 ```typescript
283 // src/acme-dns/Adapter.ts
284 import type { DnsConfig } from "alchemy/DNS";
285
286 export const Adapter = (
287 options: { zone?: string } = {},
288 ): DnsConfig<"AcmeDns"> => ({
289 type: "AcmeDns",
290 ...(options.zone === undefined ? {} : { zone: options.zone }),
291 });
292 ```
293
294 ### Implement the adapter
295
296 The adapter is an object with three functions, each returning the resource
297 it declares:
298
299 ```typescript
300 // src/acme-dns/Adapter.ts
301 import * as DNS from "alchemy/DNS";
302 import * as RemovalPolicy from "alchemy/RemovalPolicy";
303 import type { Providers } from "./Providers.ts";
304 import { RecordList } from "./RecordList.ts";
305
306 export const adapter = {
307 // Point one hostname at the platform: a CNAME, or A/AAAA records.
308 alias: (id, { zone, name, target }) =>
309 RecordList(id, { zone, records: DNS.aliasRecords(name, target) as DNS.DnsRecord[] }),
310 // Several hostnames at one hostname target. Give RecordList a `{ names }`
311 // binding contract to let sites attached to an AWS.Website.Router add theirs.
312 aliasSet: (id, { zone, names = [], target }) =>
313 RecordList(id, {
314 zone,
315 records: names.map((name) => ({ name, type: "CNAME" as const, value: target.hostname as string })),
316 }),
317 // Records the platform computed, e.g. certificate validation CNAMEs.
318 records: (id, { zone, records, retain }) =>
319 RecordList(id, { zone, records: records as DNS.DnsRecord[] }).pipe(
320 retain ? RemovalPolicy.retain() : (effect) => effect,
321 ),
322 } satisfies DNS.DnsAdapter<Providers>;
323 ```
324
325 `satisfies DNS.DnsAdapter<Providers>` types the arguments and checks that
326 each function declares resources of your cloud. Honor `retain`: platforms
327 set it for records that must outlive the resource, such as ACM validation
328 `CNAME`s.
329
330 ### Register it in your providers layer
331
332 `adapterLayer` only registers the adapter service. It does not register the
333 native record providers declared by `alias`, `aliasSet`, or `records`, so
334 include those providers in the host package's `providers()` layer as well.
335
336 `DNS.adapterLayer` registers the adapter under the `type` your constructor
337 returns. Merge it into the same `providers()` layer that registers your
338 record providers:
339
340 ```typescript
341 // src/acme-dns/Providers.ts
342 import * as DNS from "alchemy/DNS";
343 import * as Layer from "effect/Layer";
344 import { adapter } from "./Adapter.ts";
345
346 export const providers = () =>
347 Layer.mergeAll(RecordListProvider(), DNS.adapterLayer("AcmeDns", adapter));
348 ```
349
350 ### Use it from a stack
351
352 Pass the data constructor as `domain.dns` on any platform, and add your
353 layer to the stack's providers:
354
355 ```typescript
356 const stack = Alchemy.Stack(
357 "Web",
358 { providers: Layer.mergeAll(AWS.providers(), AcmeDns.providers()) },
359 Effect.gen(function* () {
360 yield* AWS.Website.StaticSite("Site", {
361 path: "./dist",
362 domain: { name: "app.example.com", dns: AcmeDns.Adapter() },
363 });
364 }),
365 );
366 ```
367
368 ### Test it
369
370 Test against the real DNS host. Deploy a stack that calls each adapter
371 function, check the records out of band with the host's API, update the
372 stack and check that the records converge, then destroy it and check that
373 they're gone. Start and end every test with `stack.destroy()`:
374
375 ```typescript
376 test.provider("publishes an alias", (stack) =>
377 Effect.gen(function* () {
378 yield* stack.destroy();
379 yield* stack.deploy(
380 Effect.gen(function* () {
381 const dns = yield* DNS.resolve(AcmeDns.Adapter({ zone: "example.com" }));
382 yield* dns.alias("Web", { name: "www.example.com", target: { hostname: "example.net" } });
383 }),
384 );
385 // read the CNAME back through the Acme DNS API and assert on it
386 yield* stack.destroy();
387 // assert the CNAME is gone
388 }),
389 );
390 ```
391
392 `packages/integration-tests/test/DNS/Adapter.test.ts` does this for the
393 built-in adapters.
394
395 ## Troubleshooting
396
397 | Error | Cause and fix |
398 | --- | --- |
399 | `DnsAdapterNotRegistered` | `domain.dns` names a host whose `providers()` layer isn't in the stack. Add it, for example `Cloudflare.providers()` for `Cloudflare.DNS.Adapter()`. |
400 | `OwnedBySomeoneElse` | A record already exists at a hostname the domain aliases. Delete it, or deploy with `--adopt` to take it over. |
401 | `CertificateCaaError` | A `CAA` record on the domain doesn't authorize Amazon, so ACM refused to issue the certificate. Add `0 issue "amazon.com"` (and `issuewild` for wildcard names) at the zone apex and redeploy. Alchemy never writes `CAA` records. |
402 | `DnsAdapterError` | The DNS host can't publish a record as requested, for example a `CNAME` at the apex of a pinned Hetzner zone. Use an address target or a host that flattens `CNAME`s. |
403 | `SaasQuotaNotAllocated` | A Worker's `domain.dns` names another host, but Cloudflare for SaaS isn't enabled on the SaaS zone. |
404
405 ## Where to go next
406
407 - [AWS custom domains](/aws/networking/custom-domains): certificates, hosted
408 zones, and API Gateway domains on AWS.
409 - [Cloudflare domains](/cloudflare/networking/domains): zones and DNS
410 records on Cloudflare.
411 - [Custom Provider](/infrastructure-as-code/custom-provider): implement the
412 record resources behind a new adapter.