@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, 06:00 UTC

main
mdx 149 lines 4.88 KB
Raw
1 ---
2 title: DNS
3 description: Hetzner Cloud DNS with Alchemy — Zones and RecordSets as resources, plus ReadDns/WriteDns bindings for querying and mutating records from Effects.
4 ---
5
6 Hetzner Cloud DNS is part of the same project and the same
7 `HCLOUD_TOKEN` as your servers — no separate account, console, or
8 token. Alchemy models it two ways: **resources** (`Zone`,
9 `RecordSet`) for records that belong to your stack, and **bindings**
10 (`ReadDns`/`WriteDns`) for code that queries or mutates records
11 dynamically.
12
13 ## Zones
14
15 A [`Zone`](/providers/hetzner/zone) is an apex domain you own —
16 `name` must be a real registrable domain (no subdomains, no
17 trailing dot):
18
19 ```typescript
20 import * as Hetzner from "@alchemy.run/hetzner";
21
22 export const Dns = Hetzner.Zone("dns", {
23 name: "example.com",
24 ttl: 300,
25 });
26 ```
27
28 Changing `name` replaces the Zone. The resolved resource exposes
29 `assignedNameservers` — set those at your registrar to delegate the
30 domain — plus `delegationStatus` to check whether that's done.
31
32 ## RecordSets
33
34 A [`RecordSet`](/providers/hetzner/recordset) is one `(name, type)`
35 pair and **all** of its records. Values accept resource outputs, so
36 pointing your domain at a Load Balancer is a reference, not a
37 copy-pasted IP:
38
39 ```typescript
40 const www = yield* Hetzner.RecordSet("www", {
41 zone: Dns,
42 name: "www",
43 type: "A",
44 ttl: 300,
45 records: [{ value: lb.ipv4.as<string>() }],
46 });
47 ```
48
49 `name` is relative to the zone (`@` for the apex). Changing `zone`,
50 `name`, or `type` replaces the RecordSet; `records` and `ttl`
51 update in place. Because a RecordSet owns the whole `(name, type)`
52 pair, keep each pair in exactly one resource.
53
54 ## Query & mutate from Effects
55
56 For DNS that isn't part of the declared stack — health-dependent
57 records, dynamic entries, lookups — bind a typed client to a zone.
58 Three bindings, each with a matching layer:
59
60 | Binding | Layer | Client |
61 | --- | --- | --- |
62 | `Hetzner.ReadDns(zone)` | `Hetzner.ReadDnsHttp` | `getRecordSet`, `listRecordSets` |
63 | `Hetzner.WriteDns(zone)` | `Hetzner.WriteDnsHttp` | `createRecordSet`, `setRecordSetRecords`, `addRecordSetRecords`, `removeRecordSetRecords`, `updateRecordSet`, `deleteRecordSet`, `changeRecordSetTtl`, … |
64 | `Hetzner.ReadWriteDns(zone)` | `Hetzner.ReadWriteDnsHttp` | both |
65
66 The zone is fixed when you bind — pass the Zone declaration
67 directly, and calls never pass a zone id:
68
69 ```typescript
70 import * as Alchemy from "alchemy";
71 import * as Hetzner from "@alchemy.run/hetzner";
72 import * as Effect from "effect/Effect";
73 import { Dns } from "./dns.ts";
74
75 const SyncRecords = Alchemy.Action(
76 "SyncRecords",
77 Effect.gen(function* () {
78 const dns = yield* Hetzner.ReadWriteDns(Dns);
79
80 return Effect.fn(function* () {
81 const listed = yield* dns.listRecordSets({ type: ["A"] });
82
83 const { action } = yield* dns.setRecordSetRecords("api", "A", {
84 records: [{ value: "203.0.113.20" }],
85 });
86 yield* Hetzner.waitForZoneAction(action);
87 });
88 }).pipe(Effect.provide(Hetzner.ReadWriteDnsHttp)),
89 );
90 ```
91
92 :::caution[DNS mutations are asynchronous]
93 Every mutating RRSet call returns an `action` that Hetzner applies
94 in the background — a read right after may not see the change.
95 Always `yield* Hetzner.waitForZoneAction(action)` before depending
96 on the result. (Zone actions have their own API namespace — use
97 `waitForZoneAction`, not the compute `waitForAction`.)
98 :::
99
100 Writes also require your `HCLOUD_TOKEN` to be a **Read & Write**
101 token — a read-only token fails mutations with a typed `Forbidden`.
102
103 ## Put it together: a domain on your Load Balancer
104
105 ```typescript
106 const cert = yield* Hetzner.Certificate("cert", {
107 type: "managed",
108 domainNames: ["example.com", "www.example.com"],
109 });
110
111 yield* Hetzner.RecordSet("apex", {
112 zone: Dns,
113 name: "@",
114 type: "A",
115 records: [{ value: lb.ipv4.as<string>() }],
116 });
117 ```
118
119 The managed [Certificate](/hetzner/networking#tls-termination) is
120 issued via this same DNS, so the Zone must exist (and be delegated)
121 first — Alchemy orders that for you through the references.
122
123 ## Publish other platforms' records in Hetzner DNS
124
125 `Hetzner.DNS.Adapter()` lets a site or service on another platform publish
126 its custom-domain records in a Hetzner zone — an AWS website's certificate
127 validation and alias records, a Fly site's ACME challenge, and so on:
128
129 ```typescript
130 yield* AWS.Website.StaticSite("Site", {
131 path: "./dist",
132 domain: {
133 name: "www.example.com",
134 dns: Hetzner.DNS.Adapter({ zone: "example.com" }),
135 },
136 });
137 ```
138
139 The adapter declares `Hetzner.DNS.RecordList` resources, which add their
140 values to each RRSet and leave other values alone. Hetzner can't flatten a
141 `CNAME` at the zone apex, so point apex hostnames at addresses. See
142 [DNS Adapters](/infrastructure-as-code/dns-adapters).
143
144 ## Where next
145
146 - [Networking](/hetzner/networking) — the Load Balancer these
147 records usually point at.
148 - [`Zone`](/providers/hetzner/zone) and
149 [`RecordSet`](/providers/hetzner/recordset) references.