From a16827e53acefb9e19072236c152a8aac25eeb57 Mon Sep 17 00:00:00 2001 From: JesseBot Date: Sun, 10 Sep 2023 10:05:27 +0200 Subject: [PATCH] Update README.md - clean up more formatting and add more getting started instructions to readme --- README.md | 77 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 62 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 0b0d6e8ba..72d560a85 100644 --- a/README.md +++ b/README.md @@ -25,9 +25,7 @@ Also helpful for benchmarking various [k8s distros](#supported-k8s-distributions

-## Getting Started - -### Installation +# Installation smol-k8s-lab requires Python 3.11. If you've already got it and [`brew`] installed, you should be able to: ```bash @@ -38,10 +36,53 @@ pip3.11 install smol-k8s-lab smol-k8s-lab --help ``` -### Configuration -We've got a [Quickstart guide](https://small-hack.github.io/smol-k8s-lab/quickstart) for you to jump right in :) +## 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: -Sneak peak... You can create any application you already have in Argo CD by following a simple application schema like this: +```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. + +```yaml +# 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: @@ -52,7 +93,8 @@ apps: argo: # secret keys to pass to Argo CD Application Set Generator secret_keys: - # Used for letsencrypt-staging, to generate certs + # 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. @@ -65,12 +107,14 @@ apps: ref: "main" # namespace to install the k8s app in namespace: "ingress" - # source repos for cert-manager CD App Project (in addition to argo.repo) + # source repos for cert-manager CD App Project (in addition to cert-manager.argo.repo) project_source_repos: - https://charts.jetstack.io ``` -## Under the hood +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 @@ -110,15 +154,13 @@ Version is the helm chart version, or manifest version. 2. Argo CD is optional, but if not installed, smol-k8s-lab will only install: metallb, nginx-ingress, and cert-manager -None of these default, nor the optionally installed, applications are supported or endorsed by their companies/organizations. These are all community maintained Argo CD Application manifests. - ### Optionally Installed Applications | Application/Tool | Description | Initialization Supported | |:----------------:|:------------|:------------------------:| -| [cilium logo][Cilium]
[Cilium]alpha | latest | Kubernetes netflow visualizer and policy editor | Yes | -| [kyvero logo][Kyverno]
[Kyverno]alpha | latest | Kubernetes native policy management to enforce policies on k8s resources | No | +| [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 | @@ -127,7 +169,7 @@ Version is the helm chart version, or manifest version. | [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 | +| [k9s logo, outline of dog with ship wheels for eyes][k9s]
[k9s] | Terminal based dashboard for kubernetes | Yes | ## Troubleshooting @@ -166,20 +208,25 @@ Want to get started with argocd? If you've installed it via smol-k8s-lab, then y [ESO]: https://external-secrets.io/v0.8.1/ +[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/ [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/ [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 +[loki]: https://grafana.com/oss/loki/ [Mastodon]: https://joinmastodon.org/ [matrix]: https://matrix.org/ [minio]: https://min.io/ -[Prometheus Stack]: https://github.com/small-hack/argocd-apps/tree/main/prometheus [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/ +[restic]: https://restic.readthedocs.io/en/stable/ [Vouch]: https://github.com/jessebot/vouch-helm-chart [Zitadel]: https://github.com/zitadel/zitadel-charts/tree/main