## Architecture Decision Record: Default Runtime for Managed Workloads

### Status

Proposed

### Context

Our infrastructure orchestrator manages workloads requiring a Kubernetes-compatible runtime environment.

**Requirements**

- Cross-platform (Linux, Windows, macOS)
- Kubernetes compatibility
- Lightweight, easy setup with minimal dependencies
- Clean host teardown and minimal residue
- Well-maintained and actively supported

### Decision

We select **k3d (k3s in Docker)** as our default runtime environment across all supported platforms (Linux, Windows, macOS).

### Rationale

- **Consistency Across Platforms:**  
  One solution for all platforms simplifies development, supports documentation, and reduces complexity.

- **Simplified Setup and Teardown:**  
  k3d runs Kubernetes clusters in Docker containers, allowing quick setup, teardown, and minimal host residue.

- **Leveraging Existing Container Ecosystem:**  
  Docker/container runtimes are widely adopted, making their presence and familiarity common among users.

- **Kubernetes Compatibility:**  
  k3s (within k3d) is fully Kubernetes-certified, ensuring compatibility with standard Kubernetes tools and manifests.

- **Active Maintenance and Community:**  
  k3d and k3s both have active communities and are well-maintained.

### Consequences

#### Positive

- **Uniform User Experience:** Users have a consistent setup experience across all platforms.
- **Reduced Support Overhead:** Standardizing runtime simplifies support, documentation, and troubleshooting.
- **Clean Isolation:** Containerization allows developers to easily clean up clusters without affecting host systems.
- **Facilitates Multi-Cluster Development:** Easy creation and management of multiple clusters concurrently.

#### Negative

- **Docker Dependency:** Requires Docker (or compatible runtime) on all platforms.
- **Potential Overhead:** Slight performance/resource overhead compared to native k3s.
- **Docker Licensing Considerations:** Enterprise licensing of Docker Desktop could introduce additional considerations.

### Alternatives Considered

- **Native k3s (Linux) / k3d (Windows/macOS):** Original proposal. Rejected for greater simplicity and consistency.
- **Minikube, MicroK8s, Kind:** Rejected due to complexity, resource usage, or narrower use-case focus.
- **Docker Compose, Podman Desktop:** Rejected due to lack of orchestration or current limited k3d compatibility.

### Future Work

- Evaluate Podman Desktop or other container runtimes to avoid Docker dependency.
- Continuously monitor k3d maturity and stability.
- Investigate WebAssembly (WASM) runtimes as emerging alternatives for containerized workloads.
