@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 216 lines 7.04 KB
Raw
1 ---
2 title: "Part 5: Deploy to Your Own Cluster"
3 description: Point the tutorial stack at a hosted Kubernetes cluster such as GKE, AKS, EKS, k3s, or anything in your kubeconfig. Keep the local cluster for development with stages, and clean up.
4 sidebar:
5 order: 5
6 ---
7
8 import Terminal from "../../../../components/Terminal.astro";
9 import PackageManagers from "../../../../components/PackageManagers.astro";
10
11 Everything you built in Parts 1–4 runs on a cluster on your machine.
12 None of it is specific to that cluster. The Deployment, the Effect
13 Jobs, and the Helm chart only need a `cluster` to run on. In this part
14 you'll point the stack at a cluster of your own, while keeping the
15 local one for development.
16
17 ## Choose a cluster
18
19 You need a cluster you can reach with `kubectl`. If you don't have
20 one, create it with your platform's tools and follow its section of
21 [Setup](/kubernetes/setup#connect-to-your-cluster):
22
23 - **GKE.** `gcloud container clusters get-credentials` writes the
24 context. See [Setup → GKE](/kubernetes/setup#gke).
25 - **AKS.** `az aks get-credentials` writes the context. See
26 [Setup → AKS](/kubernetes/setup#aks).
27 - **k3s, RKE2, DigitalOcean, and others.** Use the kubeconfig the
28 platform gives you. See
29 [Setup → k3s, RKE2, and other distributions](/kubernetes/setup#k3s-rke2-and-other-distributions).
30 - **Amazon EKS.** Create the cluster in this same Stack. See
31 [Amazon EKS](/kubernetes/clusters/eks).
32
33 Then note its context name:
34
35 ```sh
36 kubectl config get-contexts
37 ```
38
39 The rest of this part uses a context named `prod`.
40
41 ## Choose a registry
42
43 The smoke test and health check are built from your code, so they
44 need a registry the cluster's nodes can pull from. The local cluster
45 came with one. For yours, pick a repository you can push to, such as
46 `ghcr.io/<you>` on GitHub, and log in:
47
48 ```sh
49 echo $GITHUB_TOKEN | docker login ghcr.io -u <you> --password-stdin
50 ```
51
52 Make the pushed images readable by the cluster. Use a public package,
53 or [pull credentials](/kubernetes/clusters/registries#let-the-nodes-pull)
54 for a private one. See [Container registries](/kubernetes/clusters/registries).
55
56 ## Pick the cluster by stage
57
58 Every Alchemy deploy targets a **stage**. By default that's your own
59 `live_<you>` stage, or you can name one with `--stage`. Keep the
60 local cluster for your stage and use the hosted cluster for `prod`. In `src/infra.ts`,
61 replace the `Cluster` declaration:
62
63 ```diff lang="typescript"
64 +import { Stage } from "alchemy";
65 import * as Kubernetes from "@alchemy.run/kubernetes";
66 import * as Effect from "effect/Effect";
67
68 -export const Cluster = Kubernetes.LocalCluster("Cluster", {
69 - name: "alchemy",
70 -});
71 +export const Cluster = Effect.gen(function* () {
72 + const stage = yield* Stage;
73 + if (stage === "prod") {
74 + return Kubernetes.KubeConfig({
75 + context: "prod",
76 + registry: { server: "ghcr.io/you" },
77 + });
78 + }
79 + return yield* Kubernetes.LocalCluster("Cluster", { name: "alchemy" });
80 +});
81 ```
82
83 For `prod`, `Kubernetes.KubeConfig` connects through the `prod`
84 context and pushes images to `ghcr.io/you`. Every other stage keeps
85 the local cluster. Nothing else changes. The Namespace, Deployment,
86 Jobs, and chart all take whichever cluster `Cluster` returns.
87
88 ## Set the node architecture
89
90 Images are built for `amd64` nodes by default. If your cluster runs
91 Arm nodes, such as AWS Graviton or Ampere, say so:
92
93 ```diff lang="typescript"
94 return Kubernetes.KubeConfig({
95 context: "prod",
96 registry: { server: "ghcr.io/you" },
97 + architecture: "arm64",
98 });
99 ```
100
101 ## Stop returning the local context
102
103 `cluster.context` only exists on the local cluster. Remove it from
104 the Stack's outputs in `alchemy.run.ts`:
105
106 ```diff lang="typescript"
107 return {
108 - context: cluster.context,
109 namespace: web.namespace,
110 service: web.serviceName,
111 smokeTest: smokeTest.jobName,
112 };
113 ```
114
115 ## Deploy to prod
116
117 <PackageManagers run="alchemy deploy --stage prod" />
118
119 <Terminal content={`[u]Plan[/u]: [g]5 to create[/g]
120
121 [g]+[/g] [b]HealthCheck[/b] [d](Kubernetes.Job)[/d]
122 [g]+[/g] [b]MetricsServer[/b] [d](Kubernetes.HelmChart)[/d]
123 [g]+[/g] [b]Namespace[/b] [d](Kubernetes.Manifest)[/d]
124 [g]+[/g] [b]SmokeTest[/b] [d](Kubernetes.Job)[/d]
125 [g]+[/g] [b]Web[/b] [d](Kubernetes.Deployment)[/d]
126
127 Proceed?
128 ◉ Yes ○ No
129 [d]Pushed ghcr.io/you/mycluster-smoketest-prod-…:7a31fba1…[/d]
130 [d]Pushed ghcr.io/you/mycluster-healthcheck-prod-…:27bde98e…[/d]
131 [g]✓[/g] [b]Namespace[/b] [d](Kubernetes.Manifest)[/d] [g]created[/g]
132 [g]✓[/g] [b]MetricsServer[/b] [d](Kubernetes.HelmChart)[/d] [g]created[/g]
133 [g]✓[/g] [b]Web[/b] [d](Kubernetes.Deployment)[/d] [g]created[/g]
134 [g]✓[/g] [b]SmokeTest[/b] [d](Kubernetes.Job)[/d] [g]created[/g]
135 [g]✓[/g] [b]HealthCheck[/b] [d](Kubernetes.Job)[/d] [g]created[/g]`} />
136
137 `prod` has its own state, so this deploy creates everything on the
138 hosted cluster and leaves your local stage alone. There's no
139 `LocalCluster` in the plan, because the `prod` stage never declares
140 one.
141
142 ## Check the hosted cluster
143
144 The same commands work, with the `prod` context:
145
146 ```sh
147 kubectl --context prod -n my-app get deployments,jobs,cronjobs
148 kubectl --context prod -n my-app logs job/<smokeTest>
149 ```
150
151 ## Skip what the platform already has
152
153 Many hosted clusters include metrics-server, and applying the chart
154 over it would take ownership of its objects. Install the chart only
155 where it's missing:
156
157 ```diff lang="typescript"
158 +import { Stage } from "alchemy";
159 import * as Kubernetes from "@alchemy.run/kubernetes";
160 ```
161
162 ```diff lang="typescript"
163 yield* HealthCheck;
164
165 -const metricsServer = yield* Kubernetes.HelmChart("MetricsServer", {
166 - cluster,
167 - // ...
168 -});
169 +const stage = yield* Stage;
170 +if (stage !== "prod") {
171 + yield* Kubernetes.HelmChart("MetricsServer", {
172 + cluster,
173 + // ...
174 + });
175 +}
176 ```
177
178 Deploying `prod` again now plans the chart for deletion there.
179
180 ## Clean up the local cluster
181
182 Destroy your own stage to remove everything on your machine,
183 including the kind cluster and its registry:
184
185 <PackageManagers run="alchemy destroy" />
186
187 Alchemy deletes the resources in reverse dependency order and the
188 cluster last. The next `alchemy deploy` recreates it in about 30
189 seconds. Run `alchemy destroy --stage prod` when you want to remove
190 the hosted deployment too.
191
192 ## Recap
193
194 You started with an empty directory and now have:
195
196 - A stack that runs on a local cluster for development and on a
197 hosted cluster in `prod`
198 - Effect programs built and pushed to whichever registry the cluster
199 uses
200 - A Deployment, a Helm chart, and Jobs that don't depend on where
201 they run
202
203 ## Where next
204
205 - **[Setup](/kubernetes/setup).** Connect to more kinds of clusters,
206 check RBAC permissions, and deploy from CI.
207 - **[Container registries](/kubernetes/clusters/registries).** Push
208 credentials, pull access, and node architecture.
209 - **[Deployments](/kubernetes/workloads/deployments).** Effect HTTP
210 servers, Service types, and the pod template escape hatch.
211 - **[Jobs & CronJobs](/kubernetes/workloads/jobs).** Everything about
212 image and Effect Jobs.
213 - **[Stages](/environments/stages).** Per-developer, preview, and
214 production stages.
215 - **[Amazon EKS](/kubernetes/clusters/eks).** Create the cluster in
216 the same Stack and use AWS bindings.