@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 321 lines 10.9 KB
Raw
1 ---
2 title: ECS
3 description: Run containers on AWS with ECS and Fargate — Task definitions that run to completion, Services that keep containers running behind a load balancer, with images bundled from an Effect program, built from your Dockerfile, or mirrored from a registry.
4 ---
5
6 **ECS** (Elastic Container Service) is AWS's managed container
7 orchestrator: you describe a container — image, CPU, memory — and
8 ECS runs it. With **Fargate**, AWS also provides the machines, so
9 there are no servers to manage.
10
11 ECS has four primitives:
12
13 - A **Cluster** is the space your containers run in.
14 - A **Task Definition** is the blueprint: which image, how much
15 CPU and memory, which IAM roles, which ports.
16 - A **Task** is a running container launched from a Task
17 Definition. It runs until its process exits.
18 - A **Service** keeps a set number of Tasks running — restarting
19 ones that stop, optionally routing traffic to them through a
20 load balancer.
21
22 Alchemy models these directly:
23 [`Cluster`](/providers/aws/ecs/cluster),
24 [`Task`](/providers/aws/ecs/task) — a task definition plus
25 everything needed to build and publish its image — and
26 [`Service`](/providers/aws/ecs/service). Each can run a plain
27 container image, or an Effect program that Alchemy bundles into
28 one.
29
30 ## Run a Task
31
32 The simplest `Task` runs a pre-built registry image — no Effect
33 runtime in the container:
34
35 ```typescript
36 // alchemy.run.ts
37 import * as AWS from "@alchemy.run/aws";
38
39 const migrate = yield* AWS.ECS.Task("DbMigrate", {
40 image: "public.ecr.aws/docker/library/busybox:stable",
41 command: ["sh", "-c", "echo done"],
42 cpu: 256,
43 memory: 512,
44 });
45 ```
46
47 Deploying a `Task` automates the container supply chain:
48 Alchemy provisions the **task and execution IAM roles**, a
49 **CloudWatch log group**, and a **generated ECR repository**
50 holding the image, then registers a Fargate task definition. Each
51 deploy registers a new immutable revision.
52
53 The log group keeps events forever by default. Set
54 `logging: { retention: "2 weeks" }` on a `Task` or `Service` to
55 expire them; the duration is rounded up to the nearest value
56 CloudWatch Logs supports, and `"forever"` clears an existing policy.
57
58 ## Three image sources
59
60 The image comes from exactly one of three sources, flat on the
61 props:
62
63 - `image` — run a pre-built registry reference, mirrored into ECR
64 (pull → tag → push, content-addressed).
65 - `context` — build your own Dockerfile with your
66 [local Docker](/docker/setup). `dockerfile` is always a **path**,
67 defaulting to `${context}/Dockerfile`:
68
69 ```typescript
70 const render = yield* AWS.ECS.Task("RenderJob", {
71 context: "./render",
72 dockerfile: "./render/Dockerfile.gpu",
73 cpu: 1024,
74 memory: 4096,
75 });
76 ```
77
78 - `main` — bundle an inline Effect program into a generated image.
79 Compose with `image` to pick the environment base (default
80 `oven/bun:1`), or with an inline `dockerfile`
81 (`Dockerfile.inline`) when the environment needs extra build
82 steps.
83
84 :::tip
85 `runtimePlatform.cpuArchitecture` picks the architecture the task
86 runs on in Fargate (default `X86_64`). Alchemy builds or mirrors
87 the image for whatever the task definition declares, regardless of
88 the machine you build on. Declaring `"ARM64"` runs the task on
89 Graviton — cheaper per vCPU, and image builds happen to be native
90 (no emulation) on Apple Silicon machines.
91 :::
92
93 ## Run an Effect program in a Task
94
95 Pass `main: import.meta.url` and a constructor Effect whose impl
96 returns `{ run }` — the program runs to completion when the
97 container starts, then the container exits. Bindings work exactly
98 as on Lambda, attaching environment variables and IAM policy
99 statements to the task:
100
101 ```typescript
102 const drainer = yield* AWS.ECS.Task(
103 "QueueDrainer",
104 { main: import.meta.url, image: "oven/bun:1", cpu: 256, memory: 512 },
105 Effect.gen(function* () {
106 const receive = yield* AWS.SQS.ReceiveMessage(queue);
107 return {
108 run: Effect.gen(function* () {
109 // runs to completion, then the container exits
110 const batch = yield* receive({ MaxNumberOfMessages: 10 });
111 }),
112 };
113 }),
114 );
115 ```
116
117 The tagged form
118 (`class Reindexer extends AWS.ECS.Task<Reindexer, Shape>()("Reindexer") {}`
119 + `Reindexer.make(props, impl)`) works exactly as it does on
120 Lambda and Cloudflare Workers.
121
122 ## Invoke and schedule Tasks
123
124 A `Task` is the target of the ECS control-plane bindings. From a
125 Lambda function, a Service, or any other host, bind
126 [`RunTask`](/providers/aws/ecs/runtask) in the **Construction phase** —
127 this grants the host `ecs:RunTask` plus `iam:PassRole` on the
128 task's roles — then call it from a handler at **runtime**, where
129 the cluster and task definition ARNs are injected automatically:
130
131 ```typescript
132 const api = yield* AWS.Lambda.Function(
133 "Api",
134 { main: import.meta.url, functionUrl: true },
135 Effect.gen(function* () {
136 // Construction: bind the launch (IAM grants happen here)
137 const runTask = yield* AWS.ECS.RunTask(cluster, task);
138
139 return {
140 fetch: Effect.gen(function* () {
141 // runtime: launch a task per request
142 const response = yield* runTask({
143 launchType: "FARGATE",
144 networkConfiguration: {
145 awsvpcConfiguration: { subnets: [subnetId] },
146 },
147 });
148 return yield* HttpServerResponse.json({
149 taskArn: response.tasks?.[0]?.taskArn,
150 });
151 }),
152 };
153 }),
154 );
155 ```
156
157 For cron-style execution, `AWS.ECS.every` provisions an
158 EventBridge rule (plus the invoke role) that runs the task on a
159 schedule — plain-English durations normalize to `rate(...)`, and
160 `cron(...)` expressions pass through as-is:
161
162 ```typescript
163 yield* AWS.ECS.every("NightlyJob", "cron(0 3 * * ? *)", {
164 cluster,
165 task: nightlyTask,
166 subnets: [privateSubnet1.subnetId, privateSubnet2.subnetId],
167 securityGroups: [jobSecurityGroup.groupId],
168 });
169 ```
170
171 ## Keep a server running with a Service
172
173 A `Service` keeps `desiredCount` copies of a container alive.
174 It takes the same three image sources as `Task` — synthesizing
175 its own task definition — and `loadBalancer: true` provisions a
176 public **Application Load Balancer**, target group, and listener
177 in front of it:
178
179 ```typescript
180 const cluster = yield* AWS.ECS.Cluster("AppCluster", {});
181
182 const nginx = yield* AWS.ECS.Service("Edge", {
183 cluster,
184 image: "public.ecr.aws/nginx/nginx:1.27",
185 port: 80,
186 desiredCount: 2,
187 loadBalancer: true,
188 });
189
190 return { url: nginx.url }; // http://<alb-dns-name>
191 ```
192
193 Networking is optional to start: when `vpcId`/`subnets` are
194 omitted the account's **default VPC** (and its per-AZ subnets) is
195 used, and when `securityGroups` is omitted with
196 `loadBalancer: true`, Alchemy provisions a security group that
197 admits the listener port. For a real deployment, build a
198 dedicated VPC with the [`Network`](/providers/aws/ec2/network)
199 helper and pass `vpcId` + `subnets` — see
200 [VPC & networking](/aws/networking).
201
202 An effectful `Service` is the server counterpart: where a `Task`
203 impl returns `{ run }`, a `Service` impl returns `{ fetch }`:
204
205 ```typescript
206 const api = yield* AWS.ECS.Service(
207 "Api",
208 { cluster, main: import.meta.url, port: 3000, desiredCount: 2, cpu: 256, memory: 512 },
209 Effect.gen(function* () {
210 const putItem = yield* AWS.DynamoDB.PutItem(table);
211 return {
212 fetch: Effect.gen(function* () {
213 return yield* HttpServerResponse.json({ ok: true });
214 }),
215 };
216 }).pipe(Effect.provide(AWS.DynamoDB.PutItemHttp)),
217 );
218 ```
219
220 ## Reuse a Task's definition
221
222 A `Service` can also deploy an existing `Task`'s definition
223 instead of owning an image — shared image, roles, and config; the
224 Service adds `desiredCount`, load balancing, and deployment
225 configuration:
226
227 ```typescript
228 const api = yield* AWS.ECS.Service("Api", {
229 cluster,
230 task: apiTask,
231 desiredCount: 2,
232 loadBalancer: true,
233 });
234 ```
235
236 Most service configuration — desired count, task definition
237 revision, network config, deployment settings, load balancers —
238 updates **in place** as a rolling deployment; only truly
239 immutable aspects (service name, cluster, scheduling strategy,
240 deployment controller type, switching between `launchType` and
241 `capacityProviderStrategy`) replace the service. For
242 cost-sensitive workers, swap `launchType` (default `"FARGATE"`)
243 for a `capacityProviderStrategy` mixing `FARGATE_SPOT` and
244 `FARGATE` — see the
245 [`Service` reference](/providers/aws/ecs/service) for the
246 placement, deployment, and Service Connect knobs.
247
248 ## Run background work
249
250 Containers are always-on, so an effectful container can do more
251 than answer requests. Yield `ServerHost` and register
252 long-running loops with `host.run` — they execute alongside the
253 HTTP handler for the life of the container:
254
255 ```diff lang="typescript"
256 import * as AWS from "@alchemy.run/aws";
257 +import { ServerHost } from "alchemy/Runtime/Process";
258 import * as Effect from "effect/Effect";
259 +import * as Schedule from "effect/Schedule";
260
261 Effect.gen(function* () {
262 + const host = yield* ServerHost;
263 +
264 + yield* host.run(
265 + Effect.log("heartbeat").pipe(
266 + Effect.repeat(Schedule.spaced("30 seconds")),
267 + Effect.asVoid,
268 + ),
269 + );
270 +
271 return {
272 fetch: Effect.gen(function* () {
273 // ...
274 }),
275 };
276 }),
277 ```
278
279 Use this for polling loops, queue drainers, or connections that
280 stay open across requests.
281
282 ## Process scope vs request scope
283
284 An ECS container is a **real process**, and its instance scope
285 reflects that: the bundled program runs under a root scope that
286 closes when the process shuts down gracefully, so resources
287 acquired in the constructor — the connection a `host.run` loop holds open, a
288 warm pool shared across requests — are genuinely released on exit.
289 Serverless runtimes only approximate this: workerd never closes
290 its instance scope at all, and Lambda gets a best-effort 500 ms
291 SIGTERM window; a server gets a real graceful shutdown (a hard
292 kill still skips finalizers, as in any process).
293
294 Each HTTP request still gets its own request `Scope`, released when
295 the response settles — the same per-event contract as every other
296 runtime. See
297 [Instance scope vs request scope](/infrastructure-as-effects/runtime#instance-scope-vs-request-scope)
298 for the model across all runtimes.
299
300 ## Bindings
301
302 `Task` and `Service` declare the same binding contract as a
303 Lambda `Function`: bindings attach **environment variables and
304 IAM policy statements**, which Alchemy folds into the container
305 environment and the task role. The ECS control-plane bindings
306 (`RunTask`, `StopTask`, `ListTasks`, `DescribeTasks`) work from
307 Lambda functions and from other containers — useful for a
308 function that fans work out to containers.
309
310 ## Where next
311
312 - [Choosing a runtime](/aws/compute/choosing-a-runtime) — when Lambda,
313 EKS, or EC2 fits better than ECS.
314 - [VPC & networking](/aws/networking) — what the `Network`
315 helper creates, and the primitives underneath it.
316 - [EKS](/aws/compute/eks) — the same platform model on managed
317 Kubernetes.
318 - [`Task` reference](/providers/aws/ecs/task),
319 [`Service` reference](/providers/aws/ecs/service),
320 [`Cluster` reference](/providers/aws/ecs/cluster) — every prop
321 and attribute.