@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 254 lines 8.5 KB
Raw
1 ---
2 title: Jobs & CronJobs
3 description: Run work to completion with Kubernetes.Job, as a container image or as an Effect program, and on a schedule as a CronJob. Covers how Job names, re-runs, retries, and cleanup work.
4 ---
5
6 [`Kubernetes.Job`](/providers/kubernetes/job) runs work until it
7 finishes, such as migrations, seeds, smoke tests, and reports. It
8 applies a **ServiceAccount** and a Kubernetes **Job**. When you set
9 `schedule`, it applies a **CronJob** instead.
10
11 A Job runs one of two things:
12
13 - **A container image.** It can be any image, with its own
14 entrypoint and arguments. Nothing about the program needs to know
15 about Alchemy.
16 - **An Effect program.** It's an Effect you write in the same
17 codebase, bundled into an image and run in the pod. It can read
18 configuration, call other services, and use bindings.
19
20 ## Run a container image
21
22 Pass `image`, and optionally `command` and `args`:
23
24 ```typescript
25 const migrate = yield* Kubernetes.Job("Migrate", {
26 cluster,
27 name: "migrate",
28 namespace: "apps",
29 image: "ghcr.io/acme/migrator:v3",
30 args: ["up"],
31 env: { DATABASE_URL: db.connectionString },
32 backoffLimit: 2,
33 });
34 ```
35
36 The cluster's nodes pull the image as written, so this works on any
37 cluster. It takes the same image, environment, resource, and pod
38 template props as a [Deployment](/kubernetes/workloads/deployments),
39 without the port and Service.
40
41 ## Run an Effect program
42
43 Declare the Job in its own module with `main: import.meta.url` and an
44 implementation that returns `{ run }`. This example assumes
45 `src/infra.ts` exports the cluster and an `Api` Deployment, as
46 described in [Why the props are an Effect](#why-the-props-are-an-effect):
47
48 ```typescript
49 // src/Seed.ts
50 import * as Kubernetes from "@alchemy.run/kubernetes";
51 import * as Effect from "effect/Effect";
52 import { Api, Cluster } from "./infra.ts";
53
54 export default Kubernetes.Job(
55 "Seed",
56 Effect.gen(function* () {
57 const cluster = yield* Cluster;
58 return {
59 cluster,
60 main: import.meta.url,
61 name: "seed",
62 backoffLimit: 2,
63 };
64 }),
65 Effect.gen(function* () {
66 const api = yield* Api;
67 const apiService = yield* api.serviceName;
68
69 return {
70 run: Effect.gen(function* () {
71 const service = yield* apiService;
72 yield* Effect.log(`seeding records through ${service}`);
73 }).pipe(Effect.orDie),
74 };
75 }),
76 );
77 ```
78
79 Then yield it from your Stack with `yield* Seed`.
80
81 On deploy, Alchemy bundles the module, builds an image for the
82 cluster's nodes, pushes it to the cluster's registry, and applies the
83 Job. In the pod, a generated entrypoint runs `run` to completion and
84 exits:
85
86 - **Success.** The process exits 0 and the Job completes.
87 - **Failure.** A failed or defected `run` exits non-zero, which
88 Kubernetes counts against `backoffLimit`.
89
90 Yielding a resource attribute such as `api.serviceName` in the
91 implementation binds it to the Job. Alchemy resolves the value at
92 deploy time and delivers it to the pod, and `run` reads it by
93 yielding the returned Effect. The binding also makes the Job depend
94 on the resource.
95
96 `run` can use `HttpClient` to call other services. It can also use the Bun
97 platform services, such as the file system and child processes. A
98 Job has nowhere to return errors, so `run` must handle them or turn
99 them into defects with `Effect.orDie`.
100
101 ### What the cluster needs
102
103 The image has to be pushed somewhere the nodes can pull from:
104
105 - **[`Kubernetes.LocalCluster`](/kubernetes/clusters/local).** It has
106 a built-in registry, so there's nothing to configure.
107 - **Any other cluster.** It needs a
108 [`registry`](/kubernetes/clusters/registries) on the connection,
109 such as `ghcr.io/acme`.
110 - **[Amazon EKS](/kubernetes/clusters/eks).** It uses ECR, which is
111 created for you.
112
113 The generated entrypoint imports `@effect/platform-bun`, so install
114 it alongside `alchemy` and `effect`.
115
116 ### Why the props are an Effect
117
118 The props are an Effect so the module can `yield*` shared resources
119 that the Stack also uses, such as the cluster, a namespace, or a
120 Deployment to call. Declare those shared resources at module scope in
121 a file such as `src/infra.ts`. Each `yield*` resolves to the same
122 resource. When the props don't reference anything, pass a plain
123 object instead.
124
125 ### Tagged Jobs
126
127 The tagged form declares the Job as a class, so other code can depend
128 on it by type and the implementation is provided as a Layer:
129
130 ```typescript
131 export class Backfill extends Kubernetes.Job<Backfill>()("Backfill") {}
132
133 export default Backfill.make(
134 { cluster, main: import.meta.url, backoffLimit: 1 },
135 Effect.gen(function* () {
136 return { run: Effect.log("backfilling") };
137 }),
138 );
139 ```
140
141 ## When a Job runs
142
143 Kubernetes starts a Job as soon as it's created. Alchemy creates a
144 new Job whenever what it runs changes. A Job runs:
145
146 - On the first deploy.
147 - On every deploy that changes its spec. That means the image,
148 `args`, `env` values, resources, or pod template. `env` values
149 include Outputs that resolved to new values.
150 - For Effect programs, on every deploy that changes the program or
151 anything it imports.
152
153 A Job doesn't run on deploys that leave it unchanged. The deploy
154 doesn't wait for the Job to finish. Follow it with
155 `kubectl wait --for=condition=complete job/<jobName>` and
156 `kubectl logs job/<jobName>`.
157
158 ## Job names
159
160 A Job's pod template can't change after the Job is created, so
161 Alchemy names each one-shot Job after its spec. `jobName` is the base
162 name plus the first eight characters of a hash, for example
163 `seed-5133e709`. A changed spec produces a new name. Alchemy applies
164 the new Job and deletes the previous one along with its pods.
165
166 Kubernetes caps Job names at 63 characters, so the base name is
167 truncated to fit. Read the current name from the `jobName`
168 attribute rather than predicting it.
169
170 ## Retries, restarts, and cleanup
171
172 - `backoffLimit` sets how many failed pods Kubernetes retries before
173 marking the Job failed.
174 - `restartPolicy` sets what happens after a failure. `"Never"` is the
175 default and starts a new pod. `"OnFailure"` restarts the container
176 in place.
177 - `ttlSecondsAfterFinished` makes Kubernetes delete the finished Job
178 this many seconds after it completes or fails.
179
180 With `ttlSecondsAfterFinished`, Kubernetes removes the Job object on
181 its own. Alchemy tracks the Job through its ServiceAccount, so a
182 garbage-collected Job is not treated as missing and does not run
183 again until its spec changes.
184
185 ## Run on a schedule
186
187 Set `schedule` to a standard five-field cron expression and Alchemy
188 applies a `CronJob` instead. It works for both kinds of Job:
189
190 ```typescript
191 // an image
192 const nightly = yield* Kubernetes.Job("NightlyReport", {
193 cluster,
194 name: "nightly-report",
195 image: "ghcr.io/acme/reports:v2",
196 schedule: "0 3 * * *",
197 backoffLimit: 1,
198 ttlSecondsAfterFinished: 86_400,
199 });
200 ```
201
202 ```typescript
203 // an Effect program
204 export default Kubernetes.Job(
205 "Heartbeat",
206 Effect.gen(function* () {
207 const cluster = yield* Cluster;
208 return {
209 cluster,
210 main: import.meta.url,
211 name: "heartbeat",
212 schedule: "*/5 * * * *",
213 };
214 }),
215 Effect.gen(function* () {
216 return { run: Effect.log("still here") };
217 }),
218 );
219 ```
220
221 `backoffLimit`, `restartPolicy`, and `ttlSecondsAfterFinished` apply
222 to each Job the CronJob starts. A CronJob can be updated in place, so
223 it keeps a stable name. That name is the base name, truncated to 52
224 characters so Kubernetes can append its own suffix to each Job it
225 starts. Changing the program updates the CronJob's image, and the
226 next scheduled run uses it.
227
228 Schedules are evaluated in the time zone of the cluster's controller
229 manager, which is UTC on most hosted clusters. The CronJob
230 `timeZone` field isn't exposed as a prop. If you need it, write the
231 CronJob as a [Manifest](/kubernetes/objects/manifests).
232
233 Adding or removing `schedule` switches between a one-shot Job and a
234 CronJob. Alchemy applies the new object and deletes the old one.
235
236 ## Attributes
237
238 - `jobName` is the name of the Job or CronJob object.
239 - `kind` is `"Job"` or `"CronJob"`.
240 - `schedule` is the cron schedule, or `undefined` for a one-shot Job.
241 - `serviceAccountName` is the ServiceAccount the pods run as.
242 - `namespace` is the namespace of the objects.
243 - `imageUri` is the image the pods run.
244 - `connection` is the cluster connection.
245 - `kubernetesObjects` holds references to the applied objects.
246
247 ## Where next
248
249 - **[Tutorial part 3](/kubernetes/tutorial/part-3).** Builds an
250 Effect smoke test and a scheduled Effect Job on a local cluster.
251 - **[Configuration & bindings](/kubernetes/workloads/bindings).**
252 Pass values and credentials to a Job.
253 - **[`Job` reference](/providers/kubernetes/job).** Lists every prop
254 and attribute.