## 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.