BEYOND DOCKER

Kubernetes

Kiri can run a Kubernetes cluster for local work: one node, k3s, in one container. kiri k8s start makes it, waits until the node is ready, and adds a kiri context to kubectl. A LoadBalancer service gets its port on your Mac’s localhost, so you can open it in the browser.

Start a cluster

zsh

$ kiri k8s start
pulling rancher/k3s:v1.37.1-k3s1…
waiting for the node…
kubectl context `kiri` added to /Users/you/.kube/config (backup: /Users/you/.kube/config.bak.kiri.1793174400)
Kubernetes is ready in 20 s: kubectl --context kiri get nodes

The first start pulls the k3s image; after that, a start takes about 20 seconds. Kiri waits up to three minutes for the node to report Ready, and tells you to look at the container’s logs if it doesn’t.

While the cluster runs, Kiri’s window shows Kubernetes and its version in the status bar, and the node appears in the container list as kiri-k8s.

The commands

Command	What it does
`kiri k8s start`	Creates the cluster the first time, or starts it again, then waits for the node.
`kiri k8s start --use`	The same, and makes `kiri` kubectl’s current context.
`kiri k8s status`	`not created`, or the container’s state; when running, `kubectl get nodes -o wide` from inside.
`kiri k8s stop`	Stops the cluster. Its state is kept, and `start` resumes it.
`kiri k8s delete`	Removes the cluster, its state and the `kiri` context.

The Kiri daemon must be running, from Kiri.app or kiri daemon.

What runs where

The cluster is a privileged Kiri container named kiri-k8s, running k3s server from the rancher/k3s image. Its state, everything under /var/lib/rancher/k3s, is in the kiri-k8s volume, so it survives stop and start. It restarts with Kiri unless you stopped it. k3s’s bundled Traefik ingress is turned off.

kubectl on your Mac talks to the API server on 127.0.0.1:6443. A LoadBalancer service's port is forwarded from localhost to the node container.

The kiri context

When the node is ready, Kiri reads the cluster’s kubeconfig, renames its cluster, user and context to kiri, and saves it at ~/.kiri/kubeconfig. If kubectl is on your PATH, Kiri also merges it into ~/.kube/config:

your existing ~/.kube/config is backed up first, as config.bak.kiri.<time>;
an old kiri cluster, user and context are replaced, other contexts are left alone;
your current context only changes with --use.

Without kubectl, point tools at the file directly:

export KUBECONFIG=~/.kiri/kubeconfig

The API server listens on 127.0.0.1:6443 only. kiri k8s delete removes ~/.kiri/kubeconfig and the kiri entries from ~/.kube/config.

LoadBalancer services on localhost

Every LoadBalancer service gets its port on your Mac’s localhost, TCP or UDP. Kiri checks the cluster’s services every few seconds, starts a forward to the node for each LoadBalancer port, and removes it when the service or the cluster goes.

kubectl --context kiri create deployment web --image=nginx:alpine
kubectl --context kiri expose deploy web --type=LoadBalancer \
  --port 8080 --target-port 80
open http://localhost:8080

ClusterIP services and cluster DNS work as in any cluster, from pod to pod. Only LoadBalancer ports reach the Mac.

Linux machinesA long-lived Linux box with your user and your files.Memory and sleepHow the VM gives memory back and sleeps when idle.