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

main
mdx 355 lines 9.59 KB
Raw
1 ---
2 title: Cloud Run sidecars
3 description: Run more containers next to a Cloud Run service — plain images, GCP.Run.Container resources, or your own Effect programs — and control the order they start in.
4 ---
5
6 A Cloud Run instance can run several containers. The first one takes
7 requests. The rest are sidecars, and every container in the instance
8 reaches the others on `localhost`.
9
10 A sidecar can be a plain image you list in the template, a
11 `GCP.Run.Container` that runs an image, or a `GCP.Run.Container` that
12 runs your own Effect program. This page starts with a service that runs
13 an image, then moves to Effect services, which bind their sidecars.
14
15 ## Add a sidecar
16
17 List more containers after the first in `template.containers`:
18
19 ```typescript
20 // alchemy.run.ts
21 import * as Alchemy from "alchemy";
22 import * as GCP from "@alchemy.run/gcp";
23 import * as Effect from "effect/Effect";
24
25 export default Alchemy.Stack(
26 "MyApp",
27 { providers: GCP.providers(), state: GCP.state() },
28 Effect.gen(function* () {
29 const proxy = yield* GCP.Run.Service("Proxy", {
30 template: {
31 containers: [
32 {
33 image: "us-docker.pkg.dev/cloudrun/container/hello",
34 ports: [{ containerPort: 8080 }],
35 },
36 { name: "cache", image: "docker.io/library/redis:7-alpine" },
37 ],
38 },
39 });
40 return { url: proxy.uri };
41 }),
42 );
43 ```
44
45 Only one container may have `ports`, and that container takes the
46 requests.
47
48 ## Start containers in order
49
50 Cloud Run starts every container at once, and the instance takes
51 requests as soon as the first one passes its startup probe. The first
52 requests can reach a sidecar before it listens. `dependsOn` holds a
53 container back until the containers it names pass their startup
54 probes:
55
56 ```diff lang="typescript"
57 const proxy = yield* GCP.Run.Service("Proxy", {
58 template: {
59 containers: [
60 {
61 image: "us-docker.pkg.dev/cloudrun/container/hello",
62 ports: [{ containerPort: 8080 }],
63 + dependsOn: ["cache"],
64 },
65 - { name: "cache", image: "docker.io/library/redis:7-alpine" },
66 + {
67 + name: "cache",
68 + image: "docker.io/library/redis:7-alpine",
69 + startupProbe: { tcpSocket: { port: 6379 } },
70 + },
71 ],
72 },
73 });
74 ```
75
76 Give each dependency a startup probe that checks it can serve. A
77 sidecar has no `ports`, so its probe names the port.
78
79 ## Chain dependencies
80
81 A container that others wait on can wait too. Names chain into an
82 order, and containers that don't depend on each other still start
83 together:
84
85 ```text
86 cache ✓ → app ✓ → proxy ✓ → requests
87 ```
88
89 If a dependency never passes its startup probe, the containers waiting
90 on it never start. The new revision fails and traffic stays on the
91 previous one.
92
93 `dependsOn` only orders startup. A dependency that crashes later
94 doesn't stop the containers that wait on it. Give it a `livenessProbe`
95 so Cloud Run restarts it.
96
97 ## Declare a sidecar as a Container
98
99 `GCP.Run.Container` declares a sidecar as a resource. List it in
100 `containers` like a plain spec:
101
102 ```diff lang="typescript"
103 +const cache = yield* GCP.Run.Container("Cache", {
104 + image: "docker.io/library/redis:7-alpine",
105 + port: 6379,
106 + startupProbe: { tcpSocket: {} },
107 +});
108 const proxy = yield* GCP.Run.Service("Proxy", {
109 template: {
110 containers: [
111 {
112 image: "us-docker.pkg.dev/cloudrun/container/hello",
113 ports: [{ containerPort: 8080 }],
114 - dependsOn: ["cache"],
115 + dependsOn: [cache.name],
116 },
117 - {
118 - name: "cache",
119 - image: "docker.io/library/redis:7-alpine",
120 - startupProbe: { tcpSocket: { port: 6379 } },
121 - },
122 + cache,
123 ],
124 },
125 });
126 ```
127
128 `cache.name` is an Output. Alchemy names the container from its id (or
129 its `name` prop) and puts that name into `dependsOn`, so you never
130 write it twice. `port` fills in the port the probe checks.
131
132 ## Wait for another Container
133
134 A Container's own `dependsOn` takes another Container's `name` the
135 same way:
136
137 ```diff lang="typescript"
138 +const web = yield* GCP.Run.Container("Web", {
139 + image: "docker.io/library/nginx:1.27-alpine",
140 + port: 80,
141 + startupProbe: { tcpSocket: {} },
142 +});
143 const cache = yield* GCP.Run.Container("Cache", {
144 image: "docker.io/library/redis:7-alpine",
145 port: 6379,
146 startupProbe: { tcpSocket: {} },
147 + dependsOn: [web.name],
148 });
149 const proxy = yield* GCP.Run.Service("Proxy", {
150 template: {
151 containers: [
152 {
153 image: "us-docker.pkg.dev/cloudrun/container/hello",
154 ports: [{ containerPort: 8080 }],
155 dependsOn: [cache.name],
156 },
157 cache,
158 + web,
159 ],
160 },
161 });
162 ```
163
164 ```text
165 web ✓ → cache ✓ → proxy ✓ → requests
166 ```
167
168 Every name in `dependsOn` has to belong to a container in the same
169 `containers` list.
170
171 ## Run your own program in a Container
172
173 Give a Container `main` and an Effect, and Alchemy bundles your program
174 into its own image. Return methods next to `fetch`:
175
176 ```typescript
177 // src/worker.ts
178 import * as GCP from "@alchemy.run/gcp";
179 import * as Effect from "effect/Effect";
180 import * as HttpServerResponse from "effect/http/HttpServerResponse";
181
182 export default class Worker extends GCP.Run.Container<Worker>()(
183 "Worker",
184 { main: import.meta.url, port: 3000, startupProbe: { httpGet: { path: "/health" } } },
185 Effect.gen(function* () {
186 return {
187 greet: (name: string) => Effect.succeed(`hello ${name}`),
188 fetch: Effect.succeed(HttpServerResponse.text("ok")),
189 };
190 }),
191 ) {}
192 ```
193
194 An image service lists it like any other Container:
195
196 ```diff lang="typescript"
197 +import Worker from "./src/worker.ts";
198
199 +const worker = yield* Worker;
200 const proxy = yield* GCP.Run.Service("Proxy", {
201 template: {
202 containers: [
203 {
204 image: "us-docker.pkg.dev/cloudrun/container/hello",
205 ports: [{ containerPort: 8080 }],
206 - dependsOn: [cache.name],
207 + dependsOn: [worker.name],
208 },
209 - cache,
210 - web,
211 + worker,
212 ],
213 },
214 });
215 ```
216
217 The proxy reaches it at `http://localhost:3000`.
218
219 ## Add sidecars to an Effect service
220
221 A service with `main` runs your program in the first container. Leave
222 that entry empty and list sidecars after it:
223
224 ```typescript
225 // src/api.ts
226 import * as GCP from "@alchemy.run/gcp";
227 import * as Effect from "effect/Effect";
228 import * as HttpServerResponse from "effect/http/HttpServerResponse";
229
230 export default class Api extends GCP.Run.Service<Api>()(
231 "Api",
232 {
233 main: import.meta.url,
234 template: {
235 containers: [
236 { dependsOn: ["cache"] },
237 {
238 name: "cache",
239 image: "docker.io/library/redis:7-alpine",
240 startupProbe: { tcpSocket: { port: 6379 } },
241 },
242 ],
243 },
244 },
245 Effect.gen(function* () {
246 return {
247 fetch: Effect.succeed(HttpServerResponse.text("hello")),
248 };
249 }),
250 ) {}
251 ```
252
253 ## Bind a Container
254
255 An Effect service binds a Container instead of listing it.
256 `GCP.Run.bindContainer` adds the Container to the revision and to the
257 service's `dependsOn`, and returns a client that calls it on
258 `localhost`:
259
260 ```typescript
261 // src/api.ts
262 import * as GCP from "@alchemy.run/gcp";
263 import * as Effect from "effect/Effect";
264 import * as HttpServerResponse from "effect/http/HttpServerResponse";
265 import Worker from "./worker.ts";
266
267 export default class Api extends GCP.Run.Service<Api>()(
268 "Api",
269 { main: import.meta.url },
270 Effect.gen(function* () {
271 const worker = yield* GCP.Run.bindContainer(Worker);
272 return {
273 fetch: Effect.gen(function* () {
274 return HttpServerResponse.text(yield* worker.greet("sam"));
275 }),
276 };
277 }),
278 ) {}
279 ```
280
281 `worker.greet` calls the method over HTTP, and `worker.fetch` sends a
282 request to the Container's `fetch`. For typed clients, bind with an
283 [Effect RPC](/gcp/apis/effect-rpc) schema or an
284 [Effect HTTP API](/gcp/apis/effect-http-api).
285
286 ## Bind a sidecar's port
287
288 A sidecar that doesn't speak HTTP, like Redis, is bound by port.
289 Declare it in its own module:
290
291 ```typescript
292 // src/cache.ts
293 import * as GCP from "@alchemy.run/gcp";
294
295 export const Cache = GCP.Run.Container("Cache", {
296 image: "docker.io/library/redis:7-alpine",
297 port: 6379,
298 startupProbe: { tcpSocket: {} },
299 });
300 ```
301
302 `GCP.Run.bindPort` adds it to the revision and the `dependsOn` the
303 same way, and returns its address:
304
305 ```diff lang="typescript"
306 +import { Cache } from "./cache.ts";
307
308 Effect.gen(function* () {
309 + const cache = yield* GCP.Run.bindPort(Cache, 6379);
310 + // cache.url === "http://localhost:6379"
311 return {
312 fetch: Effect.succeed(HttpServerResponse.text("hello")),
313 };
314 }),
315 ```
316
317 ## Bind a Container from a Container
318
319 A Container's program binds sidecars the same way a service does.
320 Here `Worker` binds `Cache`:
321
322 ```diff lang="typescript"
323 +import { Cache } from "./cache.ts";
324
325 export default class Worker extends GCP.Run.Container<Worker>()(
326 "Worker",
327 { main: import.meta.url, port: 3000, startupProbe: { httpGet: { path: "/health" } } },
328 Effect.gen(function* () {
329 + const cache = yield* GCP.Run.bindPort(Cache, 6379);
330 return {
331 greet: (name: string) => Effect.succeed(`hello ${name}`),
332 fetch: Effect.succeed(HttpServerResponse.text("ok")),
333 };
334 }),
335 ) {}
336 ```
337
338 `Cache` joins whichever revision `Worker` runs in, and `Worker` waits
339 for it. That holds whether a service binds `Worker` or lists it:
340
341 ```text
342 cache ✓ → worker ✓ → api ✓ → requests
343 ```
344
345 Other bindings in a Container work as they do in a service: their
346 environment variables land on the Container, and their roles go to the
347 service's account. A Container's own `dependsOn` is kept alongside the
348 names its bindings add.
349
350 ## List or bind
351
352 A service that runs an image lists its sidecars, and names what each
353 one waits for with `dependsOn`. A service or Container that runs your
354 program binds its sidecars, which gives it a client and orders startup
355 for it.