Metadata-Version: 2.4
Name: smol_k8s_lab
Version: 11.3.1
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: bitwarden-wrapper (>=0.1.2,<0.2.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: rich-subproc (>=0.1.0,<0.2.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">
  <!-- commented out until we have our new forgejo up and running
  <a href="https://codeberg.org/open-engineering/smol-k8s-lab/releases">
    <img src="https://img.shields.io/gitea/v/release/open-engineering/smol-k8s-lab?gitea_url=https%3A%2F%2Fcodeberg.org&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 self-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/argocd-apps/src/branch/main/nextcloud), [Matrix](https://codeberg.org/open-engineering/argocd-apps/src/branch/main/matrix/), and [Home Assistant](https://codeberg.org/open-engineering/argocd-apps/src/branch/main/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](https://smol-k8s-lab.open.engineering/)
- 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](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
```

Checkout our [TUI docs](https://smol-k8s-lab.open.engineering/tui) 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/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 Argo CD is *not* installed, `smol-k8s-lab` will *only* install: MetalLB, prometheus CRDs, Traefik, and cert-manager.

|                                                                                                          Application                                                                                                         | Description                                                                                                                                                   |
|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------|
|                [<img src="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/cert-manager_icon.png" width="32px" alt="cert manager logo">][cert-manager] <br /> [cert-manager]                                            | For SSL/TLS certificates                                                                                                                                      |
|                                   [<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="docs/assets/images/icons/alloy.png" width="32px" alt="alloy logo, a redish orange spiraly triangular circle">][alloy] <br /> [alloy]                                       | For collecting metrics, logs, and traces to be forwarded to loki, tempo, and mimir and viewed in grafana.                                                     |
|                                   [<img src="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="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 OpenBao and Bitwarden                                                            |
| [<img src="https://raw.githubusercontent.com/openbao/artwork/refs/heads/main/color/openbao-color.png" width="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="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="docs/assets/images/icons/grafana.png" width="32" alt="Grafana logo, an orange spiral">][Grafana Stack] <br /> [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](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/
[cert-manager]: https://cert-manager.io/docs/
[cilium]: https://cilium.io/
[ESO]: https://external-secrets.io/v2.0.0/
[grafana]: https://grafana.com/
[Grafana Stack]: https://codeberg.org/open-engineering/argocd-apps/src/branch/main/grafana_stack
[k8up]: https://k8up.io
[Kyverno]: https://github.com/kyverno/kyverno/
[loki]: https://grafana.com/oss/loki/
[Mastodon]: https://joinmastodon.org/
[mimir]: https://grafana.com.com/oss/mimir
[matrix]: https://matrix.org/
[metallb]: https://github.io/metallb/metallb
[Nextcloud]: https://github.com/nextcloud/helm
[OpenBao]: https://openbao.org/
[Tempo]: https://grafana.com/oss/tempo/
[Traefik]: https://traefik.io/traefik
[ZITADEL]: https://github.com/zitadel/zitadel-charts/tree/main

