🧸 smol-k8s-lab

A terminal based tool to install slimmer k8s distros on metal, with batteries included!

Features

• Deploys Argo CD by default, so you can manage your entire lab using files in open source git repos
  • Argo CD ships with a dashboard with a custom theme 💙
  • Argo CD is default secured with a self hosted OIDC provider, Zitadel

• Uses a local password manager of your choice. Currently supported:
  • Bitwarden
  • KeyPass
  • macOS keychain
  • Freedesktop Secret Service supports many DE including GNOME (requires secretstorage)
  • KDE4 & KDE5 KWallet (requires dbus)
• External Secerts management for your sensitive Kubernetes Secret values. Currently supported:
  • Bitwarden
  • OpenBao
• Manages all your authentication needs centrally using Zitadel, a self-hosted OIDC provider
• Supports initialization on a range of common self-hosted apps 📱
  • featured initialized apps such as Zitadel, Nextcloud, Matrix, and Home Assistant include backups and restores!
• Allows you to deploy multiple environments, so you can have environments for dev, testing, prod, etc.
• Lots o' docs
• Commitment to never monetizing this app. It will always be AGPL licensed and free 💙
• No AI or LLM "features" and a "No AI" contribution policy

---

Installation

🐝 sure to check out our full installation guide, but the gist of it is smol-k8s-lab can be installed via pipx (or brew coming soon).

pipx

smol-k8s-lab requires Python 3.12+ (and pipx). If you've already got both and other pre-reqs, you should be able to:

# install the CLI
pipx install smol-k8s-lab

# Check the help menu before proceeding
smol-k8s-lab --help

Checkout our TUI docs for more info on how to get started playing with smol-k8s-lab :-)

Upgrades

Check out our upgrades guide for how to upgrade to different major versions, but in general, you can always run:

pipx upgrade smol-k8s-lab

Under the hood

Note: this project is not officially affiliated with any of the below tooling or applications.

Supported k8s distributions

We always install the latest version of Kubernetes that is available from the distro's startup script.

Distro	Description
k3s	The certified Kubernetes distribution built for IoT & Edge computing
KinD	kind is a tool for running local Kubernetes clusters using Docker container “nodes”. kind was primarily designed for testing Kubernetes itself, but may be used for local development or CI.

We tend to test first on k3s first, then the other distros. k3d support coming soon.

Default Installed Applications

All of these can be disabled with the exception of Argo CD, which is optional, but if Argo CD is not installed, smol-k8s-lab will only install: MetalLB, prometheus CRDs, Traefik, and cert-manager.

Application	Description
metallb	Loadbalancer and IP Address pool manager for metal
cert-manager	For SSL/TLS certificates
Traefik	Traefik is both an Ingress and Gateway API controller and we're currently switching to supporting it in addition to cilium since ingress-nginx is deprecated.
alloy	For collecting metrics, logs, and traces to be forwarded to loki, tempo, and mimir and viewed in grafana.
Argo CD	Gitops - Continuous Deployment
ESO	external-secrets-operator integrates external secret management systems like OpenBao and Bitwarden
OpenBao	OpenBao (Hashicorp Vault fork) - it's a Secrets Store.
ZITADEL	An identity provider and OIDC provider to provide SSO
Grafana Stack	Grafana monitoring and logging stack (LGTM) using loki, grafana, tempo, and mimir (which includes alert manager).

For a complete list of installable applications, checkout the default apps docs. To install your own custom apps, you can check out an example via the config file or learn how to do it via the tui.

Status

Somewhat stable and being actively supported, so if you'd like to contribute or just found a 🐛, feel free to open an issue (and/or pull request) over at codeberg.org, and we'll try to take a look ASAP!