Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-0011: Colima on macOS and k3d on Linux as the local cluster drivers

Status: accepted · Date: 2026-10-13 · Decision makers: James Hebden

Context and Problem Statement

Xianyun needs a local Kubernetes cluster that comes up quickly, can be destroyed and recreated, and gives the host a usable network path to the ingress. The two platforms it targets differ: macOS has no native container runtime, and Linux does. The original Caproni project settled this in its alpha decision log; this ADR records the decision and what the Rust code does with it.

Decision Drivers

  • A real route from the host to the cluster’s ingress on both platforms
  • Lightweight enough to run beside a developer’s other work
  • Works in CI on Linux runners
  • No privileged setup beyond what the container runtime itself needs

Considered Options

  1. Colima on macOS and k3d on Linux, chosen automatically by driver: auto
  2. k3d everywhere, with Docker Desktop on macOS
  3. minikube everywhere
  4. Kind everywhere

Decision Outcome

Chosen option: “Colima on macOS and k3d on Linux”, because Colima gives macOS a Linux VM with its own network address without Docker Desktop, and k3d runs k3s in containers directly on Linux, including on CI runners. The original decision log noted that Colima lacks network support on Linux, and that minikube also works. driver: auto picks colima on macOS and k3d elsewhere (crates/xianyun-cluster/src/driver/auto.rs); k3d and colima can still be named explicitly, and external, vcluster, and mock sit alongside them.

Consequences

Good:

  • One setting covers both platforms, and CI uses the Linux path
  • The drivers sit behind one trait, so adding another is a new file and a registration

Bad:

  • Two code paths to test. Only the k3d path has an end-to-end test (e2e-k3d); the Colima driver is covered by unit tests against a mocked runner, and its live-cluster tests are ignored.
  • Rootless Podman on Linux needs extra setup; see Linux and Podman setup

Neutral:

  • Colima always runs on the containerd runtime; see ADR-0016

Implementation Location

  • crates/xianyun-cluster/src/driver/auto.rs
  • crates/xianyun-cluster/src/driver/k3d.rs
  • crates/xianyun-cluster/src/driver/colima.rs

More Information

  • Recorded on 2026-10-13 from the Go project’s alpha decision log (see ADR-0017 for where that log went) and the Rust driver code.
  • Related: FR-004