How kilter uses KIND

KIND ("Kubernetes IN Docker") runs a complete Kubernetes cluster inside Docker containers. Instead of VMs or a cloud account, the cluster's node — control plane included — is just a container on your machine. That makes clusters cheap to create, cheap to destroy, and completely disposable.

One cluster per project

Kilter creates a dedicated KIND cluster for every project, named kilter-<project> (e.g. kilter-kilterkb). Nothing is shared between projects:

Each cluster is its own Docker container — docker ps shows one per running project.
Each project's workloads live in a <project>-dev namespace inside its own cluster.
Ports and kubeconfigs are per-project too (see Namespaces & isolation).

The payoff: you can break one project's environment as badly as you like — wrong migrations, crashed services, corrupted state — and every other project is untouched. kilter destroy and start over.

Lifecycle maps to Docker

Because the cluster is a Docker container, kilter's lifecycle verbs map directly onto container operations:

Command	Docker effect	State
`kilter up`	Create (or `docker start`) the cluster container, then start Tilt	Preserved on resume
`kilter down`	Nothing — container keeps running, only Tilt stops	Everything stays live
`kilter stop`	Stop the container (frees RAM/CPU)	Preserved on disk
`kilter destroy`	Delete the container entirely	Gone

State across stop/up

kilter stop writes a cluster.stopped: true flag into kilter.yaml. On the next kilter up, kilter sees the flag, runs docker start on the existing cluster container, and waits for it to become healthy (~30s) — your database contents, service data, and cluster objects all come back.

stop vs destroy: know the difference

kilter stop / kilter up preserves your KIND cluster's state — the container just pauses and resumes. Only kilter destroy actually deletes it. This is a common gotcha: reaching for destroy when you meant stop will nuke everything, database included. If you just want to free up resources, stop is the safe choice.

Crashes and reboots lose state

The cluster.stopped flag is only set by a clean kilter stop. If your machine reboots, Docker restarts, or the cluster container is OOM-killed, the flag is unset — the next kilter up falls back to recreating the cluster, and its state is lost. End the day with kilter stop, not a lid-close.

If state matters (a hand-crafted database, say), snapshot it: kilter db snapshot <name> survives even kilter destroy.

Inspecting the cluster

Kilter never touches ~/.kube/config. Each project gets an isolated kubeconfig:

export KUBECONFIG=~/.cache/kilter/<project>/kubeconfig
kubectl get pods -n <project>-dev
kubectl describe pod <pod> -n <project>-dev

For day-to-day checks you rarely need kubectl — kilter status, kilter logs <service>, and kilter restart <service> cover pod state, logs, and recovery. Reach for the raw kubeconfig when you want describe, events, or anything kilter doesn't wrap.

Next: How kilter uses Tilt — what actually runs your code inside this cluster.