From 409c2775b60cd4ee347708e8ad0548fab7c5c82f Mon Sep 17 00:00:00 2001 From: Brian May Date: Thu, 28 Nov 2024 12:26:25 +1100 Subject: [PATCH] docs: further documentation changes --- README.md | 64 +++++++++++++------ .../envs/dev/dev-cluster/config.yaml | 2 +- .../kube-prometheus-stack/config.yaml | 2 +- 3 files changed, 46 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index eb57044..57aa951 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # helmci -helmci is a program that takes a set of helm release values, typically from a dedicated repo, and automatically deploys them to a Kubernetes cluster. +helmci is a program that takes a set of helm release values, typically from a +dedicated repo, and automatically deploys them to a Kubernetes cluster. ## Quick Start @@ -16,8 +17,10 @@ helm plugin install https://github.com/databus23/helm-diff Edit kubectl context in `example/helm-values/envs/dev/dev-cluster/config.yaml`. -There are three output methods. By default the text output is used if nothing else specified. -Add `--output text` (gitlab flavoured text), `--output slack` or `--output tui` full screen text mode to the following commands. By default `text` is used. +There are three output methods. By default the text output is used if nothing +else specified. Add `--output text` (gitlab flavoured text), `--output slack` +or `--output tui` full screen text mode to the following commands. By default +`text` is used. The `tui` full screen text mode has the following keyboard bindings: @@ -31,7 +34,7 @@ The `tui` full screen text mode has the following keyboard bindings: - `left`/`right` scroll the details pane left/right. Edit the `./example/helm-values/envs/dev/dev-cluster/config.yaml` file and -insert the arn of an available cluster. +insert the context of an available cluster. Run commands such as: @@ -57,7 +60,8 @@ Use `--cluster=dev-cluster` to limit releases to that cluster. Use `--env=dev` to limit releases to that env. -Use `--release-filter` to apply more filters. Supported are `chart_type`, `chart_name` and `release_name`. +Use `--release-filter` to apply more filters. Supported are `chart_type`, +`chart_name` and `release_name`. Example: @@ -118,11 +122,20 @@ The helm diff will compare against the previous helm install. If you made changes to the kerbernetes yaml files directly, then changes may not be detected, and you might have to bypass the diff check. -The `-b` or `--bypass-upgrade-on-no-changes` option allows you to bypass the upgrade process if no changes are detected. This can be useful to save time and resources when you are confident that no changes have been made to the release values. +The `-b` or `--bypass-upgrade-on-no-changes` option allows you to bypass the +upgrade process if no changes are detected. This can be useful to save time and +resources when you are confident that no changes have been made to the release +values. -The `-y` or `--yes` suboption can be used in conjunction with the `--bypass-upgrade-on-no-changes` option to automatically proceed with the upgrade even if no changes are detected. This is useful for automated scripts where manual intervention is not possible. +The `-y` or `--yes` suboption can be used in conjunction with the +`--bypass-upgrade-on-no-changes` option to automatically proceed with the +upgrade even if no changes are detected. This is useful for automated scripts +where manual intervention is not possible. -The `-n` or `--no` suboption can be used in conjunction with the `--bypass-upgrade-on-no-changes` option to automatically skip the upgrade if no changes are detected. This is useful when you want to ensure that upgrades are only performed when necessary without manual intervention. +The `-n` or `--no` suboption can be used in conjunction with the +`--bypass-upgrade-on-no-changes` option to automatically skip the upgrade if no +changes are detected. This is useful when you want to ensure that upgrades are +only performed when necessary without manual intervention. If neither `--no` or `--yes` are supplied then `--no` is assumed. @@ -145,18 +158,19 @@ You can have zero or more environments. An environment can have zero or more clusters. -A cluster can have zero or more releases, which corresponds to a helm release that gets installed. +A cluster can have zero or more releases, which corresponds to a helm release +that gets installed. ### Environment config ```yaml -cat example/helm-values/envs/dev/config.yaml locked: false ``` - Setting `locked` to true disables all releases under the env. -The name of the directory corresponds to the name of the environment. In the above case it will be called `dev`. +The name of the directory corresponds to the name of the environment. In the +above case it will be called `dev`. ### Cluster config @@ -170,11 +184,14 @@ locked: false - `context` is the `--kube-context` parameter passed to helm. - Setting `locked` to true disables all releases under the cluster dir. -The name of the directory corresponds to the name of the cluster. Which can be different from the context value provided. In the above example, the cluster is called `dev-cluster` and uses the parameter `--kube-context 1234-dev-cluster`. +The name of the directory corresponds to the name of the cluster. Which can be +different from the context value provided. In the above example, the cluster is +called `dev-cluster` and uses the parameter `--kube-context 1234-dev-cluster`. ### Release config -For example `example/helm-values/envs/dev/dev-cluster/kube-prometheus-stack/config.yaml`: +For example +`example/helm-values/envs/dev/dev-cluster/kube-prometheus-stack/config.yaml`: ```yaml auto: true @@ -194,15 +211,19 @@ depends: [] - Setting `locked` to false disables all deploys. - `namespace` is the kubernetes namespace to use for deploys. - `release` is the release name for the helm chart. -- `depends` is a list of releases that must be installed first. `$namespace/$release` format. +- `depends` is a list of releases that must be installed first. + `$namespace/$release` format. - `release_chart` is how to find the chart to install (see below). -Note: the value of the `release` is used as the release name, not the name of the directory. +Note: the value of the `release` is used as the release name, not the name of +the directory. -The `values.yaml` and (optionally) `values.secrets` files contain the helm values. Note `values.secrets` can be encrypted, but if so must be decrypted using whatever mechanism before running helmci. +The `values.yaml` and (optionally) `values.secrets` files contain the helm +values. Note `values.secrets` can be encrypted, but if so must be decrypted +using whatever mechanism before running helmci. There is also a `lock.json` file for each release that contains meta -information for the downloaded chart. +information for the downloaded chart. This file is managed automatically. ### Helm chart config @@ -237,7 +258,8 @@ release_chart: ## History -There are a number of existing solutions of deploying stuff on a kubernetes cluster. The main contenders are: +There are a number of existing solutions of deploying stuff on a kubernetes +cluster. The main contenders are: - [argocd](https://argoproj.github.io/cd/) - [spinnaker](https://spinnaker.io/) @@ -246,11 +268,13 @@ There are a number of existing solutions of deploying stuff on a kubernetes clus Unfortunately, these all had limitations: - argocd, while it supports helm charts, it does not support saving helm values in git. -- Can overcome this issue by creating git repo of charts containing helm sub-charts, but this is ugly and requires modifying the helm values. +- Can overcome this issue by creating git repo of charts containing helm + sub-charts, but this is ugly and requires modifying the helm values. - spinnaker seems rather heavy weight to install, haven't succeeded yet. - harness is mostly proprietary solution. -As a result a Python program was written as an alternative solution. This is a rewrite of the Python program. +As a result a Python program was written as an alternative solution. The Python +program was never released outside EA. This is a rewrite of the Python program. ## Current Limitations diff --git a/example/helm-values/envs/dev/dev-cluster/config.yaml b/example/helm-values/envs/dev/dev-cluster/config.yaml index bded123..ffcf794 100644 --- a/example/helm-values/envs/dev/dev-cluster/config.yaml +++ b/example/helm-values/envs/dev/dev-cluster/config.yaml @@ -1,2 +1,2 @@ -context: dev-cluster +context: arn:aws:eks:us-east-2:136983895179:cluster/muspelheim locked: false diff --git a/example/helm-values/envs/dev/dev-cluster/kube-prometheus-stack/config.yaml b/example/helm-values/envs/dev/dev-cluster/kube-prometheus-stack/config.yaml index de05ad5..2c90fe7 100644 --- a/example/helm-values/envs/dev/dev-cluster/kube-prometheus-stack/config.yaml +++ b/example/helm-values/envs/dev/dev-cluster/kube-prometheus-stack/config.yaml @@ -7,5 +7,5 @@ release_chart: type: helm repo_url: https://prometheus-community.github.io/helm-charts chart_name: kube-prometheus-stack - chart_version: 35.5.1 + chart_version: '35.5.1' depends: []