@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 311 lines 10.3 KB
Raw
1 ---
2 title: Setup
3 description: Install Alchemy and connect it to a Kubernetes cluster, whether a local cluster on your machine, any cluster in your kubeconfig, or an explicit connection for CI. Then add a registry for images built from your code.
4 ---
5
6 import PackageManagers from "../../../components/PackageManagers.astro";
7
8 export const pkgs = `alchemy@latest @alchemy.run/kubernetes@latest effect @effect/platform-bun @effect/platform-node`;
9
10 Alchemy deploys to any Kubernetes cluster whose API server it can
11 reach. That includes a cluster on your machine, GKE, AKS, EKS,
12 DigitalOcean, k3s, or an on-prem fleet. This page covers what you
13 need before the first deploy. You need the `alchemy` and `@alchemy.run/kubernetes` packages, a
14 cluster to deploy to, a registry for images built from your code,
15 and permission to manage objects in the cluster.
16
17 ## Prerequisites
18
19 - [Bun](https://bun.sh) or Node.js 22+
20 - [Docker](https://docs.docker.com/get-started/get-docker/), to build
21 images from your code and to run a local cluster
22 - A cluster. Use [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation)
23 for a local one, or credentials for a hosted one. Hosted
24 credentials are usually a kubeconfig context that already works
25 with `kubectl`.
26 - [`helm`](https://helm.sh/docs/intro/install/), only if you install
27 [Helm charts](/kubernetes/objects/helm-charts)
28 - [`kubectl`](https://kubernetes.io/docs/tasks/tools/) is useful for
29 checking access and inspecting what Alchemy deploys. Alchemy talks
30 to the Kubernetes API directly and never runs it.
31
32 ## Create a project directory
33
34 <PackageManagers init dir="my-cluster" />
35
36 ## Install
37
38 <PackageManagers add={pkgs} />
39
40 ## Add the providers
41
42 Every Stack that uses Kubernetes resources needs
43 `Kubernetes.providers()`:
44
45 ```typescript
46 // alchemy.run.ts
47 import * as Alchemy from "alchemy";
48 import * as Kubernetes from "@alchemy.run/kubernetes";
49 import * as Effect from "effect/Effect";
50
51 export default Alchemy.Stack(
52 "MyApp",
53 {
54 providers: Kubernetes.providers(),
55 state: Alchemy.localState(),
56 },
57 Effect.gen(function* () {
58 // Kubernetes resources go here
59 }),
60 );
61 ```
62
63 It registers the `LocalCluster`, `Deployment`, `Job`, `Manifest`, and
64 `HelmChart` providers, plus authentication for kubeconfig,
65 bearer-token, client-certificate, and exec-plugin connections. There is no
66 `alchemy profile` step for Kubernetes. Credentials come from the
67 connection each resource carries.
68
69 ## Connect to your cluster
70
71 Each resource's `cluster` prop says where it runs and how Alchemy
72 authenticates. Find your kind of cluster below.
73
74 ### A cluster on your machine
75
76 If you don't have a cluster yet, let Alchemy create one.
77 [`Kubernetes.LocalCluster`](/kubernetes/clusters/local) runs a
78 [kind](https://kind.sigs.k8s.io) cluster in Docker with an image
79 registry built in:
80
81 ```typescript
82 const cluster = yield* Kubernetes.LocalCluster("Cluster", {
83 name: "alchemy",
84 });
85
86 const web = yield* Kubernetes.Deployment("Web", {
87 cluster,
88 image: "ghcr.io/stefanprodan/podinfo:6.15.0",
89 port: 9898,
90 serviceType: "ClusterIP",
91 });
92 ```
93
94 Install kind first. On macOS run `brew install kind`, or see
95 [kind's install guide](https://kind.sigs.k8s.io/docs/user/quick-start/#installation).
96 The [tutorial](/kubernetes/tutorial/part-1) uses a local cluster
97 throughout.
98
99 ### Any cluster with a kubeconfig
100
101 If `kubectl` already works against the cluster, Alchemy can use the
102 same kubeconfig context. List your contexts and pick the one you
103 deploy to:
104
105 ```sh
106 kubectl config get-contexts
107 ```
108
109 Pass its name in your program:
110
111 ```typescript
112 const cluster = Kubernetes.KubeConfig({ context: "prod-us-east" });
113
114 const web = yield* Kubernetes.Deployment("Web", {
115 cluster,
116 image: "ghcr.io/acme/web:1.4.0",
117 port: 8080,
118 });
119 ```
120
121 Alchemy reads the kubeconfig at deploy time. It uses `path` if you
122 pass one, otherwise the first entry of `$KUBECONFIG`, otherwise
123 `~/.kube/config`. Name the context explicitly, because the file's
124 `current-context` changes whenever someone runs
125 `kubectl config use-context`.
126
127 Contexts created by a cloud CLI call an `exec` credential plugin for
128 short-lived tokens. The plugin must be installed and logged in on
129 every machine that deploys, including CI runners.
130
131 ### GKE
132
133 Write a context with the Google Cloud CLI:
134
135 ```sh
136 gcloud container clusters get-credentials <cluster> --region <region>
137 ```
138
139 The context is named `gke_<project>_<region>_<cluster>` and calls
140 `gke-gcloud-auth-plugin`. Install the plugin with
141 `gcloud components install gke-gcloud-auth-plugin`.
142
143 ### AKS
144
145 Write a context with the Azure CLI:
146
147 ```sh
148 az aks get-credentials --name <cluster> --resource-group <group>
149 ```
150
151 The context is named after the cluster. For clusters that use
152 Microsoft Entra ID authentication, install
153 [`kubelogin`](https://azure.github.io/kubelogin/) and convert the
154 context to use your Azure CLI login:
155
156 ```sh
157 kubelogin convert-kubeconfig -l azurecli
158 ```
159
160 ### EKS
161
162 EKS clusters can be created and targeted from the same Stack, with
163 ECR images and AWS bindings built in. See
164 [Amazon EKS](/kubernetes/clusters/eks).
165
166 ### k3s, RKE2, and other distributions
167
168 Self-managed distributions write a kubeconfig on the server. k3s
169 writes it to `/etc/rancher/k3s/k3s.yaml` and RKE2 writes it to
170 `/etc/rancher/rke2/rke2.yaml`. Copy it to the deploying machine and
171 change its `server` address from `127.0.0.1` to one your machine can
172 reach. Then point `path` at it:
173
174 ```typescript
175 const cluster = Kubernetes.KubeConfig({
176 path: "./k3s.yaml",
177 context: "default",
178 });
179 ```
180
181 Hosted Kubernetes services such as DigitalOcean, Linode, and Scaleway
182 provide a kubeconfig from their console or CLI. Use it the same way.
183
184 ### Existing local clusters
185
186 A kind, minikube, or Docker Desktop cluster you started yourself adds
187 a context to `~/.kube/config`. The context is named `kind-<name>`,
188 `minikube`, or `docker-desktop`, and it works like any other
189 kubeconfig cluster. Local clusters usually have no load balancer, so
190 use `serviceType: "ClusterIP"` or `"NodePort"` for Deployments.
191
192 ### Without a kubeconfig
193
194 Some environments have no kubeconfig, such as a CI job or a
195 bootstrap script. There, describe the connection directly with an
196 endpoint and an `auth` descriptor:
197
198 ```typescript
199 import * as Config from "effect/Config";
200
201 const token = yield* Config.String("K8S_TOKEN");
202
203 const cluster: Kubernetes.Connection = {
204 endpoint: "https://k8s.internal.example.com:6443",
205 certificateAuthorityData: "LS0tLS1CRUdJTi…", // base64-encoded PEM
206 auth: { kind: "token", token },
207 };
208 ```
209
210 `auth` can also be a client certificate (`kind: "client-cert"`) or an
211 exec plugin (`kind: "exec"`). A token or certificate in a raw
212 connection is stored in Alchemy's state. Changing it replaces the
213 resources that use it, so prefer kubeconfig or exec connections for
214 long-lived stacks. See
215 [Connecting to clusters](/kubernetes/clusters/connecting) for every
216 option.
217
218 ## Check your permissions
219
220 Alchemy needs RBAC permission to `get`, `create`, `patch`, and
221 `delete` the objects each resource manages, in the namespaces you
222 deploy to:
223
224 - `Deployment` writes a ServiceAccount, a Deployment, and a Service.
225 - `Job` writes a ServiceAccount and a Job, or a CronJob when it has a
226 `schedule`.
227 - `Manifest` writes the one object in its `manifest`.
228 - `HelmChart` writes every object the chart renders, often including
229 cluster-scoped ClusterRoles, CRDs, and webhook configurations.
230
231 Namespaces, ClusterRoles, CRDs, and other cluster-scoped kinds need
232 cluster-level permissions. Workload namespaces must already exist or
233 be created in the same Stack with a
234 [Manifest](/kubernetes/objects/manifests).
235
236 Check before deploying with `kubectl auth can-i`, using the same
237 context:
238
239 ```sh
240 kubectl --context prod-us-east auth can-i create deployments --namespace apps
241 kubectl --context prod-us-east auth can-i patch services --namespace apps
242 ```
243
244 ## Add a registry for your code
245
246 Workloads that run a pre-built `image` need nothing else. Workloads
247 built from your code, such as an Effect program (`main`) or a
248 Dockerfile (`context`), are built on your machine. Alchemy pushes
249 them to a registry the cluster's nodes can pull from. Add one to the
250 connection:
251
252 ```typescript
253 const cluster = Kubernetes.KubeConfig({
254 context: "prod-us-east",
255 registry: { server: "ghcr.io/acme" },
256 });
257 ```
258
259 Alchemy pushes with your machine's Docker login unless you pass
260 credentials. `LocalCluster` and EKS provide a registry themselves.
261 See [Container registries](/kubernetes/clusters/registries).
262
263 ## Deploy from CI
264
265 A CI runner needs the same things as your laptop. It needs network
266 access to the API server, credentials, and any exec plugin your
267 context calls. Common setups:
268
269 - Authenticate the runner to your cloud, for example with GitHub
270 OIDC. Then create the kubeconfig with the cloud CLI command above.
271 - Log the runner's Docker in to your registry (`docker login`) before
272 deploying workloads built from your code.
273 - Store a kubeconfig file as a secret, write it to disk, and set
274 `KUBECONFIG` to its path.
275 - Pass `path` and `context` from environment variables so the same
276 program targets a different cluster per stage.
277
278 Use a remote [state store](/state-store) so CI and your team see the
279 same deployments. See [CI](/environments/ci) for running
280 `alchemy deploy` in GitHub Actions.
281
282 ## State storage
283
284 Kubernetes has no state backend of its own, so pick one of:
285
286 - **`Alchemy.localState()`.** State lives on disk under `.alchemy/`
287 next to your code. This is fine for trying things out alone, but CI
288 and teammates can't see it.
289 - **`postgresState()`.** State lives in a Postgres database you
290 already run, such as a managed database from your Kubernetes
291 provider. It locks each stage while a deploy runs. See
292 [Postgres state store](/state-store#postgres-state-store).
293 - **`Cloudflare.state()` or `AWS.state()`.** State lives in your
294 Cloudflare or AWS account. See [State Store](/state-store).
295 - **Your own store.** Implement the state service over S3-compatible
296 storage, Redis, or anything else. See
297 [Custom state store](/state-store/custom-state-store).
298
299 Each resource stores its cluster connection in state so
300 `alchemy destroy` can reach the cluster later, even after the code
301 that declared it is gone.
302
303 ## Next steps
304
305 - [Tutorial part 1](/kubernetes/tutorial/part-1) deploys a
306 Deployment, step by step.
307 - [Connecting to clusters](/kubernetes/clusters/connecting) covers
308 every connection form, multi-cluster stacks, and moving between
309 clusters.
310 - [Kubernetes overview](/kubernetes) is the map of resources and
311 guides.