Metadata-Version: 2.4
Name: smol_k8s_lab
Version: 11.1.0
Summary: CLI and TUI to quickly install k3s or kind and manage apps declaratively using Argo CD, OpenBao, and Zitadel.
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: kubernetes,homelab,kind,k3s,k8s
Author: Jesse Hitch
Author-email: jessebot@linux.com
Requires-Python: >=3.13,<3.15
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Installation/Setup
Requires-Dist: bcrypt (>=5.0.0,<6.0.0)
Requires-Dist: click (>=8.1,<9.0)
Requires-Dist: cryptography (>=50.0.0,<51.0.0)
Requires-Dist: cute-name-generator (>=0.2,<0.3)
Requires-Dist: keyring (>=25.7.0,<26.0.0)
Requires-Dist: kubernetes (>=36,<37)
Requires-Dist: minio (>=7.2,<8.0)
Requires-Dist: pyfiglet (>=1.0,<2.0)
Requires-Dist: pyjwt (>=2.10,<3.0)
Requires-Dist: pykeepass (>=4.1.1.post1,<5.0.0)
Requires-Dist: python-ulid (>=4.0,<5.0)
Requires-Dist: pyyaml (>=6.0,<7.0)
Requires-Dist: requests (>=2.32,<3.0)
Requires-Dist: rich (>=14.1,<15.0)
Requires-Dist: ruamel-yaml (>=0.19,<0.20)
Requires-Dist: ruamel-yaml-string (>=0.1,<0.2)
Requires-Dist: textual (>=8.0,<9.0)
Requires-Dist: xdg-base-dirs (>=6.0,<7.0)
Project-URL: Bug Tracker, http://codeberg.org/open-engineering/smol-k8s-lab/issues
Project-URL: Documentation, https://smol-k8s-lab.open.engineering
Project-URL: Homepage, https://smol-k8s-lab.open.engineering
Project-URL: Repository, http://codeberg.org/open-engineering/smol-k8s-lab
Description-Content-Type: text/markdown

<h2 align="center">
 🧸 <code>smol-k8s-lab</code>
</h2>

<p align="center">
  <a href="https://codeberg.org/open-engineering/smol-k8s-lab/releases">
    <img src="https://img.shields.io/gitea/v/release/small-hack/smol-k8s-lab?gitea_url=https%3A%2F%2Fgit.open.engineering&logo=Forgejo">
  </a>
  <a href="https://pypi.org/project/smol_k8s_lab/">
    <img alt="PyPI - Version" src="https://img.shields.io/pypi/v/smol-k8s-lab?logo=pypi">
  </a>
  <a href="https://pypi.org/project/smol_k8s_lab/">
    <img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/smol-k8s-lab?logo=python">
  </a>
</p>

<p align="center">
  A terminal based tool to install slimmer k8s distros on metal, with batteries included!
</p>

<p align="center">
  <a href="./docs/assets/images/screenshots/help_text.svg">
    <img width="800" alt="Screenshot of the smol-k8s-lab help menu" src="./docs/assets/images/screenshots/help_text.svg">
  </a><br>
</p>

### Features

- Deploys [Argo CD](https://github.com/argoproj/argo-cd) by default, so you can manage your entire lab using files in [open source git repos](https://codeberg.org/open-engineering/argocd-apps)
  - 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 selfed hosted OIDC provider
- Supports initialization on a [range of common self-hosted apps](https://codeberg.org/open-engineering/argocd-apps/) 📱
  - featured initialized apps such as [Zitadel], [Nextcloud](https://codeberg.org/open-engineering/smol-k8s-lab/k8s_apps/nextcloud/), [Matrix](https://codeberg.org/open-engineering/smol-k8s-lab/k8s_apps/matrix/), and [Home Assistant](https://codeberg.org/open-engineering/smol-k8s-lab/k8s_apps/home_assistant/) include [b]backups and restores[/b]!
- Lots o' [docs](https://smol-k8s-lab.open.engineering)
- commitment to never monetizing this app. It will always be AGPL licensed and free 💙
- No AI or LLMs "features" and No AI contribution policy

-----------------------------

# Installation

🐝 sure to check out our full [installation guide](https://smol-k8s-lab.open.engineering/installation/), 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](https://github.com/pypa/pipx)). If you've already got both and [other pre-reqs](https://smol-k8s-lab.open.engineering/installation/#prerequisites), you should be able to:

```bash
# install the CLI
pipx install smol-k8s-lab

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

Then you should be able to check the version and cli options with:

```bash
smol-k8s-lab --help
```

<p align="center">
  <a href="https://codeberg.org/open-engineering/smol-k8s-lab/raw/branch/main/docs/assets/images/screenshots/help_text.svg">
      <img src="./docs/assets/images/screenshots/help_text.svg" alt="Output of smol-k8s-lab --help after cloning the directory and installing the prerequisites.">
  </a>
</p>

Checkout our [TUI docs](https://smol-k8s-lab.open.engineering/tui/create_modify_screens/) for more info on how to get started playing with `smol-k8s-lab` :-)

### Upgrades

Check out our [upgrades guide](https://smol-k8s-lab.open.engineering/upgrades/) for how to upgrade to different major versions, but in general, you can always run:

```bash
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                                                                                                                                                                                  |
|:------------------------------------------------------------------------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|   [<img src="https://codeberg.org/open-engineering/smol-k8s-lab/raw/branch/main/docs/assets/images/icons/k3s_icon.ico" width="26">][k3s] <br /> [k3s]  | The certified Kubernetes distribution built for IoT & Edge computing                                                                                                                         |
|     [<img src="https://codeberg.org/open-engineering/smol-k8s-lab/raw/branch/main/docs/assets/images/icons/k3d.png" width="26">][k3d] <br /> [k3d]     | **TESTING PHASE** k3s in docker 🐳                                                                                                                                                           |
| [<img src="https://codeberg.org/open-engineering/smol-k8s-lab/raw/branch/main/docs/assets/images/icons/kind_icon.png" width="32">][KinD] <br /> [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 not installed, `smol-k8s-lab` will <i>only</i> install: MetalLB, nginx-ingress, and cert-manager.

|                                                                                                                              Application                                                                                                                              | Description                                                                                                                                                   | Initialization Supported |
|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------:|
|   [<img src="https://codeberg.org/open-engineering/smol-k8s-lab/raw/branch/main/docs/assets/images/icons/metallb_icon.png" width="32px" alt="metallb logo, blue arrow pointing up, with small line on one leg of arrow to show balance">][metallb] <br /> [metallb]   | Loadbalancer and IP Address pool manager for metal                                                                                                            |            ✅            |
|                                                                               [<img src="./docs/assets/images/icons/cilium.png" width="32px" alt="cilium logo">][cilium] <br /> [cilium]                                                                              | Gateway API (a bit clunky right now, but getting better!)                                                                                                     |            ✅            |
|                                                       [<img src="./docs/assets/images/icons/traefik.png" width="32px" alt="traefik logo, blue gopher wearing a plane director outfit">][traefik] <br /> 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. |            ✅            |
|                                [<img src="https://codeberg.org/open-engineering/smol-k8s-lab/raw/branch/main/docs/assets/images/icons/cert-manager_icon.png" width="32px" alt="cert manager logo">][cert-manager] <br /> [cert-manager]                               | For SSL/TLS certificates                                                                                                                                      |            ✅            |
|                      [<img src="https://codeberg.org/open-engineering/smol-k8s-lab/raw/branch/main/docs/assets/images/icons/argo_icon.png" width="32" alt="argo CD logo, an organer squid wearing a fishbowl helmet">][Argo CD] <br /> [Argo CD]                      | Gitops - Continuous Deployment                                                                                                                                |            ✅            |
| [<img src="https://codeberg.org/open-engineering/smol-k8s-lab/raw/branch/main/docs/assets/images/icons/argo_icon.png" width="32" alt="argo CD logo, an organer squid wearing a fishbowl helmet">][Argo CD Appset Secret Plugin] <br /> [Argo CD Appset Secret Plugin] | Gitops - Continuous Deployment                                                                                                                                |            ✅            |
|                      [<img src="https://codeberg.org/open-engineering/smol-k8s-lab/raw/branch/main/docs/assets/images/icons/eso_icon.png" width="32" alt="ESO logo, outline of robot with astricks in a screen in it's belly">][ESO] <br /> [ESO]                     | external-secrets-operator integrates external secret management systems like Bitwarden                                                                        |            ❌            |
|                            [<img src="https://codeberg.org/open-engineering/smol-k8s-lab/raw/branch/main/docs/assets/images/icons/eso_icon.png" width="32" alt="ESO logo, again">][Bitwarden ESO Provider] <br /> [Bitwarden ESO Provider]                            | Bitwarden external-secrets-operator provider                                                                                                                  |            ✅            |
|                   [<img src="https://raw.githubusercontent.com/openbao/artwork/refs/heads/main/color/openbao-color.png" height="32px" alt="OpenBao logo, drawing of 3 small bao with simple eyes personifying them">][OpenBao] <br /> [OpenBao]                   | OpenBao (Hashicorp Vault fork) - it's a Secrets Store.                                                                                                        |            ✅            |
|                              [<img src="https://codeberg.org/open-engineering/smol-k8s-lab/raw/branch/main/docs/assets/images/icons/zitadel.png" width="32" alt="Zitadel logo, an orange arrow pointing left">][ZITADEL] <br /> [ZITADEL]                             | An identity provider and OIDC provider to provide SSO                                                                                                         |            ✅            |
|                             [<img src="https://codeberg.org/open-engineering/smol-k8s-lab/raw/branch/main/docs/assets/images/icons/prometheus.png" width="32" alt="Prometheus logo, a torch">][Prometheus Stack] <br /> [Prometheus Stack]                            | Prometheus monitoring and logging stack using [loki]/[alloy], [alert manager], and [grafana]                                                                  |            ✅            |

For a complete list of installable applications, checkout the [default apps docs](https://smol-k8s-lab.open.engineering/k8s_apps/). To install your own custom apps, you can check out an [example via the config file](https://smol-k8s-lab.open.engineering/config_file/#applications) or [learn how to do it via the tui](https://smol-k8s-lab.open.engineering/tui/apps_screen/#adding-new-applications).


# Status

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

<!-- k8s distro link references -->
[k3s]: https://k3s.io/
[k3d]: https://k3d.io/
[KinD]: https://kind.sigs.k8s.io/

<!-- k8s optional apps link references -->
[alloy]: https://grafana.com.com/oss/alloy
[alert manager]: https://prometheus.io/docs/alerting/latest/alertmanager/
[Argo CD]:https://argo-cd.readthedocs.io/en/latest/
[Argo CD Appset Secret Plugin]: https://codeberg.org/open-engineering/argocd-appset-secret-plugin/
[Bitwarden ESO Provider]: https://codeberg.org/open-engineering/bitwarden-eso-provider
[cert-manager]: https://cert-manager.io/docs/
[cilium]: https://cilium.io/
[ESO]: https://external-secrets.io/v2.0.0/
[grafana]: https://grafana.com/
[ingress-nginx]: https://github.io/kubernetes/ingress-nginx
[k8tz]: https://git.open.engineering/small-hack/argocd-apps/src/branch/main/k8tz
[k8up]: https://k8up.io
[Kyverno]: https://github.com/kyverno/kyverno/
[kepler]: https://github.com/sustainable-computing-io/kepler-helm-chart/tree/main/chart/kepler
[Local Path Provisioner]: https://github.com/rancher/local-path-provisioner
[loki]: https://grafana.com/oss/loki/
[Mastodon]: https://joinmastodon.org/
[matrix]: https://matrix.org/
[metallb]: https://github.io/metallb/metallb
[Nextcloud]: https://github.com/nextcloud/helm
[OpenBao]: https://openbao.org/
[Prometheus Stack]: https://codeberg.org/open-engineering/argocd-apps/tree/main/prometheus
[traefik]: https://traefik.io/traefik
[ZITADEL]: https://github.com/zitadel/zitadel-charts/tree/main

<!-- k8s tooling reference -->
[`brew`]: https://brew.sh
[k9s]: https://k9scli.io/topics/install/
[restic]: https://restic.readthedocs.io/en/stable/

