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