@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 236 lines 6.73 KB
Raw
1 ---
2 title: "Part 1: Your First Deployment"
3 description: Create a Stack, start a Kubernetes cluster on your machine with Kubernetes.LocalCluster, deploy a replicated HTTP service with Kubernetes.Deployment, and reach it with kubectl.
4 sidebar:
5 order: 1
6 ---
7
8 import Terminal from "../../../../components/Terminal.astro";
9 import PackageManagers from "../../../../components/PackageManagers.astro";
10
11 export const pkgs = `alchemy@latest @alchemy.run/kubernetes@latest effect @effect/platform-bun @effect/platform-node`;
12
13 In this first part you'll create a Stack, start a Kubernetes cluster
14 on your machine, and deploy a replicated HTTP service. You won't
15 write a line of YAML.
16
17 The tutorial runs on a local cluster so you can follow it without a
18 cloud account. Everything you build works on any Kubernetes cluster.
19 [Part 5](/kubernetes/tutorial/part-5) shows how to point it at yours.
20
21 ## Prerequisites
22
23 - [Bun](https://bun.sh) or Node.js 22+
24 - [Docker](https://docs.docker.com/get-started/get-docker/),
25 [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation),
26 and [`kubectl`](https://kubernetes.io/docs/tasks/tools/)
27
28 kind runs Kubernetes inside Docker containers. Alchemy runs it for
29 you, but it must be installed. On macOS, run `brew install kind`.
30
31 ## Create a project
32
33 Start with an empty directory and initialize a `package.json`:
34
35 <PackageManagers init dir="my-cluster" />
36
37 ## Install dependencies
38
39 Install `alchemy@latest`, `@alchemy.run/kubernetes`, and `effect`:
40
41 <PackageManagers add={pkgs} />
42
43 ## Create the Stack
44
45 Every Alchemy program starts with a `Stack`. A Stack is a collection
46 of Resources, the providers that manage them, and a state store that
47 remembers what was deployed. Create `alchemy.run.ts`:
48
49 ```typescript
50 // alchemy.run.ts
51 import * as Alchemy from "alchemy";
52 import * as Kubernetes from "@alchemy.run/kubernetes";
53 import * as Effect from "effect/Effect";
54
55 export default Alchemy.Stack(
56 "MyCluster",
57 {
58 providers: Kubernetes.providers(),
59 state: Alchemy.localState(),
60 },
61 Effect.gen(function* () {
62 // resources go here
63 }),
64 );
65 ```
66
67 `Kubernetes.providers()` teaches Alchemy how to create, update, and
68 delete Kubernetes resources. `Alchemy.localState()` keeps state in a
69 `.alchemy/` directory next to your code.
70
71 ## Start a local cluster
72
73 Declare a cluster as the first resource:
74
75 ```diff lang="typescript"
76 Effect.gen(function* () {
77 - // resources go here
78 + const cluster = yield* Kubernetes.LocalCluster("Cluster", {
79 + name: "alchemy",
80 + });
81 }),
82 ```
83
84 `Kubernetes.LocalCluster` is a resource like any other. Deploying
85 creates a [kind](https://kind.sigs.k8s.io) cluster named `alchemy` in
86 Docker, and destroying deletes it. It also starts an image registry
87 next to the cluster, which you'll use in
88 [Part 3](/kubernetes/tutorial/part-3).
89
90 ## Add a Deployment
91
92 Declare a replicated HTTP server on the cluster. This one runs
93 [podinfo](https://github.com/stefanprodan/podinfo), a small demo
94 service that answers with JSON:
95
96 ```diff lang="typescript"
97 const cluster = yield* Kubernetes.LocalCluster("Cluster", {
98 name: "alchemy",
99 });
100
101 + const web = yield* Kubernetes.Deployment("Web", {
102 + cluster,
103 + name: "web",
104 + image: "ghcr.io/stefanprodan/podinfo:6.15.0",
105 + port: 9898,
106 + replicas: 2,
107 + serviceType: "ClusterIP",
108 + });
109 }),
110 ```
111
112 `cluster` tells the Deployment where to run. Every Kubernetes
113 resource takes one, and passing the `LocalCluster` makes the
114 Deployment depend on it, so Alchemy creates the cluster first.
115
116 `"Web"` is the resource's logical ID in your program. `name: "web"`
117 is the name of the objects in the cluster. Without it, Alchemy
118 generates one from the stack, stage, and logical ID, such as
119 `mycluster-web-live-you-…`. Set it before the first deploy, because a
120 Deployment keeps the name it was created with.
121
122 `image` is a registry reference the cluster pulls as written, and
123 `port` is both the container port and the Service port.
124
125 ## Keep the Service internal
126
127 `serviceType` defaults to `LoadBalancer`, which asks the cluster for
128 an external load balancer and waits up to about three minutes for
129 one to be assigned. A local cluster has no load balancer, so the
130 example sets `serviceType: "ClusterIP"`. The Service gets a
131 cluster-internal address only, and you'll reach it through
132 `kubectl port-forward`.
133
134 ## Return Stack outputs
135
136 Return the names you'll need from the command line:
137
138 ```diff lang="typescript"
139 const web = yield* Kubernetes.Deployment("Web", {
140 cluster,
141 name: "web",
142 image: "ghcr.io/stefanprodan/podinfo:6.15.0",
143 port: 9898,
144 replicas: 2,
145 serviceType: "ClusterIP",
146 });
147
148 + return {
149 + context: cluster.context,
150 + namespace: web.namespace,
151 + service: web.serviceName,
152 + };
153 }),
154 ```
155
156 `cluster.context` is the kubeconfig context kind created for the
157 cluster, which you'll pass to `kubectl`.
158
159 ## Deploy
160
161 <PackageManagers run="alchemy deploy" />
162
163 <Terminal content={`[u]Plan[/u]: [g]2 to create[/g]
164
165 [g]+[/g] [b]Cluster[/b] [d](Kubernetes.LocalCluster)[/d]
166 [g]+[/g] [b]Web[/b] [d](Kubernetes.Deployment)[/d]
167
168 Proceed?
169 ◉ Yes ○ No
170 [d]Creating kind cluster alchemy (about 30 seconds)...[/d]
171 [d]Starting image registry on localhost:5001...[/d]
172 [g]✓[/g] [b]Cluster[/b] [d](Kubernetes.LocalCluster)[/d] [g]created[/g]
173 [g]✓[/g] [b]Web[/b] [d](Kubernetes.Deployment)[/d] [g]created[/g]
174 {
175 [s2]context: "kind-alchemy",
176 [s2]namespace: "default",
177 [s2]service: "web",
178 }`} />
179
180 Alchemy created the cluster, then applied three objects to it. They
181 are a `ServiceAccount`, a `Deployment` with two replicas, and a
182 `Service` in front of them. The deploy finishes as soon as the API server
183 accepts the objects. Kubernetes pulls the image and starts the pods
184 in the background.
185
186 ## Verify it worked
187
188 kind added a `kind-alchemy` context to your kubeconfig. Wait for the
189 rollout, then forward a local port to the Service:
190
191 ```sh
192 kubectl --context kind-alchemy rollout status deployment/web
193 kubectl --context kind-alchemy port-forward service/web 9898:9898
194 ```
195
196 In a second terminal:
197
198 ```sh
199 curl localhost:9898
200 ```
201
202 ```json
203 {
204 "hostname": "web-857dfd7659-7pfv2",
205 "version": "6.15.0",
206 "message": "greetings from podinfo v6.15.0",
207 ...
208 }
209 ```
210
211 Run `alchemy deploy` again. Nothing changed, so the plan is empty:
212
213 <Terminal content={`[u]Plan[/u]: [d]no changes[/d]
214
215 {
216 [s2]context: "kind-alchemy",
217 [s2]namespace: "default",
218 [s2]service: "web",
219 }`} />
220
221 This is the core loop. You declare resources in code, deploy, and
222 Alchemy works out what changed.
223
224 ## Recap
225
226 You now have:
227
228 - A Kubernetes cluster on your machine, declared as a resource
229 - A two-replica podinfo Deployment behind a `ClusterIP` Service,
230 created with no YAML
231 - Stack outputs naming the kubeconfig context, the Service, and its
232 namespace
233
234 In [Part 2](/kubernetes/tutorial/part-2), you'll give the app its own
235 namespace and configure it with environment variables and resource
236 limits.