🧸 Smol K8s Lab
Leverage Argo CD and slim Kubernetes distributions, like K3s, to create production-like environments via a declarative workflow. Batteries and 🦑 included.
About
smol-k8s-lab's declarative workflow, CLI, and TUI enable rapid iteration in production-like environments with minimal costs for failure. This makes it ideal for proof-of-concepts, prototyping, and benchmarking Kubernetes applications and distributions. It's also great for home labs, with some common FOSS apps such as Home Assistant, Nextcloud, Matrix, and more!
By default, smol-k8s-lab deploys Argo CD + Argo CD Appset Secret Plugin which enables Argo CD to securely manage your lab via files in open source Git repos. Additionally, a customized nord-like dark-theme is provided for Argo CD's incredibly useful web-interface.
Consider viewing our very long walk through if you like video walk-throughs (which is a little out of date, but we intend to update it as soon as possible to include new features):
Here's the same video with captions.
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 💙
- Specializes in using Bitwarden (though not required) to store sensitive values both in your Bitwwarden vault, and on your cluster as Secrets.
- Manages all your authentication needs centrally using Zitadel and Vouch 💪
- Supports initialization on a range of common self-hosted apps 📱
- featured initialized apps such as Zitadel, Nextcloud, Matrix, and Home Assistant include [b]backups and restores[/b]!
- Lots o' docs
Getting Started
Please see our Getting Started guide.
Under the hood
Note: this project is not officially affiliated with any of the below tooling or applications. We just love open source projects 💙
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 |
 k3d |
K3d is k3s in Docker 🐳. In beta! |
 KinD |
kind is a tool for running local Kubernetes clusters using Docker container “nodes”. kind was primarily designed for testing Kubernetes itself. |
We tend to test first on k3s first, then the other distros.
Default Installed Applications
Version is the helm chart version, or manifest version. See the Default Applications tab for more info on each application.
| Application | Description | Initialization Supported |
|---|---|---|
 metallb |
Loadbalancer and IP Address pool manager for metal | ✅ |
 ingress-nginx |
The ingress-nginx controller allows access to the cluster remotely, needed for web traffic | ❌ |
 cert-manager |
For SSL/TLS certificates | ✅ |
 Argo CD |
Gitops - Continuous Deployment | ✅ |
| Argo CD Appset Secret Plugin |
Gitops - Continuous Deployment | ✅ |
 ESO |
external-secrets-operator integrates external secret management systems like Bitwarden or GitLab | ❌ |
| Bitwarden ESO Provider |
Bitwarden external-secrets-operator provider | ✅ |
 ZITADEL |
An identity provider and OIDC provider to provide SSO | ✅ |
 Vouch |
Vouch proxy allows you to secure web pages that lack authentication e.g. prometheus | ✅ |
 Prometheus Stack |
Prometheus monitoring and logging stack using loki/promtail, alert manager, and grafana | ✅ |
Minor Notes:
All Default Applications can be disabled through your
~/.config/smol-k8s-lab/config.yamlfile, except Argo CD. You can still choose not to install it, but if not installed, smol-k8s-lab will only install: metallb, nginx-ingress, and cert-manager
Optionally Installed Applications
| Application/Tool | Description | Initialization Supported |
|---|---|---|
 Ciliumdemo |
Kubernetes netflow visualizer and policy editor | ✅ |
 Home Assistant |
Home Assistant, a self hosted, at home IoT management solution. | ✅ |
 Kyvernoalpha |
Kubernetes native policy management to enforce policies on k8s resources | ❌ |
 kepler |
Kepler (Kubernetes Efficient Power Level Exporter) uses eBPF to probe energy-related system stats and exports them as Prometheus metrics. | ✅ |
 k8up |
Backups operator using restic to backup to s3 endpoints | ✅ |
 k8tz |
Timezone environment variable injector for pods and cronjobs | ✅ |
 Netmaker |
Netmaker is a self hosted vpn management tool that uses Wiregaurd® | ✅ |
 Nextcloud |
Nextcloud is a self hosted file server | ✅ |
 Mastodon |
Mastodon is a self hosted federated social media network | ✅ |
 matrix |
Matrix is a self hosted chat platform | ✅ |
 minio |
Self hosted S3 Object Store operator | ✅ |
 seaweedfs |
Self hosted S3 Object Store | ✅ |
 k9s |
Terminal based dashboard for kubernetes | ✅ |
Status
smol-k8s-lab is actively maintained, and in a semi-stable state. We still may introduce features that, upon major version releases, can introduce breaking changes, but we'll always include how to update your config files in the merged pull request description, and that will be linked in the release notes.
Development
smol-k8s-lab is written in Python 3.12 and built and published using Poetry. You can check out the pyproject.toml for the versions of each library we install below.
Core libraries
These are installed anytime you install smol-k8s-lab as an end user:
| Default Library | Description |
|---|---|
| bcrypt | to pass a password to argocd and automatically update your Bitwarden |
| click | handles arguments for the CLI |
| kubernetes | for using the partially functional python sdk for kubernetes |
| minio | for connecting to s3 and saving credentials |
| pyfiglet | uses figlet to print the ascii text banner in the tui |
| pyjwt | used for processing tokens from zitadel |
| pyyaml | this is actively being removed in favor of ruamel.yaml |
| rich | makes all the pretty formatted text in logs and --help |
| textual | this is the framework used for writing the TUI |
| ruamel.yaml | to handle the k8s yamls and configs while maintaining comments) |
| xdg-base-dirs | lets us use default config and cache directories for storage accross major OSes |
Development libraries
These are installed anytime you want to develop smol-k8s-lab:
| Development Library | Description |
|---|---|
| mkdocs-material | for the docs site |
| mkdocs-video | for videos on the docs site |
| deptry | for purging unused libraries |
| textual-dev | for consoling textual |
| pytest-textual-snapshot | for taking screenshots with textual |
| poethepoet | for running special tasks during poetry build |
| coqui-tts | for generating text to speech audio files |
| pydub | for converting audio files from wav to mp3, requires ffmpeg |
| pygame | for playing audio accross different OSes, requires alsa on linux |
We also utilize the Bitwarden cli, for a password manager so you never have to see/know your Argo CD password.
Things we don't handle (yet)
-
Port Forwarding
If you want to access an app outside of port forwarding to test, you'll need to make sure your app's ingress is setup correctly and then you'll need to setup your router to port forward 80->80 and 443->443 for your WAN. Then, setup DNS for your domain if you want the wider internet to access this remotely.
-
High-Availability
HA cluster design with K3s requires etcd or another external key-value store such as PostgreSQL. Smol-K8s-Lab deploys k3s in a single-node configuration using SQLite which can be used for multi-node configurations but is not suitable for high-availability.