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

main
mdx 163 lines 4.31 KB
Raw
1 ---
2 title: GKE
3 description: Run Effect programs as Kubernetes Deployments and Jobs on a GKE Autopilot cluster, with bindings granted through Workload Identity.
4 ---
5
6 import PackageManagers from "../../../../components/PackageManagers.astro";
7
8 export const pkgs = "@alchemy.run/kubernetes";
9
10 GKE runs your Effect program as a Kubernetes workload. You declare the
11 cluster, then a `Kubernetes.Deployment` or `Kubernetes.Job` on it.
12 Alchemy builds the image, pushes it to Artifact Registry, and applies
13 the objects. No YAML, no `kubectl`.
14
15 ## Install
16
17 <PackageManagers add={pkgs} />
18
19 Merge the Kubernetes providers next to GCP's:
20
21 ```typescript
22 // alchemy.run.ts
23 providers: Layer.mergeAll(GCP.providers(), Kubernetes.providers()),
24 ```
25
26 ## Create a cluster
27
28 An Autopilot cluster sizes its nodes from your pods, so there are no
29 node pools to manage:
30
31 ```typescript
32 // src/infra.ts
33 import * as GCP from "@alchemy.run/gcp";
34
35 export const Cluster = GCP.Container.Cluster("Cluster", {
36 location: "us-central1",
37 autopilot: true,
38 releaseChannel: "REGULAR",
39 });
40 ```
41
42 Autopilot needs a region, not a zone. Creating a cluster takes about
43 ten minutes.
44
45 ## Deploy an Effect program
46
47 A Deployment takes the same `fetch` handler as a Cloud Run service:
48
49 ```typescript
50 // src/Api.ts
51 import * as GCP from "@alchemy.run/gcp";
52 import * as Kubernetes from "@alchemy.run/kubernetes";
53 import * as Effect from "effect/Effect";
54 import * as HttpServerResponse from "effect/http/HttpServerResponse";
55 import { Cluster, Entries } from "./infra.ts";
56
57 export class Api extends Kubernetes.Deployment<Api>()("Api") {}
58
59 export default Api.make(
60 Effect.gen(function* () {
61 return {
62 cluster: yield* Cluster,
63 main: import.meta.url,
64 port: 3000,
65 replicas: 2,
66 serviceType: "LoadBalancer" as const,
67 resources: {
68 requests: { cpu: "250m", memory: "512Mi" },
69 limits: { cpu: "250m", memory: "512Mi" },
70 },
71 };
72 }),
73 Effect.gen(function* () {
74 const db = yield* GCP.Firestore.ReadWriteDatabase(Entries);
75
76 return {
77 fetch: Effect.gen(function* () {
78 const page = yield* db.list("entries", { pageSize: 100 });
79 return yield* HttpServerResponse.json(page.documents);
80 }).pipe(Effect.orDie),
81 };
82 }).pipe(Effect.provide(GCP.Firestore.ReadWriteDatabaseHttp)),
83 );
84 ```
85
86 `serviceType: "LoadBalancer"` gives the Deployment a public IP.
87 `api.url` includes the port: `http://<ip>:3000`.
88
89 ## Add it to the Stack
90
91 Provide the Deployment's layer and yield the class:
92
93 ```typescript
94 // alchemy.run.ts
95 import ApiLive, { Api } from "./src/Api.ts";
96
97 export default Alchemy.Stack(
98 "MyApp",
99 {
100 providers: Layer.mergeAll(GCP.providers(), Kubernetes.providers()),
101 state: GCP.state(),
102 },
103 Effect.gen(function* () {
104 const api = yield* Api;
105 return { url: api.url };
106 }).pipe(Effect.provide(ApiLive)),
107 );
108 ```
109
110 ## Bindings use Workload Identity
111
112 `ReadWriteDatabase` grants the role to the Deployment's Kubernetes
113 service account directly. Pods get Google tokens from the GKE metadata
114 server. There are no keys and no Google service account to create.
115
116 A new conditional grant can take a few minutes to reach Firestore. Set
117 `backoffLimit` on Jobs so Kubernetes retries until it lands.
118
119 ## Run a Job
120
121 `Kubernetes.Job` takes a `run` entry and runs once when it is applied:
122
123 ```typescript
124 // src/Seed.ts
125 export default Kubernetes.Job(
126 "Seed",
127 Effect.gen(function* () {
128 return { cluster: yield* Cluster, main: import.meta.url, backoffLimit: 6 };
129 }),
130 Effect.gen(function* () {
131 const db = yield* GCP.Firestore.WriteDatabase(Entries);
132 return {
133 run: db.set("entries/hello", { message: "first!" }).pipe(Effect.orDie),
134 };
135 }).pipe(Effect.provide(GCP.Firestore.WriteDatabaseHttp)),
136 );
137 ```
138
139 Add `schedule: "0 3 * * *"` to the props to make it a CronJob.
140
141 ## Deploy an existing image
142
143 ```typescript
144 const web = yield* Kubernetes.Deployment("Web", {
145 cluster,
146 image: "nginx:1.27",
147 port: 80,
148 serviceType: "LoadBalancer",
149 });
150 ```
151
152 ## Example
153
154 [`examples/gcp-gke`](https://github.com/alchemy-run/alchemy/tree/main/examples/gcp-gke)
155 is a guestbook on Autopilot: an Effect API, an nginx Deployment, a
156 seed Job, and a namespace from a raw manifest.
157
158 ## Where next
159
160 - [Kubernetes](/kubernetes) — Deployments, Jobs, manifests, and Helm
161 charts in depth.
162 - [Container reference](/providers/gcp/container#cluster) — every
163 cluster prop.