diff --git a/.github/workflows/build-docs.yaml b/.github/workflows/build-docs.yaml new file mode 100644 index 000000000..2cee685c0 --- /dev/null +++ b/.github/workflows/build-docs.yaml @@ -0,0 +1,30 @@ +name: mkdocs-build-and-publish +on: + push: + branches: + - main +permissions: + contents: write +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - uses: actions/setup-python@v4 + with: + python-version: 3.x + + - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV + + - uses: actions/cache@v3 + with: + key: mkdocs-material-${{ env.cache_id }} + path: .cache + restore-keys: | + mkdocs-material- + + - run: pip install mkdocs-material + + - run: mkdocs gh-deploy --force + diff --git a/.stylelintrc.json b/.stylelintrc.json new file mode 100644 index 000000000..ee85d9b18 --- /dev/null +++ b/.stylelintrc.json @@ -0,0 +1,3 @@ +{ + "extends": "stylelint-config-standard" +} \ No newline at end of file diff --git a/README.md b/README.md index 4505b7161..0afea80de 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Also helpful for benchmarking various [k8s distros](#supported-k8s-distributions

- + Output of smol-k8s-lab --help after cloning the directory and installing the prerequisites.

@@ -42,7 +42,8 @@ smol-k8s-lab --help After you've followed the installation instructions, if you're *new* to `smol-k8s-lab`, initialize a new config file. To do that, just run: ```bash -# we'll walk you through any configuration needed before saving the config and deploying it for you +# we'll walk you through any configuration needed before +# saving the config and deploying it for you smol-k8s-lab ``` @@ -101,9 +102,6 @@ apps: # 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: "" - # If set to "", we'll instead use the repo, path, ref, namespace, and project_source_repos - # else we'll skip installing this app b/c its part of another app of apps with this name. - part_of_app_of_apps: "" # 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! @@ -127,9 +125,9 @@ We always install the latest version of Kubernetes that is available from the di | Distro | Description | |:----------:|:------------------------------------------------------| -| [][k3s]
[k3s] | The certified Kubernetes distribution built for IoT & Edge computing | -| [][k3d]
[k3d] | **ALPHA - TESTING PHASE** k3s in docker 🐳 | -| [][KinD]
[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. | +| [][k3s]
[k3s] | The certified Kubernetes distribution built for IoT & Edge computing | +| [][k3d]
[k3d] | **ALPHA - TESTING PHASE** k3s in docker 🐳 | +| [][KinD]
[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. @@ -138,16 +136,16 @@ Version is the helm chart version, or manifest version. | Application | Description | Initialization Supported | |:-------------------------------:|:------------------------------------------------------|:------------------------:| -| [metallb logo, blue arrow pointing up, with small line on one leg of arrow to show balance][metallb]
[metallb] | Loadbalancer and IP Address pool manager for metal | Yes | -| [nginx logo, white letter N with green background][ingress-nginx]
[ingress-nginx] | The ingress controller allows access to the cluster remotely, needed for web traffic | No | -| [cert manager logo][cert-manager]
[cert-manager] | For SSL/TLS certificates | Yes | -| [argo CD logo, an organer squid wearing a fishbowl helmet][Argo CD]
[Argo CD] | Gitops - Continuous Deployment | Yes | -| [argo CD logo, an organer squid wearing a fishbowl helmet][Argo CD Appset Secret Plugin]
[Argo CD Appset Secret Plugin] | Gitops - Continuous Deployment | Yes | -| [ESO logo, outline of robot with astricks in a screen in it's belly][ESO]
[ESO] | external-secrets-operator integrates external secret management systems like Bitwarden or GitLab | No | -| [ESO logo, again][Bitwarden ESO Provider]
[Bitwarden ESO Provider] | Bitwarden external-secrets-operator provider | Yes | -| [Zitadel logo, an orange arrow pointing left][Zitadel]
[Zitadel] | An identity provider and OIDC provider to provide SSO | Yes | -| [Vouch logo, the letter V in rainbow ][Vouch]
[Vouch] | Vouch proxy allows you to secure web pages that lack authentication e.g. prometheus | Yes | -| [Prometheus logo, a torch][Prometheus Stack]
[Prometheus Stack] | Prometheus monitoring and logging stack using [loki]/[promtail], [alert manager], and [grafana] | Yes | +| [metallb logo, blue arrow pointing up, with small line on one leg of arrow to show balance][metallb]
[metallb] | Loadbalancer and IP Address pool manager for metal | Yes | +| [nginx logo, white letter N with green background][ingress-nginx]
[ingress-nginx] | The ingress controller allows access to the cluster remotely, needed for web traffic | No | +| [cert manager logo][cert-manager]
[cert-manager] | For SSL/TLS certificates | Yes | +| [argo CD logo, an organer squid wearing a fishbowl helmet][Argo CD]
[Argo CD] | Gitops - Continuous Deployment | Yes | +| [argo CD logo, an organer squid wearing a fishbowl helmet][Argo CD Appset Secret Plugin]
[Argo CD Appset Secret Plugin] | Gitops - Continuous Deployment | Yes | +| [ESO logo, outline of robot with astricks in a screen in it's belly][ESO]
[ESO] | external-secrets-operator integrates external secret management systems like Bitwarden or GitLab | No | +| [ESO logo, again][Bitwarden ESO Provider]
[Bitwarden ESO Provider] | Bitwarden external-secrets-operator provider | Yes | +| [Zitadel logo, an orange arrow pointing left][Zitadel]
[Zitadel] | An identity provider and OIDC provider to provide SSO | Yes | +| [Vouch logo, the letter V in rainbow ][Vouch]
[Vouch] | Vouch proxy allows you to secure web pages that lack authentication e.g. prometheus | Yes | +| [Prometheus logo, a torch][Prometheus Stack]
[Prometheus Stack] | Prometheus monitoring and logging stack using [loki]/[promtail], [alert manager], and [grafana] | Yes | **Minor Notes** @@ -163,17 +161,17 @@ Version is the helm chart version, or manifest version. | Application/Tool | Description | Initialization Supported | |:----------------:|:------------|:------------------------:| -| [cilium logo][Cilium]
[Cilium]alpha | Kubernetes netflow visualizer and policy editor | Yes | -| [kyvero logo][Kyverno]
[Kyverno]alpha | Kubernetes native policy management to enforce policies on k8s resources | No | -| [keycloak logo][Keycloak]
[KeyCloak]alpha | Self hosted IAM/Oauth2 solution | Yes | -| [kepler logo][kepler]
[kepler] | Kepler (Kubernetes Efficient Power Level Exporter) uses eBPF to probe energy-related system stats and exports them as Prometheus metrics. | Yes | -| [k8up logo, a minimalist logo of a small blue hill with line starting the right going into the hill][k8up]
[k8up] | Backups operator using [restic] to backup to s3 endpoints | Yes | -| [k8tz logo, the k8s logo but with a watch in the center instead of the ship wheel][k8tz]
[k8tz] | Timezone environment variable injector for pods and cronjobs | Yes | -| [nextcloud logo, 3 white circles touching eachother on a blue background][Nextcloud]
[Nextcloud] | Nextcloud is a self hosted file server | Yes | -| [Mastodon logo, a white M in a purple chat bubble][Mastodon]
[Mastodon] | Mastodon is a self hosted federated social media network | Yes | -| [Matrix logo][matrix]
[matrix] | Matrix is a self hosted chat platform | Yes | -| [minio logo, a minimalist drawing in red of a crane][minio]
[minio] | Self hosted S3 Object Store operator | Yes | -| [k9s logo, outline of dog with ship wheels for eyes][k9s]
[k9s] | Terminal based dashboard for Kubernetes | Yes | +| [cilium logo][Cilium]
[Cilium]alpha | Kubernetes netflow visualizer and policy editor | Yes | +| [kyvero logo][Kyverno]
[Kyverno]alpha | Kubernetes native policy management to enforce policies on k8s resources | No | +| [keycloak logo][Keycloak]
[KeyCloak]alpha | Self hosted IAM/Oauth2 solution | Yes | +| [kepler logo][kepler]
[kepler] | Kepler (Kubernetes Efficient Power Level Exporter) uses eBPF to probe energy-related system stats and exports them as Prometheus metrics. | Yes | +| [k8up logo, a minimalist logo of a small blue hill with line starting the right going into the hill][k8up]
[k8up] | Backups operator using [restic] to backup to s3 endpoints | Yes | +| [k8tz logo, the k8s logo but with a watch in the center instead of the ship wheel][k8tz]
[k8tz] | Timezone environment variable injector for pods and cronjobs | Yes | +| [nextcloud logo, 3 white circles touching eachother on a blue background][Nextcloud]
[Nextcloud] | Nextcloud is a self hosted file server | Yes | +| [Mastodon logo, a white M in a purple chat bubble][Mastodon]
[Mastodon] | Mastodon is a self hosted federated social media network | Yes | +| [Matrix logo][matrix]
[matrix] | Matrix is a self hosted chat platform | Yes | +| [minio logo, a minimalist drawing in red of a crane][minio]
[minio] | Self hosted S3 Object Store operator | Yes | +| [k9s logo, outline of dog with ship wheels for eyes][k9s]
[k9s] | Terminal based dashboard for Kubernetes | Yes | ## Troubleshooting diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index ea648890b..000000000 --- a/docs/_config.yml +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Smol K8s Lab" -remote_theme: just-the-docs/just-the-docs -color_scheme: "new_colors" -search_enabled: true -permalink: pretty -url: "https://jessebot.github.io/smol-k8s-lab" -# Aux links for the upper right navigation -aux_links: - "smol-k8s-lab on GitHub": - - "//github.com/jessebot/smol-k8s-lab" - -plugins: - - jekyll-seo-tag diff --git a/docs/index.md b/docs/index.md index 7223be065..1b0560fcb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,30 +1,199 @@ -## ☁️ *smol k8s lab* 🧸 -[Output of smol-k8s-lab --help after cloning the directory and installing the prerequisites.](https://raw.githubusercontent.com/jessebot/smol-k8s-lab/main/docs/screenshots/help_text.svg) +

+🧸 Smol K8s Lab

-A project aimed at getting up and running quickly with mostly smaller k8s distros in one small command line script. +

+Smol K8s Lab leverages ArgoCD and slim k8s distributions like K3s to create production-like environments via a declartive workflow. Batteries and 🦑 included. +

+

+ + + +

+

+ + Output of smol-k8s-lab --help after cloning the directory and installing the prerequisites. + +

-### Stack We Install on K8s +## About + +By default, Smol K8s Lab deploys ArgoCD + a secret plugin generator which enables ArgoCD to securely manage your lab via files in public open-source git repos. Additionally, a customized dark-theme is provided for ArgoCD's incredibly useful web-interface. + +Smol K8s Lab's declarative workflow enables rapid itteration in production-like environments with minimal costs for failure. This makes it ideal for proof-of-concepts, prototyping, and benchmarking k8s applicatons and distributions! 💙
+ + +## Installation + +Smol K8s Lab requires Python 3.11 and brew. An installer script is provided below to install the proper dependancies on Ubuntu 22.04, Debain12, or MacOS 13.0+ hosts. + +If you do NOT have the required dependancies: + +- Download [setup.sh](https://github.com/jessebot/onboardme/blob/main/setup.sh) to your current directory and execute it. This is a generic provisioning script that will install Python 3.11, Brew, and a select few other pacakages used throughout our repos. + + ```bash + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/jessebot/onboardme/main/setup.sh)" + ``` + +If you DO have Python 3.11 and brew installed: + +- Install the CLI + + ```bash + pip3.11 install smol-k8s-lab + ``` + +- Check the help menu before proceeding + + ```bash + smol-k8s-lab --help + ``` + +## Usage + +### Initialization +After you've followed the installation instructions, if you're *new* to `smol-k8s-lab`, initialize a new config file. To do that, just run: + +```bash +# we'll walk you through any configuration needed before saving the config and deploying it for you +smol-k8s-lab +``` + +
+

Upgrading 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: + +```yaml +# this upgrades smol-k8s-lab +pip3.11 install --upgrade smol-k8s-lab + +# this initializes a new configuration +smol-k8s-lab +``` + +
+ +#### Creating a new config without running smol-k8s-lab +This is helpful if you just want to take a look at the default configuration before installing any kubernetes distros. This will also allow you to disable any default applications you'd like ahead of time. + +```bash +# create the needed directory if you haven't already, NOTE: this can also be in $XDG_CONFIG_HOME/smol-k8s-lab/config.yaml +mkdir -p ~/.config/smol-k8s-lab + +# download the default config file +curl -o config.yaml https://raw.githubusercontent.com/small-hack/smol-k8s-lab/main/smol_k8s_lab/config/default_config.yaml + +# move the config file to the config directory (can also be $XDG_CONFIG_HOME/smol-k8s-lab/config.yaml) +mv config.yaml ~/.config/smol-k8s-lab/config.yaml +``` + +You can now use your text editor of choice to view and edit the default config before running `smol-k8s-lab` :) + +## Configuration +You can checkout the default config file [here](./smol_k8s_lab/config/default_config.yaml). We've also got a [Quickstart guide](https://small-hack.github.io/smol-k8s-lab/quickstart) for you to jump right in :) + +### 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: + +```yaml +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: "" + # If set to "", we'll instead use the repo, path, ref, namespace, and project_source_repos + # else we'll skip installing this app b/c its part of another app of apps with this name. + part_of_app_of_apps: "" + # 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 afilliated 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 | +|:----------:|:------------------------------------------------------| +| [][k0s]
[k0s] | Simple, Solid & Certified Kubernetes Distribution
⚠️ testing| +| [][k3s]
[k3s] | The certified Kubernetes distribution built for IoT & Edge computing | +| [][k3d]
[k3d] | K3d is k3s in Docker 🐳.
⚠️ testing | +| [][KinD]
[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 Version is the helm chart version, or manifest version. -| Application | Version | Description | -|:-------------------------------:|:-------------:|:------------------------------------------------------| -| 🐄 [Local Path Provisioner] | k3s latest | Default simple local file storage for persistent data | -| [nginx logo, white letter N with green background][nginx-ingress]
[nginx-ingress] | 4.4.0 | The ingress controller allows access to the cluster remotely, needed for web traffic | -| [cert manager logo][cert-manager]
[cert-manager] | 1.10.1 | For SSL/TLS certificates | -| [k9s logo, outline of dog with ship wheels for eyes][k9s]
[k9s] | latest | Terminal based dashboard for kubernetes | +| Application | Description | Initialization Supported | +|:-------------------------------:|:------------------------------------------------------|:------------------------:| +| [metallb logo, blue arrow pointing up, with small line on one leg of arrow to show balance][metallb]
[metallb] | Loadbalancer and IP Address pool manager for metal | Yes | +| [nginx logo, white letter N with green background][ingress-nginx]
[ingress-nginx] | The ingress controller allows access to the cluster remotely, needed for web traffic | No | +| [cert manager logo][cert-manager]
[cert-manager] | For SSL/TLS certificates | Yes | +| [argo CD logo, an organer squid wearing a fishbowl helmet][Argo CD]
[Argo CD] | Gitops - Continuous Deployment | Yes | +| [argo CD logo, an organer squid wearing a fishbowl helmet][Argo CD Appset Secret Plugin]
[Argo CD Appset Secret Plugin] | Gitops - Continuous Deployment | Yes | +| [ESO logo, outline of robot with astricks in a screen in it's belly][ESO]
[ESO] | external-secrets-operator integrates external secret management systems like Bitwarden or GitLab | No | +| [ESO logo, again][Bitwarden ESO Provider]
[Bitwarden ESO Provider] | Bitwarden external-secrets-operator provider | Yes | +| [Zitadel logo, an orange arrow pointing left][Zitadel]
[Zitadel] | An identity provider and OIDC provider to provide SSO | Yes | +| [Vouch logo, the letter V in rainbow ][Vouch]
[Vouch] | Vouch proxy allows you to secure web pages that lack authentication e.g. prometheus | Yes | +| [Prometheus logo, a torch][Prometheus Stack]
[Prometheus Stack] | Prometheus monitoring and logging stack using [loki]/[promtail], [alert manager], and [grafana] | Yes | + +Minor Notes: -#### Optionally installed +>All Default Applications can be disabled through your `~/.config/smol-k8s-lab/config.yaml` file, **except**: +> +> - ingress-nginx is the currently the only supported ingress-controller. traefik support is being worked on. +> +> - Argo CD is optional, but if not installed, smol-k8s-lab will only install: metallb, nginx-ingress, and cert-manager -| Application/Tool | Version | Description | -|:----------------:|:-------------:|:------------| -| [metallb logo, blue arrow pointing up, with small line on one leg of arrow to show balance][metallb]
[metallb] | 0.13.7 | loadbalancer for metal, since we're mostly selfhosting | -| [argo CD logo, an organer squid wearing a fishbowl helmet][Argo CD]
[Argo CD] | 5.16.2 | Gitops - Continuous Deployment | -| [ESO logo, outline of robot with astricks in a screen in it's belly][ESO]
[ESO] | 0.6.1 | external-secrets-operator integrates external secret management systems like GitLab| -| [kyvero logo][Kyverno]
[Kyverno] | latest | Kubernetes native policy management to enforce policies on k8s resources | +## Optionally Installed Applications -### Tooling Used for the CLI itself and interface +| Application/Tool | Description | Initialization Supported | +|:----------------:|:------------|:------------------------:| +| [cilium logo][Cilium]
[Cilium]alpha | Kubernetes netflow visualizer and policy editor | Yes | +| [kyvero logo][Kyverno]
[Kyverno]alpha | Kubernetes native policy management to enforce policies on k8s resources | No | +| [keycloak logo][Keycloak]
[KeyCloak]alpha | Self hosted IAM/Oauth2 solution | Yes | +| [kepler logo][kepler]
[kepler] | Kepler (Kubernetes Efficient Power Level Exporter) uses eBPF to probe energy-related system stats and exports them as Prometheus metrics. | Yes | +| [k8up logo, a minimalist logo of a small blue hill with line starting the right going into the hill][k8up]
[k8up] | Backups operator using [restic] to backup to s3 endpoints | Yes | +| [k8tz logo, the k8s logo but with a watch in the center instead of the ship wheel][k8tz]
[k8tz] | Timezone environment variable injector for pods and cronjobs | Yes | +| [nextcloud logo, 3 white circles touching eachother on a blue background][Nextcloud]
[Nextcloud] | Nextcloud is a self hosted file server | Yes | +| [Mastodon logo, a white M in a purple chat bubble][Mastodon]
[Mastodon] | Mastodon is a self hosted federated social media network | Yes | +| [Matrix logo][matrix]
[matrix] | Matrix is a self hosted chat platform | Yes | +| [minio logo, a minimalist drawing in red of a crane][minio]
[minio] | Self hosted S3 Object Store operator | Yes | +| [k9s logo, outline of dog with ship wheels for eyes][k9s]
[k9s] | Terminal based dashboard for kubernetes | Yes | + + +## Troubleshooting +If you're stuck, checkout the [Notes](https://jessebot.github.io/smol-k8s-lab/notes) to see if we also got stuck on the same thing at some point :) Under each kubernetes distro or application, we'll have notes on how to learn more about it, as well as any errors we've already battled. + + +# Status +This is still in later alpha, as we figure out all the apps and distros we want to support, and pin all the versions, but if you'd like to contribute or just found a :bug:, feel free to open an issue (or pull request), and we'll take a look! We'll try to get back to you asap! + + +## Development smol-k8s-lab is written in Python and built and published using [Poetry]. You can check out the `pyproject.toml` for the versions of each library we install below: - [rich] (this is what makes all the pretty formatted text) @@ -36,24 +205,64 @@ We also utilize the [Bitwarden cli], for a password manager so you never have to ## Things we don't handle -### 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. +1. 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. + +2. 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. ### Troubleshooting + If you're stuck, checkout the [Notes section](https://jessebot.github.io/smol-k8s-lab/notes) to see if we also got stuck on the same thing at some point :) +## And more! + +Want to get started with argocd? If you've installed it via smol-k8s-lab, then you can jump [here](https://github.com/jessebot/argo-example#argo-via-the-gui). Otherwise, if you want to start from scratch, start [here](https://github.com/jessebot/argo-example#argocd) -[metallb]: https://github.io/metallb/metallb "metallb" [Local Path Provisioner]: https://github.com/rancher/local-path-provisioner [nginx-ingress]: https://github.io/kubernetes/ingress-nginx -[cert-manager]: https://cert-manager.io/docs/ -[k9s]: https://k9scli.io/topics/install/ - -[Argo CD]: https://github.io/argoproj/argo-helm -[ESO]: https://external-secrets.io/v0.5.9/ + +[k3s]: https://k3s.io/ +[k3d]: https://k3d.io/ +[KinD]: https://kind.sigs.k8s.io/ +[k0s]: https://k0sproject.io/ + + +[ESO]: https://external-secrets.io +[alert manager]: https://prometheus.io/docs/alerting/latest/alertmanager/ +[Argo CD]:https://argo-cd.readthedocs.io/en/latest/ +[Argo CD Appset Secret Plugin]: https://github.com/jessebot/argocd-appset-secret-plugin/ + +[cert-manager]: https://cert-manager.io/docs/ +[cilium]: https://github.com/cilium/cilium/tree/v1.14.1/install/kubernetes/cilium +[Bitwarden ESO Provider]: https://github.com/jessebot/bitwarden-eso-provider +[grafana]: https://grafana.com/ +[ingress-nginx]: https://github.io/kubernetes/ingress-nginx +[k8tz]: https://github.com/small-hack/argocd-apps/tree/main/alpha/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 +[Keycloak]: https://github.com/bitnami/charts/tree/main/bitnami/keycloak/templates +[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 "metallb" +[minio]: https://min.io/ +[Nextcloud]: https://github.com/nextcloud/helm +[Prometheus Stack]: https://github.com/small-hack/argocd-apps/tree/main/prometheus +[promtail]: https://grafana.com/docs/loki/latest/send-data/promtail/ +[Vouch]: https://github.com/jessebot/vouch-helm-chart +[Zitadel]: https://github.com/zitadel/zitadel-charts/tree/main + + +[`brew`]: https://brew.sh +[k9s]: https://k9scli.io/topics/install/ +[restic]: https://restic.readthedocs.io/en/stable/ [Poetry]: https://python-poetry.org/ diff --git a/docs/index.old b/docs/index.old new file mode 100644 index 000000000..a746f484f --- /dev/null +++ b/docs/index.old @@ -0,0 +1,88 @@ +

☁️ smol k8s lab 🧸

+ +

Quickly deploy a minimal, production-like k8s environment in one command line script.

+ + +## Supported k8s distributions +We always install the latest version of kubernetes that is available from the distro's startup script. We tend to test on k3s first, then kind. K0s support is experimental. + +| Distro | Description | +|:----------:|:------------------------------------------------------| +| [][k0s]
[k0s] | Simple, Solid & Certified Kubernetes Distribution | +| [][k3s]
[k3s] | The certified Kubernetes distribution built for IoT & Edge computing | +| [][KinD]
[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. | + + + + +## Core Components +Version is the helm chart version, or manifest version. + +| Application | Version | Description | +|:-------------------------------:|:-------------:|:------------------------------------------------------| +| 🐄 [Local Path Provisioner] | k3s latest | Default simple local file storage for persistent data | +| [nginx logo, white letter N with green background][nginx-ingress]
[nginx-ingress](https://kubernetes.github.io/ingress-nginx/) | 4.4.0 | The ingress controller allows access to the cluster remotely, needed for web traffic | +| [cert manager logo][cert-manager]
[cert-manager](https://cert-manager.io/docs/) | 1.10.1 | For SSL/TLS certificates | +| [k9s logo, outline of dog with ship wheels for eyes][k9s]
[k9s](https://k9scli.io/topics/install/) | latest | Terminal based dashboard for kubernetes | + + +## Optional Packages + +| Application/Tool | Version | Description | +|:----------------:|:-------------:|:------------| +| [metallb logo, blue arrow pointing up, with small line on one leg of arrow to show balance][metallb]
[metallb](https://github.io/metallb/metallb) | 0.13.7 | loadbalancer for metal, since we're mostly selfhosting | +| [argo CD logo, an organer squid wearing a fishbowl helmet][Argo CD]
[Argo CD](https://argo-cd.readthedocs.io/en/stable/) |5.16.2 | Gitops - Continuous Deployment | +| [ESO logo, outline of robot with astricks in a screen in it's belly][ESO]
[ESO](https://external-secrets.io/latest/) | 0.6.1 | external-secrets-operator integrates external secret management systems like GitLab| +| [kyvero logo][Kyverno]
[Kyverno](https://github.com/kyverno/kyverno/) | latest | Kubernetes native policy management to enforce policies on k8s resources | +| [minio logo][Minio]
[Minio](https://min.io/) | latest | MinIO is a high-performance, S3 compatible object store. | + + + +## Tooling Used for the CLI itself and interface +smol-k8s-lab is written in Python and built and published using [Poetry]. You can check out the `pyproject.toml` for the versions of each library we install below: + +- [rich](https://github.com/Textualize/richP): this is what makes all the pretty formatted text +- [PyYAML](https://pyyaml.org/): to handle the k8s yamls and configs +- [bcrypt](https://pypi.org/project/bcrypt/): to pass a password to argocd and automatically update your Bitwarden +- [click](https://pypi.org/project/click/): handles arguments for the CLI + +We also utilize the [Bitwarden cli](https://bitwarden.com/help/cli/), for a password manager so you never have to see/know your argocd password. + +## Things we don't do + +- Forwarding ports 80 and 443 on your router + + 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. + +- SSL/TLS for endpoints on private networks + + We expect the user to provide an endpoint that is reachable by letsencrypt. After SSL is working (if it's not, follow the steps in the [cert-manager common error troubleshooting guide](https://cert-manager.io/docs/faq/acme/#common-errors)), you can also change the `letsencrypt-staging` value to `letsencrypt-prod` for any domains you own and can configure to point to your cluster via DNS. + +### Troubleshooting +If you're stuck, checkout the [Notes section](https://jessebot.github.io/smol-k8s-lab/notes) to see if we also got stuck on the same thing at some point :) + + + +[k3s]: https://k3s.io/ +[KinD]: https://kind.sigs.k8s.io/ +[k0s]: https://k0sproject.io/ + + +[metallb]: https://github.io/metallb/metallb "metallb" +[Local Path Provisioner]: https://github.com/rancher/local-path-provisioner +[nginx-ingress]: https://github.io/kubernetes/ingress-nginx +[cert-manager]: https://cert-manager.io/docs/ +[k9s]: https://k9scli.io/topics/install/ + + +[Argo CD]: https://github.io/argoproj/argo-helm +[ESO]: https://external-secrets.io/ +[Kyverno]: https://github.com/kyverno/kyverno/ + + +[Poetry]: https://python-poetry.org/ +[rich]: https://github.com/Textualize/richP +[PyYAML]: https://pyyaml.org/ +[bcrypt]: https://pypi.org/project/bcrypt/ +[click]: https://pypi.org/project/click/ +[Bitwarden cli]: https://bitwarden.com/help/cli/ diff --git a/docs/mathjax.js b/docs/mathjax.js new file mode 100644 index 000000000..bf37d7453 --- /dev/null +++ b/docs/mathjax.js @@ -0,0 +1,16 @@ +window.MathJax = { + tex: { + inlineMath: [["\\(", "\\)"]], + displayMath: [["\\[", "\\]"]], + processEscapes: true, + processEnvironments: true + }, + options: { + ignoreHtmlClass: ".*|", + processHtmlClass: "arithmatex" + } + }; + + document$.subscribe(() => { + MathJax.typesetPromise() + }) \ No newline at end of file