@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 278 lines 7.16 KB
Raw
1 ---
2 title: Cloud Run
3 description: Run an Effect HTTP service on Cloud Run with GCP.Function — public or private URLs, environment, scaling, and bindings that grant IAM.
4 ---
5
6 `GCP.Function` runs an Effect program as a Cloud Run service. You
7 write a `fetch` handler, Alchemy builds a container image, pushes it
8 to Artifact Registry, and deploys a new revision. The service scales
9 with traffic and down to zero.
10
11 :::note
12 The image is built on your machine, so Docker has to be running when
13 you deploy. To deploy without Docker, use
14 [Cloud Functions](/gcp/compute/cloud-functions).
15 :::
16
17 ## Declare a service
18
19 ```typescript
20 // src/Api.ts
21 import * as GCP from "@alchemy.run/gcp";
22 import * as Effect from "effect/Effect";
23 import * as HttpServerResponse from "effect/http/HttpServerResponse";
24
25 export default class Api extends GCP.Function<Api>()(
26 "Api",
27 { main: import.meta.url },
28 Effect.gen(function* () {
29 return {
30 fetch: Effect.succeed(HttpServerResponse.text("Hello from Cloud Run!")),
31 };
32 }),
33 ) {}
34 ```
35
36 `GCP.Function` is the same class as `GCP.Run.Service`. `main` names
37 the file to bundle.
38
39 ## Add it to the Stack
40
41 ```typescript
42 // alchemy.run.ts
43 import * as Alchemy from "alchemy";
44 import * as GCP from "@alchemy.run/gcp";
45 import * as Effect from "effect/Effect";
46 import Api from "./src/Api.ts";
47
48 export default Alchemy.Stack(
49 "MyApp",
50 { providers: GCP.providers(), state: GCP.state() },
51 Effect.gen(function* () {
52 const api = yield* Api;
53 return { url: api.uri };
54 }),
55 );
56 ```
57
58 `api.uri` is the service's `https://….run.app` URL.
59
60 ## Make it public
61
62 A new service only accepts callers with a Google identity token and
63 `roles/run.invoker`. Set `invokerIamDisabled` to let anyone call it:
64
65 ```diff lang="typescript"
66 export default class Api extends GCP.Function<Api>()(
67 "Api",
68 - { main: import.meta.url },
69 + { main: import.meta.url, invokerIamDisabled: true },
70 ```
71
72 Leave it off for internal services. Another service calls a private
73 one with [`InvokeService`](/gcp/networking/private-services).
74
75 ## Read the request
76
77 `fetch` is an Effect. Get the request from `HttpServerRequest`:
78
79 ```typescript
80 import { HttpServerRequest } from "effect/http/HttpServerRequest";
81
82 fetch: Effect.gen(function* () {
83 const request = yield* HttpServerRequest;
84 const url = new URL(request.originalUrl, "http://localhost");
85
86 if (request.method === "POST" && url.pathname === "/echo") {
87 const body = yield* request.json;
88 return yield* HttpServerResponse.json(body);
89 }
90
91 return HttpServerResponse.text("Not found", { status: 404 });
92 }).pipe(Effect.orDie),
93 ```
94
95 For typed routes, use [Effect HTTP](/gcp/apis/effect-http-api) or
96 [Effect RPC](/gcp/apis/effect-rpc). Both produce a `fetch` handler.
97
98 ## Bind resources
99
100 Declare a resource in the constructor and bind it. The binding returns
101 a client and grants the service the role it needs on that resource:
102
103 ```typescript
104 Effect.gen(function* () {
105 const links = yield* GCP.Firestore.Database("Links", {
106 type: "FIRESTORE_NATIVE",
107 });
108 const db = yield* GCP.Firestore.ReadWriteDatabase(links);
109
110 return {
111 fetch: Effect.gen(function* () {
112 const doc = yield* db.get("links/home");
113 return yield* HttpServerResponse.json(doc?.fields ?? {});
114 }).pipe(Effect.orDie),
115 };
116 }).pipe(Effect.provide(GCP.Firestore.ReadWriteDatabaseHttp)),
117 ```
118
119 Each service gets its own service account. Bindings grant roles to it
120 and nothing else. See [How bindings grant IAM](/gcp/security/iam).
121
122 ## Pass environment variables
123
124 `env` sets plain container environment variables:
125
126 ```typescript
127 {
128 main: import.meta.url,
129 env: {
130 LOG_LEVEL: "debug",
131 API_BASE: other.uri,
132 },
133 }
134 ```
135
136 Values can be Outputs from other resources. For credentials, use
137 [Secret Manager](/gcp/security/secrets-kms) instead.
138
139 ## Choose the region
140
141 A service deploys to the Stack's region (your profile's region, else
142 `us-central1`). Pin it with `location`:
143
144 ```typescript
145 { main: import.meta.url, location: "europe-west1" }
146 ```
147
148 Changing `location` replaces the service.
149
150 ## Tune scaling
151
152 Keep warm instances to avoid cold starts, or cap the maximum:
153
154 ```typescript
155 {
156 main: import.meta.url,
157 scaling: { minInstanceCount: 1, maxInstanceCount: 20 },
158 }
159 ```
160
161 ## Size the container
162
163 Set CPU, memory, timeout, and concurrency on the revision template:
164
165 ```typescript
166 {
167 main: import.meta.url,
168 template: {
169 timeout: "60s",
170 maxInstanceRequestConcurrency: 40,
171 containers: [{ resources: { limits: { cpu: "2", memory: "1Gi" } } }],
172 },
173 }
174 ```
175
176 Every template change rolls out a new revision.
177
178 ## Check health
179
180 Cloud Run's default startup probe passes as soon as the port accepts a
181 connection. Give it an HTTP probe so a revision only takes traffic once
182 the program can serve:
183
184 ```typescript
185 {
186 main: import.meta.url,
187 template: {
188 containers: [
189 {
190 startupProbe: { httpGet: { path: "/health" }, periodSeconds: 2, failureThreshold: 30 },
191 livenessProbe: { httpGet: { path: "/health" }, periodSeconds: 10 },
192 },
193 ],
194 },
195 }
196 ```
197
198 A failing liveness probe restarts the container. Probes can also use
199 `tcpSocket` or `grpc`. Remove `startupProbe` to go back to the default.
200
201 ## Add a sidecar
202
203 Containers after the first run next to `main` and reach it on
204 `localhost`. Only the first container takes requests:
205
206 ```typescript
207 {
208 main: import.meta.url,
209 template: {
210 containers: [
211 { dependsOn: ["cache"] },
212 {
213 name: "cache",
214 image: "docker.io/library/redis:7-alpine",
215 startupProbe: { tcpSocket: { port: 6379 } },
216 },
217 ],
218 },
219 }
220 ```
221
222 `dependsOn` starts `main` after `cache` passes its startup probe.
223 [Sidecars](/gcp/compute/sidecars) covers start order, running your own
224 program as a sidecar, and binding it for a typed client.
225
226 ## Receive events
227
228 Event sources make Google call your service. Each one creates the
229 delivery (a push subscription, a scheduler job, an Eventarc trigger)
230 and lets only that delivery in, so the service can stay private:
231
232 ```typescript
233 yield* GCP.PubSub.consumeTopicMessages(Orders, (messages) =>
234 messages.pipe(Stream.runForEach(({ message }) => handle(message))),
235 );
236 // …provided with Effect.provide(GCP.Run.TopicEventSource)
237 ```
238
239 See [Pub/Sub](/gcp/messaging/pubsub),
240 [Cloud Scheduler](/gcp/messaging/scheduler),
241 [Storage events](/gcp/messaging/storage-events), and
242 [Eventarc](/gcp/messaging/eventarc).
243
244 ## Run without `main`
245
246 Leave out `main` to deploy any container image:
247
248 ```typescript
249 const hello = yield* GCP.Run.Service("Hello", {
250 invokerIamDisabled: true,
251 template: {
252 containers: [{ image: "us-docker.pkg.dev/cloudrun/container/hello" }],
253 },
254 });
255 ```
256
257 An image service can list sidecars too; see
258 [Sidecars](/gcp/compute/sidecars).
259
260 ## Destroy
261
262 `alchemy destroy` deletes the service, its image repository, and the
263 service account Alchemy created for it, and revokes that account's
264 roles.
265
266 ## Example
267
268 [`examples/gcp-cloud-run-api`](https://github.com/alchemy-run/alchemy/tree/main/examples/gcp-cloud-run-api)
269 is a link shortener on one service: Firestore for links, Secret
270 Manager for the API key.
271
272 ## Where next
273
274 - [Firestore](/gcp/data/firestore) — the datastore most services start
275 with.
276 - [Cloud Run jobs](/gcp/compute/jobs) — work that runs to completion.
277 - [Run reference](/providers/gcp/run#service) — every prop and
278 attribute.