smol_k8s_lab 2.0.5

CLI and TUI to quickly install slimmer Kubernetes distros and then manage apps declaratively using Argo CD

smol k8s lab 🧸 ^{_{Now with more :squid:}}

A terminal based tool to install slimmer k8s distros on metal, with batteries included. Deploys Argo CD by default, so you can manage your entire local testing lab from the very beginning using files in open source git repos, and with the help of a very handy dashboard. Also helpful for benchmarking various k8s distros! 💙 Check out our video tour, if you like that sort of thing:

Here's the same video with captions.

Installation

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

pipx

smol-k8s-lab requires Python 3.11+ (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

brew (still unstable)

brew is the future preferred installation method for macOS/Debian/Ubuntu, as this will also install any non-python prerequisites you need, so you don't need to worry about them. This method is new, so please let us know if anything isn't working for you.

# tap the special homebrew repo for our formula and install it
brew install small-hack/tap/smol-k8s-lab

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

smol-k8s-lab --help

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

Usage

Initialization

After you've followed the installation instructions, if you're new to smol-k8s-lab, initialize a new config file:

# we'll walk you through any configuration needed before 
# saving the config and deploying it for you
smol-k8s-lab

Upgrading config from v1.x to v2.x

If you've installed smol-k8s-lab prior to v2.0.0, please backup your old configuration, and then remove the ~/.config/smol-k8s-lab/config.yaml (or $XDG_CONFIG_HOME/smol-k8s-lab/config.yaml) file entirely, then run the following:

# this upgrades smol-k8s-lab
pip3.11 install --upgrade smol-k8s-lab

# this initializes a new configuration
smol-k8s-lab

The main difference between the old and new config files are for apps, we've added:

• apps.APPNAME.description - for adding a custom description, set it to whatever you like
• apps.APPNAME.argo.directory_recursion - so you can have bigger nested apps :)
• apps.APPNAME.argo.project.destination.namespaces - control what namespaces are allowed for a project

And we've changed:

• apps.APPNAME.argo.ref to apps.APPNAME.argo.revision
• apps.APPNAME.argo.project_source_repos to apps.APPNAME.argo.project.source_repos

And we've REMOVED:

• apps.APPNAME.argo.part_of_app_of_apps - this was mostly used internally, we think

Here's an example of an updated cert-manager app with the new config:

apps:
  cert_manager:
    # ! NOTE: you currently can't set this to false. It is necessary to deploy
    # most of our supported Argo CD apps since they often have TLS enabled either
    # for pod connectivity or ingress
    enabled: true
    description: |
      [link=https://cert-manager.io/]cert-manager[/link] let's you use LetsEncrypt to generate TLS certs for all your apps with ingress.

      smol-k8s-lab supports initialization by creating two [link=https://cert-manager.io/docs/concepts/issuer/]ClusterIssuers[/link] for both staging and production using a provided email address as the account ID for acme.

    # Initialize of the app through smol-k8s-lab
    init:
      # Deploys staging and prod ClusterIssuers and prompts you for
      # cert-manager.argo.secret_keys if they were not set. Switch to false if
      # you don't want to deploy any ClusterIssuers
      enabled: true
    argo:
      secret_keys:
        # Used for letsencrypt-staging, to generate certs
        email: ""
      # git repo to install the Argo CD app from
      repo: "https://github.com/small-hack/argocd-apps"
      # path in the argo repo to point to. Trailing slash very important!
      path: "cert-manager/"
      # either the branch or tag to point at in the argo repo above
      revision: main
      # namespace to install the k8s app in
      namespace: "cert-manager"
      # recurse directories in the provided git repo
      directory_recursion: false
      # source repos for cert-manager CD App Project (in addition to argo.repo)
      project:
        source_repos:
          - https://charts.jetstack.io
        destination:
          # automatically includes the app's namespace and argocd's namespace
          namespaces:
            - kube-system

Upgrading your config to v1.x

If you've installed smol-k8s-lab prior to v1.0.0, please backup your old configuration, and then remove the ~/.config/smol-k8s-lab/config.yaml (or $XDG_CONFIG_HOME/smol-k8s-lab/config.yaml) file entirely, then run the following:

# this upgrades smol-k8s-lab
pip3.11 install --upgrade smol-k8s-lab

# this initializes a new configuration
smol-k8s-lab

Adding custom Applications

You can create any application you already have an Argo CD application repo for, by following a simple application YAML schema in ~/.config/smol-k8s-lab/config.yaml like this:

apps:
  # name of application to create in Argo CD
  cert_manager:
    # if set to false, we ignore this app
    enabled: true
    argo:
      # secret keys to pass to Argo CD Application Set Generator
      secret_keys:
        # Used for letsencrypt-staging, to generate certs. If set to "" and cert-manager.enabled is true
        # smol-k8s-lab will prompt for this value and save it back to this file for you.
        email: ""
      # git repo to install the Argo CD app from
      repo: "https://github.com/small-hack/argocd-apps"
      # path in the argo repo to point to. Trailing slash very important!
      path: "ingress/cert-manager/"
      # either the branch or tag to point at in the argo repo above
      ref: "main"
      # namespace to install the k8s app in
      namespace: "ingress"
      # source repos for cert-manager CD App Project (in addition to cert-manager.argo.repo)
      project_source_repos:
        - https://charts.jetstack.io

Note: the above application, cert-manager, is already included as a default application in 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
k3d	ALPHA - TESTING PHASE k3s in docker 🐳
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 only install: MetalLB, nginx-ingress, and cert-manager.

Application	Description	Initialization Supported
metallb	Loadbalancer and IP Address pool manager for metal	✅
ingress-nginx	The ingress 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	✅

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

This is recently released, but still being actively supported, and if you'd like to contribute or just found a :bug:, feel free to open an issue (and/or pull request), and we'll try to take a look ASAP!