☁️ CLI & TUI with a smol friendly vibe to get started with Kubernetes on metal, then bootstrap apps using Argo CD 🧸 Great for testing webapps and benchmarking.
If you've installed smol-k8s-lab prior to v3.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 with either pip or pipx:
if using pip:
# this upgrades smol-k8s-lab using pip, but you may need to specify pip3.12 if you're using that
pip install --upgrade smol-k8s-lab
# this initializes a new configuration
smol-k8s-lab
or if using pipx:
# this upgrades smol-k8s-lab
pipx upgrade smol-k8s-lab
# this initializes a new configuration
smol-k8s-lab
If you don't want to delete your config file, please read the breaking changes below...
Breaking config.yml changes between v2.2.4 and v3.0
home assistant has graduated from demo app to live app
You'll need to change apps.home_assistant.argo.path to either home-assistant/toleration_and_affinity/ if you're using node labels and taints, or home-assistant/ if you're deploying to a single node cluster.
Here's an example with no tolerations or node affinity
```yaml
apps:
home_assistant:
enabled: false
description: |
[link=https://home-assistant.io]Home Assistant[/link] is a home IOT management solution.
By default, we assume you want to use node affinity and tolerations to keep home assistant pods on certain nodes and keep other pods off said nodes. If you don't want to use either of these features but still want to use the small-hack/argocd-apps repo, first change the argo path to /home-assistant/ and then remove the 'toleration_' and 'affinity' secret_keys from the yaml file under apps.home_assistant.description.
argo:
secret_keys:
hostname: "home-assistant.coolestdogintheworld.dog"
repo: https://github.com/small-hack/argocd-apps
path: home-assistant/
revision: main
namespace: home-assistant
directory_recursion: false
project:
source_repos:
- http://jessebot.github.io/home-assistant-helm
destination:
namespaces:
- argocd
```
And here's an example for labeled and tainted nodes, where your pod can use tolerations and node affinity
```yaml
apps:
home_assistant:
enabled: false
description: |
[link=https://home-assistant.io]Home Assistant[/link] is a home IOT management solution.
By default, we assume you want to use node affinity and tolerations to keep home assistant pods on certain nodes and keep other pods off said nodes. If you don't want to use either of these features but still want to use the small-hack/argocd-apps repo, first change the argo path to /home-assistant/ and then remove the 'toleration_' and 'affinity' secret_keys from the yaml file under apps.home_assistant.description.
argo:
secret_keys:
hostname: "home-assistant.coolestdogintheworld.dog"
toleration_key: "blutooth"
toleration_operator: "Equals"
toleration_value: "True"
toleration_effect: "NoSchedule"
affinity_key: "blutooth"
affinity_value: "True"
repo: https://github.com/small-hack/argocd-apps
path: home-assistant/toleration_and_affinity/
revision: main
namespace: home-assistant
directory_recursion: false
project:
source_repos:
- http://jessebot.github.io/home-assistant-helm
destination:
namespaces:
- argocd
```
new k3s feature for adding additional nodes
This feature changes k8s_distros.k3s.nodes to be a dictionary so that you can include additional nodes for us to join to the cluster after we create it, but before we install apps.
Here's an example of how you can add a new node to k3s on installation
```yaml
k8s_distros:
k3s:
enabled: false
k3s_yaml:
# if you enable MetalLB, we automatically add servicelb to the disable list
# enables encryption at rest for Kubernetes secrets
secrets-encryption: true
# disables traefik so we can enable ingress-nginx, remove if you're using traefik
disable:
- "traefik"
node-label:
- "ingress-ready=true"
kubelet-arg:
- "max-pods=150"
# nodes to SSH to and join to cluster. example:
nodes:
# name can be a hostname or ip address
serverfriend1.lan:
# change ssh_key to the name of a local private key to use
ssh_key: id_rsa
# must be node type of "worker" or "control_plane"
node_type: worker
# labels are optional, but may be useful for pod node affinity
node_labels:
- iot=true
# taints are optional, but may be useful for pod tolerations
node_taints:
- iot=true:NoSchedule
```
if you don't want to add any nodes, this is what you should change your nodes section to be
```yaml
k8s_distros:
k3s:
enabled: false
k3s_yaml:
# if you enable MetalLB, we automatically add servicelb to the disable list
# enables encryption at rest for Kubernetes secrets
secrets-encryption: true
# disables traefik so we can enable ingress-nginx, remove if you're using traefik
disable:
- "traefik"
node-label:
- "ingress-ready=true"
kubelet-arg:
- "max-pods=150"
# nodes to SSH to and join to cluster. example:
nodes: {}
```
cert-manager now supports DNS01 challenge solver using the Cloudflare provider
This feature reworks the apps.cert_manager.init and apps.cert_manager.argo.secret_keys sections.
Here's an example of using the HTTP01 challenge solver, which would be the only previously supported challenge solver, so if you want everything to just work how it did before your config file should look like this:
HTTP01 config.yml example
```yaml
apps:
cert_manager:
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 optional initialization by creating [link=https://cert-manager.io/docs/configuration/acme/]ACME Issuer type[/link] [link=https://cert-manager.io/docs/concepts/issuer/]ClusterIssuers[/link] using either the HTTP01 or DNS01 challenge solvers. We create two ClusterIssuers: letsencrypt-staging and letsencrypt-staging.
For the DNS01 challange solver, you will need to either export $CLOUDFLARE_API_TOKEN as an env var, or fill in the sensitive value for it each time you run smol-k8s-lab.
Currently, Cloudflare is the only supported DNS provider for the DNS01 challenge solver. If you'd like to use a different DNS provider or use a different Issuer type all together, please either set one up outside of smol-k8s-lab. We also welcome [link=https://github.com/small-hack/smol-k8s-lab/pulls]PRs[/link] to add these features :)
# Initialize of the app through smol-k8s-lab
init:
# Deploys staging and prod ClusterIssuers and prompts you for
# values if they were not set. Switch to false if you don't want
# to deploy any ClusterIssuers
enabled: true
values:
# Used for to generate certs and alert you if they're going to expire
email: "you@emailsforfriends.com"
# choose between "http01" or "dns01"
cluster_issuer_acme_challenge_solver: http01
# only needed if cluster_issuer_challenge_solver set to dns01,
# currently only cloudflare is supported
cluster_issuer_acme_dns01_provider: cloudflare
sensitive_values: []
argo:
secret_keys: {}
# 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
```
And here's how you'd use the new DNS01 feature (keep in mind you need to either provide a sensitive value each time you run smol-k8s-lab, OR you need to export $CLOUDFLARE_API_TOKEN as an env var prior to running smol-k8s-lab).
DNS01 config.yml example
```yaml
apps:
cert_manager:
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 optional initialization by creating [link=https://cert-manager.io/docs/configuration/acme/]ACME Issuer type[/link] [link=https://cert-manager.io/docs/concepts/issuer/]ClusterIssuers[/link] using either the HTTP01 or DNS01 challenge solvers. We create two ClusterIssuers: letsencrypt-staging and letsencrypt-staging.
For the DNS01 challange solver, you will need to either export $CLOUDFLARE_API_TOKEN as an env var, or fill in the sensitive value for it each time you run smol-k8s-lab.
Currently, Cloudflare is the only supported DNS provider for the DNS01 challenge solver. If you'd like to use a different DNS provider or use a different Issuer type all together, please either set one up outside of smol-k8s-lab. We also welcome [link=https://github.com/small-hack/smol-k8s-lab/pulls]PRs[/link] to add these features :)
# Initialize of the app through smol-k8s-lab
init:
# Deploys staging and prod ClusterIssuers and prompts you for
# values if they were not set. Switch to false if you don't want
# to deploy any ClusterIssuers
enabled: true
values:
# Used for to generate certs and alert you if they're going to expire
email: "you@emailsforfriends.com"
# choose between "http01" or "dns01"
cluster_issuer_acme_challenge_solver: dns01
# only needed if cluster_issuer_challenge_solver set to dns01
# currently only cloudflare is supported
cluster_issuer_acme_dns01_provider: cloudflare
sensitive_values:
# can be passed in as env vars if you pre-pend CERT_MANAGER_
# e.g. CERT_MANAGER_CLOUDFLARE_API_TOKEN
- CLOUDFLARE_API_TOKEN
argo:
secret_keys: {}
# 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
```
docs
the docs have been updated with new screenshots and screenshots I forgot before. This fixes #95
last but not least: CI
The ci pipeline for smol-k8s-lab has long been faulty, so this release aims to solve that by making each k8s distro it's own job, so they can be troubleshot independently. This also introduces smol-k8s-lab k3d cli tests via GitHub Actions for the first time 🎉
If you've installed smol-k8s-lab prior to
v3.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 with either pip or pipx:if using pip:
or if using pipx:
If you don't want to delete your config file, please read the breaking changes below...
Breaking config.yml changes between
v2.2.4andv3.0home assistant has graduated from demo app to live app
You'll need to change
apps.home_assistant.argo.pathto eitherhome-assistant/toleration_and_affinity/if you're using node labels and taints, orhome-assistant/if you're deploying to a single node cluster.Here's an example with no tolerations or node affinity
```yaml apps: home_assistant: enabled: false description: | [link=https://home-assistant.io]Home Assistant[/link] is a home IOT management solution. By default, we assume you want to use node affinity and tolerations to keep home assistant pods on certain nodes and keep other pods off said nodes. If you don't want to use either of these features but still want to use the small-hack/argocd-apps repo, first change the argo path to /home-assistant/ and then remove the 'toleration_' and 'affinity' secret_keys from the yaml file under apps.home_assistant.description. argo: secret_keys: hostname: "home-assistant.coolestdogintheworld.dog" repo: https://github.com/small-hack/argocd-apps path: home-assistant/ revision: main namespace: home-assistant directory_recursion: false project: source_repos: - http://jessebot.github.io/home-assistant-helm destination: namespaces: - argocd ```And here's an example for labeled and tainted nodes, where your pod can use tolerations and node affinity
```yaml apps: home_assistant: enabled: false description: | [link=https://home-assistant.io]Home Assistant[/link] is a home IOT management solution. By default, we assume you want to use node affinity and tolerations to keep home assistant pods on certain nodes and keep other pods off said nodes. If you don't want to use either of these features but still want to use the small-hack/argocd-apps repo, first change the argo path to /home-assistant/ and then remove the 'toleration_' and 'affinity' secret_keys from the yaml file under apps.home_assistant.description. argo: secret_keys: hostname: "home-assistant.coolestdogintheworld.dog" toleration_key: "blutooth" toleration_operator: "Equals" toleration_value: "True" toleration_effect: "NoSchedule" affinity_key: "blutooth" affinity_value: "True" repo: https://github.com/small-hack/argocd-apps path: home-assistant/toleration_and_affinity/ revision: main namespace: home-assistant directory_recursion: false project: source_repos: - http://jessebot.github.io/home-assistant-helm destination: namespaces: - argocd ```new k3s feature for adding additional nodes
This feature changes
k8s_distros.k3s.nodesto be a dictionary so that you can include additional nodes for us to join to the cluster after we create it, but before we install apps.Here's an example of how you can add a new node to k3s on installation
```yaml k8s_distros: k3s: enabled: false k3s_yaml: # if you enable MetalLB, we automatically add servicelb to the disable list # enables encryption at rest for Kubernetes secrets secrets-encryption: true # disables traefik so we can enable ingress-nginx, remove if you're using traefik disable: - "traefik" node-label: - "ingress-ready=true" kubelet-arg: - "max-pods=150" # nodes to SSH to and join to cluster. example: nodes: # name can be a hostname or ip address serverfriend1.lan: # change ssh_key to the name of a local private key to use ssh_key: id_rsa # must be node type of "worker" or "control_plane" node_type: worker # labels are optional, but may be useful for pod node affinity node_labels: - iot=true # taints are optional, but may be useful for pod tolerations node_taints: - iot=true:NoSchedule ```if you don't want to add any nodes, this is what you should change your nodes section to be
```yaml k8s_distros: k3s: enabled: false k3s_yaml: # if you enable MetalLB, we automatically add servicelb to the disable list # enables encryption at rest for Kubernetes secrets secrets-encryption: true # disables traefik so we can enable ingress-nginx, remove if you're using traefik disable: - "traefik" node-label: - "ingress-ready=true" kubelet-arg: - "max-pods=150" # nodes to SSH to and join to cluster. example: nodes: {} ```cert-manager now supports DNS01 challenge solver using the Cloudflare provider
This feature reworks the
apps.cert_manager.initandapps.cert_manager.argo.secret_keyssections.Here's an example of using the HTTP01 challenge solver, which would be the only previously supported challenge solver, so if you want everything to just work how it did before your config file should look like this:
HTTP01 config.yml example
```yaml apps: cert_manager: 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 optional initialization by creating [link=https://cert-manager.io/docs/configuration/acme/]ACME Issuer type[/link] [link=https://cert-manager.io/docs/concepts/issuer/]ClusterIssuers[/link] using either the HTTP01 or DNS01 challenge solvers. We create two ClusterIssuers: letsencrypt-staging and letsencrypt-staging. For the DNS01 challange solver, you will need to either export $CLOUDFLARE_API_TOKEN as an env var, or fill in the sensitive value for it each time you run smol-k8s-lab. Currently, Cloudflare is the only supported DNS provider for the DNS01 challenge solver. If you'd like to use a different DNS provider or use a different Issuer type all together, please either set one up outside of smol-k8s-lab. We also welcome [link=https://github.com/small-hack/smol-k8s-lab/pulls]PRs[/link] to add these features :) # Initialize of the app through smol-k8s-lab init: # Deploys staging and prod ClusterIssuers and prompts you for # values if they were not set. Switch to false if you don't want # to deploy any ClusterIssuers enabled: true values: # Used for to generate certs and alert you if they're going to expire email: "you@emailsforfriends.com" # choose between "http01" or "dns01" cluster_issuer_acme_challenge_solver: http01 # only needed if cluster_issuer_challenge_solver set to dns01, # currently only cloudflare is supported cluster_issuer_acme_dns01_provider: cloudflare sensitive_values: [] argo: secret_keys: {} # 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 ```And here's how you'd use the new DNS01 feature (keep in mind you need to either provide a sensitive value each time you run
smol-k8s-lab, OR you need to export$CLOUDFLARE_API_TOKENas an env var prior to runningsmol-k8s-lab).DNS01 config.yml example
```yaml apps: cert_manager: 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 optional initialization by creating [link=https://cert-manager.io/docs/configuration/acme/]ACME Issuer type[/link] [link=https://cert-manager.io/docs/concepts/issuer/]ClusterIssuers[/link] using either the HTTP01 or DNS01 challenge solvers. We create two ClusterIssuers: letsencrypt-staging and letsencrypt-staging. For the DNS01 challange solver, you will need to either export $CLOUDFLARE_API_TOKEN as an env var, or fill in the sensitive value for it each time you run smol-k8s-lab. Currently, Cloudflare is the only supported DNS provider for the DNS01 challenge solver. If you'd like to use a different DNS provider or use a different Issuer type all together, please either set one up outside of smol-k8s-lab. We also welcome [link=https://github.com/small-hack/smol-k8s-lab/pulls]PRs[/link] to add these features :) # Initialize of the app through smol-k8s-lab init: # Deploys staging and prod ClusterIssuers and prompts you for # values if they were not set. Switch to false if you don't want # to deploy any ClusterIssuers enabled: true values: # Used for to generate certs and alert you if they're going to expire email: "you@emailsforfriends.com" # choose between "http01" or "dns01" cluster_issuer_acme_challenge_solver: dns01 # only needed if cluster_issuer_challenge_solver set to dns01 # currently only cloudflare is supported cluster_issuer_acme_dns01_provider: cloudflare sensitive_values: # can be passed in as env vars if you pre-pend CERT_MANAGER_ # e.g. CERT_MANAGER_CLOUDFLARE_API_TOKEN - CLOUDFLARE_API_TOKEN argo: secret_keys: {} # 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 ```docs
the docs have been updated with new screenshots and screenshots I forgot before. This fixes #95
last but not least: CI
The ci pipeline for smol-k8s-lab has long been faulty, so this release aims to solve that by making each k8s distro it's own job, so they can be troubleshot independently. This also introduces smol-k8s-lab k3d cli tests via GitHub Actions for the first time 🎉