@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 405 lines 11.2 KB
Raw
1 ---
2 title: "Part 3: Effect Jobs"
3 description: Write a smoke test as an Effect program, run it as a Kubernetes Job that Alchemy builds and pushes for you, watch it re-run when the program changes, and schedule it as a CronJob.
4 sidebar:
5 order: 3
6 ---
7
8 import Terminal from "../../../../components/Terminal.astro";
9 import PackageManagers from "../../../../components/PackageManagers.astro";
10
11 In [Part 2](/kubernetes/tutorial/part-2) you configured podinfo in its
12 own namespace. Now you'll write your own code and run it on the
13 cluster. You'll start with a smoke test, written in Effect, that
14 checks podinfo is healthy after every change. Then you'll run the
15 same program on a schedule.
16
17 ## Share resources between files
18
19 The Job will live in its own file and needs the cluster, the
20 namespace, and the Deployment. Move them out of `alchemy.run.ts` into
21 `src/infra.ts`:
22
23 ```typescript
24 // src/infra.ts
25 import * as Kubernetes from "@alchemy.run/kubernetes";
26 import * as Effect from "effect/Effect";
27
28 export const Cluster = Kubernetes.LocalCluster("Cluster", {
29 name: "alchemy",
30 });
31
32 export const Namespace = Effect.gen(function* () {
33 const cluster = yield* Cluster;
34 return yield* Kubernetes.Manifest("Namespace", {
35 cluster,
36 manifest: {
37 apiVersion: "v1",
38 kind: "Namespace",
39 metadata: { name: "my-app" },
40 },
41 });
42 });
43
44 export const Web = Effect.gen(function* () {
45 const cluster = yield* Cluster;
46 const namespace = yield* Namespace;
47 return yield* Kubernetes.Deployment("Web", {
48 cluster,
49 name: "web",
50 namespace: namespace.name,
51 image: "ghcr.io/stefanprodan/podinfo:6.15.0",
52 port: 9898,
53 replicas: 2,
54 serviceType: "ClusterIP",
55 env: {
56 PODINFO_UI_MESSAGE: "hello from alchemy",
57 },
58 resources: {
59 requests: { cpu: "10m", memory: "32Mi" },
60 limits: { memory: "64Mi" },
61 },
62 });
63 });
64 ```
65
66 A resource declared at module scope is an Effect you can `yield*`
67 from anywhere. Every `yield*` resolves to the same resource, so the
68 Stack and the Job share one cluster, one namespace, and one
69 Deployment.
70
71 ## Use them from the Stack
72
73 Replace the inline declarations in `alchemy.run.ts`:
74
75 ```diff lang="typescript"
76 import * as Alchemy from "alchemy";
77 import * as Kubernetes from "@alchemy.run/kubernetes";
78 import * as Effect from "effect/Effect";
79 +import { Cluster, Web } from "./src/infra.ts";
80
81 export default Alchemy.Stack(
82 "MyCluster",
83 {
84 providers: Kubernetes.providers(),
85 state: Alchemy.localState(),
86 },
87 Effect.gen(function* () {
88 - const cluster = yield* Kubernetes.LocalCluster("Cluster", {
89 - name: "alchemy",
90 - });
91 - const namespace = yield* Kubernetes.Manifest("Namespace", { ... });
92 - const web = yield* Kubernetes.Deployment("Web", { ... });
93 + const cluster = yield* Cluster;
94 + const web = yield* Web;
95
96 return {
97 context: cluster.context,
98 namespace: web.namespace,
99 service: web.serviceName,
100 };
101 }),
102 );
103 ```
104
105 The logical IDs haven't changed, so a deploy now would show no
106 changes. Moving code between files doesn't move resources.
107
108 ## Declare the Job
109
110 Create `src/SmokeTest.ts`. A `Kubernetes.Job` that runs your own code
111 takes two Effects, one for its props and one for its implementation:
112
113 ```typescript
114 // src/SmokeTest.ts
115 import * as Kubernetes from "@alchemy.run/kubernetes";
116 import * as Effect from "effect/Effect";
117 import { Cluster, Namespace } from "./infra.ts";
118
119 export default Kubernetes.Job(
120 "SmokeTest",
121 Effect.gen(function* () {
122 const cluster = yield* Cluster;
123 const namespace = yield* Namespace;
124 return {
125 cluster,
126 main: import.meta.url,
127 name: "smoke-test",
128 namespace: namespace.name,
129 };
130 }),
131 Effect.gen(function* () {
132 return {
133 run: Effect.log("smoke test"),
134 };
135 }),
136 );
137 ```
138
139 `main: import.meta.url` says the program is this module. On deploy,
140 Alchemy bundles it, builds a container image, and pushes it to the
141 local cluster's registry. In the pod, a generated entrypoint runs
142 `run` to completion and exits.
143
144 ## Bind the service URL
145
146 Inside the cluster, a Service is reachable at
147 `<service>.<namespace>.svc.cluster.local`. Build that URL from the
148 Deployment's attributes in the Job's implementation:
149
150 ```diff lang="typescript"
151 import * as Kubernetes from "@alchemy.run/kubernetes";
152 +import * as Output from "alchemy/Output";
153 import * as Effect from "effect/Effect";
154 -import { Cluster, Namespace } from "./infra.ts";
155 +import { Cluster, Namespace, Web } from "./infra.ts";
156 ```
157
158 ```diff lang="typescript"
159 Effect.gen(function* () {
160 + const web = yield* Web;
161 + const webUrl = yield* Output.interpolate`http://${web.serviceName}.${web.namespace}.svc.cluster.local:${web.port}`;
162 +
163 return {
164 run: Effect.log("smoke test"),
165 };
166 }),
167 ```
168
169 `Output.interpolate` builds a string from the Deployment's
170 attributes. Yielding it in the implementation binds the value to the
171 Job. Alchemy resolves it at deploy time, delivers it to the pod, and
172 gives you `webUrl`, an Effect that returns the URL at runtime. The
173 binding also makes the Job depend on the Deployment.
174
175 ## Check the service
176
177 Now write the test. Read the bound URL and call podinfo's health
178 endpoint with Effect's `HttpClient`:
179
180 ```diff lang="typescript"
181 import * as Effect from "effect/Effect";
182 +import * as HttpClient from "effect/http/HttpClient";
183 +import * as HttpClientResponse from "effect/http/HttpClientResponse";
184 import { Cluster, Namespace, Web } from "./infra.ts";
185 ```
186
187 ```diff lang="typescript"
188 return {
189 - run: Effect.log("smoke test"),
190 + run: Effect.gen(function* () {
191 + const url = yield* webUrl;
192 + const response = yield* HttpClient.get(`${url}/healthz`).pipe(
193 + Effect.flatMap(HttpClientResponse.filterStatusOk),
194 + );
195 + yield* Effect.log(`${url} is healthy (${response.status})`);
196 + }).pipe(Effect.orDie),
197 };
198 ```
199
200 `HttpClientResponse.filterStatusOk` turns any non-2xx response into
201 an error.
202 `Effect.orDie` turns errors into a failed process. A Job has nowhere
203 to return an error to, so failing is how it reports one.
204
205 ## Retry while podinfo starts
206
207 The Job can start before podinfo's pods are ready. Retry the request
208 a few times with a backoff:
209
210 ```diff lang="typescript"
211 import * as Effect from "effect/Effect";
212 +import * as Schedule from "effect/Schedule";
213 import * as HttpClient from "effect/http/HttpClient";
214 ```
215
216 ```diff lang="typescript"
217 const response = yield* HttpClient.get(`${url}/healthz`).pipe(
218 Effect.flatMap(HttpClientResponse.filterStatusOk),
219 + Effect.retry({
220 + schedule: Schedule.exponential("1 second"),
221 + times: 5,
222 + }),
223 );
224 ```
225
226 ## Retries and cleanup
227
228 Tell Kubernetes how to treat the finished Job:
229
230 ```diff lang="typescript"
231 return {
232 cluster,
233 main: import.meta.url,
234 name: "smoke-test",
235 namespace: namespace.name,
236 + backoffLimit: 2,
237 + ttlSecondsAfterFinished: 600,
238 };
239 ```
240
241 `backoffLimit` is how many times Kubernetes retries a failed pod
242 before marking the Job failed. `ttlSecondsAfterFinished` lets
243 Kubernetes delete the finished Job after ten minutes. Alchemy tracks
244 the Job through its ServiceAccount, so a cleaned-up Job isn't
245 treated as missing or run again.
246
247 ## Run it from the Stack
248
249 Yield the Job in `alchemy.run.ts` and return its name:
250
251 ```diff lang="typescript"
252 +import SmokeTest from "./src/SmokeTest.ts";
253 import { Cluster, Web } from "./src/infra.ts";
254 ```
255
256 ```diff lang="typescript"
257 const cluster = yield* Cluster;
258 const web = yield* Web;
259 +const smokeTest = yield* SmokeTest;
260
261 return {
262 context: cluster.context,
263 namespace: web.namespace,
264 service: web.serviceName,
265 + smokeTest: smokeTest.jobName,
266 };
267 ```
268
269 ## Deploy
270
271 <PackageManagers run="alchemy deploy" />
272
273 <Terminal content={`[u]Plan[/u]: [g]1 to create[/g]
274
275 [g]+[/g] [b]SmokeTest[/b] [d](Kubernetes.Job)[/d]
276
277 Proceed?
278 ◉ Yes ○ No
279 [d]Bundling SmokeTest program...[/d]
280 [d]Building container image localhost:5001/mycluster-smoketest-live-you-…:112df477…[/d]
281 [d]Pushed localhost:5001/mycluster-smoketest-live-you-…:112df477…[/d]
282 [g]✓[/g] [b]SmokeTest[/b] [d](Kubernetes.Job)[/d] [g]created[/g]
283 {
284 [s2]context: "kind-alchemy",
285 [s2]namespace: "my-app",
286 [s2]service: "web",
287 [s2]smokeTest: "smoke-test-4dceddd5",
288 }`} />
289
290 Kubernetes starts a Job as soon as it's created. The deploy doesn't
291 wait for it to finish. Follow it with `kubectl`:
292
293 ```sh
294 kubectl --context kind-alchemy -n my-app wait --for=condition=complete job/smoke-test-4dceddd5
295 kubectl --context kind-alchemy -n my-app logs job/smoke-test-4dceddd5
296 ```
297
298 ```text
299 Kubernetes Job bootstrap starting...
300 INFO http://web.my-app.svc.cluster.local:9898 is healthy (200)
301 ```
302
303 ## Change the program
304
305 The Job is named `smoke-test-4dceddd5`, not `smoke-test`. Kubernetes
306 doesn't allow a Job's pod template to change after it's created, so
307 Alchemy names each Job after a hash of what it runs. Change the
308 program and you get a new Job. Leave it alone and nothing re-runs.
309
310 Change the log message and deploy:
311
312 ```diff lang="typescript"
313 -yield* Effect.log(`${url} is healthy (${response.status})`);
314 +yield* Effect.log(`${url} responded ${response.status}`);
315 ```
316
317 <Terminal content={`[u]Plan[/u]: [y]1 to update[/y]
318
319 [y]~[/y] [b]SmokeTest[/b] [d](Kubernetes.Job)[/d]
320
321 Proceed?
322 ◉ Yes ○ No
323 [g]✓[/g] [b]SmokeTest[/b] [d](Kubernetes.Job)[/d] [y]updated[/y]
324 {
325 [s2]context: "kind-alchemy",
326 [s2]namespace: "my-app",
327 [s2]service: "web",
328 [s2]smokeTest: "smoke-test-81931ef0",
329 }`} />
330
331 Alchemy rebuilt the image, ran `smoke-test-81931ef0`, and deleted
332 the previous Job. Deploy once more without changes and the plan is
333 empty.
334
335 ## Run it on a schedule
336
337 A health check is more useful when it keeps running. Copy
338 `src/SmokeTest.ts` to `src/HealthCheck.ts`, rename it, and replace
339 the retry settings with a `schedule`:
340
341 ```diff lang="typescript"
342 export default Kubernetes.Job(
343 - "SmokeTest",
344 + "HealthCheck",
345 Effect.gen(function* () {
346 // ...
347 return {
348 cluster,
349 main: import.meta.url,
350 - name: "smoke-test",
351 + name: "health-check",
352 namespace: namespace.name,
353 - backoffLimit: 2,
354 - ttlSecondsAfterFinished: 600,
355 + schedule: "*/5 * * * *",
356 };
357 }),
358 ```
359
360 `schedule` takes a standard five-field cron expression. Setting it
361 makes Alchemy create a Kubernetes `CronJob`, which starts a Job from
362 the same image every five minutes. A CronJob can be updated in place, so
363 it keeps the plain name `health-check`.
364
365 ## Deploy the CronJob
366
367 Yield it from the Stack:
368
369 ```diff lang="typescript"
370 +import HealthCheck from "./src/HealthCheck.ts";
371 import SmokeTest from "./src/SmokeTest.ts";
372 ```
373
374 ```diff lang="typescript"
375 const smokeTest = yield* SmokeTest;
376 +yield* HealthCheck;
377 ```
378
379 Deploy, wait for the next five-minute mark, and list the runs:
380
381 ```sh
382 kubectl --context kind-alchemy -n my-app get cronjobs,jobs
383 ```
384
385 ```text
386 NAME SCHEDULE TIMEZONE SUSPEND ACTIVE LAST SCHEDULE AGE
387 cronjob.batch/health-check */5 * * * * <none> False 0 12s 4m
388
389 NAME STATUS COMPLETIONS DURATION AGE
390 job.batch/health-check-29835710 Complete 1/1 5s 12s
391 job.batch/smoke-test-81931ef0 Complete 1/1 4s 6m
392 ```
393
394 ## Recap
395
396 You now have:
397
398 - Shared resources in `src/infra.ts`, used by the Stack and by the
399 Job
400 - A smoke test written in Effect, built and pushed by Alchemy, that
401 runs whenever the program changes
402 - The same program running every five minutes as a CronJob
403
404 In [Part 4](/kubernetes/tutorial/part-4), you'll install a cluster
405 add-on from a Helm chart.