docs: update documentation

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:
 
@@ -30,6 +33,9 @@ The `tui` full screen text mode has the following keyboard bindings:
 - `pg up`/`pg down`: Scroll the details pane up/down.
 - `left`/`right` scroll the details pane left/right.
 
+Edit the `./example/helm-values/envs/dev/dev-cluster/config.yaml` file and
+insert the context of an available cluster.
+
 Run commands such as:
 
 ```sh
@@ -46,21 +52,118 @@ Only do this if you really want to deploy:
 cargo run -- --vdir ./example/helm-values upgrade
 ```
 
-## Additional Options
+## Example config
+
+For demonstration purposes only.
+
+The folder structure of a config looks something like the following.
+
+```
+.
+└── envs
+    └── dev
+        ├── config.yaml
+        └── dev-cluster
+            ├── config.yaml
+            └── kube-prometheus-stack
+                ├── config.yaml
+                ├── lock.json
+                └── values.yaml
+```
+
+Has one environment, called `dev`, which has one cluster called `dev-cluster`.
+This cluster has one release called `kube-prometheus-stack`.
+
+Note the release name comes from the `config.yaml` file, not the directory
+name. But in this case they are the same. It is probably a good idea to keep
+them the same for sanity.
+
+## Usage
+
+### Filtering releases
+
+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`.
+
+Example:
+
+```sh
+cargo run -- --vdir ./example/helm-values --cluster=dev-cluster -env=dev --release-filter "release_name=kube-prometheus-stack" diff
+```
+
+### Lock files
 
-### Bypass Upgrade on No Changes
+helmci now supports lock.json files that contain details of the charts, such as
+sha256 hash. If the `lock.json` file is inconsistant then it will generate an
+error.
 
-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.
+To update all lock file entries:
 
-### Suboptions
+```sh
+cargo run -- --vdir ./example/helm-values rewrite-locks
+```
 
-#### Yes
+Note: this needs to be used with care in case the upstream repository has been
+tampered with.
 
-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.
+To update the version and automatically update the lock file entry at the same time:
 
-#### No
+```sh
+cargo run -- --output text  --vdir ./example/helm-values --release-filter "release_name=kube-prometheus-stack" update chart_version="35.5.1"
+```
 
-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.
+### OCI plugins
+
+If you have OCI plugins, you may need to enable authentication. Helmci can use
+the same authentication from docker, and helm uses this also.
+
+Example, to authenticate to AWS ECR repository:
+
+```sh
+ecr get-login-password --region=us-east-2 | helm registry login --username AWS --password-stdin XXXXXXXXXXXX.dkr.ecr.us-east-2.amazonaws.com
+```
+
+The helm config file is in a different location on OSX and Linux. On Linux use:
+
+```sh
+export DOCKER_CONFIG=~/.config/helm/registry
+```
+
+On OSX use:
+
+```sh
+export DOCKER_CONFIG=~/Library/Preferences/helm/registry
+```
+
+## Bypass Upgrade on No Changes
+
+The upgrade operation does a diff first. If there are no changes, then the
+upgrade will be skipped.
+
+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 `-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.
+
+If neither `--no` or `--yes` are supplied then `--no` is assumed.
 
 Example usage:
 
@@ -81,20 +184,21 @@ 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
+### 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
+### Cluster config
 
 For example `example/helm-values/envs/dev/dev-cluster/config.yaml`:
 
@@ -106,11 +210,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
+### 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
@@ -130,14 +237,21 @@ 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. This file is managed automatically.
 
-## Helm chart config
+### Helm chart config
 
 Example helm chart specification:
 
@@ -170,7 +284,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/)
@@ -179,11 +294,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