From f52fec66bd3eed1b52a99155d09361ac94cd410b Mon Sep 17 00:00:00 2001 From: Scott Rigby Date: Mon, 19 Apr 2021 18:29:16 -0400 Subject: [PATCH] Overriding helm values, managing secrets and configmaps with kustomize plus SOPS, semver range policies, and auto uninstalls and rollbacks Signed-off-by: Scott Rigby --- docs/use-cases/helm.md | 110 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) diff --git a/docs/use-cases/helm.md b/docs/use-cases/helm.md index 3d76ec05..efc0e938 100644 --- a/docs/use-cases/helm.md +++ b/docs/use-cases/helm.md @@ -91,6 +91,116 @@ Why is this important? If you or your team has ever collaborated with multiple engineers on one or more apps, and/or in more than one namespace or cluster, you probably have a good idea of how declarative, automatic reconciliation can help solve common problems. If not, or either way, you may want to check out this [short introduction to GitOps](https://youtu.be/r-upyR-cfDY). +## Customizing Your Release + +While Helm charts are usually installable using default configurations, users will often customize charts with their preferred configuration by [overriding the default values](https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing). +The Helm client allows this by imperatively specifying override values with `--set` on the command line, and in additional `--values` files. For example: + +```console +helm install my-traefik traefik/traefik --set service.type=ClusterIP +``` + +and + +```console +helm install my-traefik traefik/traefik --values ci/kind-values.yaml +``` + +where `ci/kind-values.yaml` contains: + +```yaml +service: + type: ClusterIP +``` + +Flux Helm Controller allows these same YAML values overrides on the `HelmRelease` CRD. +These can be declared directly in `spec.values`: + +```yaml +spec: + values: + service: + type: ClusterIP +``` + +and defined in `spec.valuesFrom` as a list of `ConfigMap` and `Secret` resources from which to draw values, allowing reusability and/or greater security. +See `HelmRelease` CRD [values overrides](https://toolkit.fluxcd.io/components/helm/helmreleases/#values-overrides) documentation for the latest spec. + +## Managing Secrets and ConfigMaps + +You may manage these `ConfigMap` and `Secret` resources any way you wish, but there are several benefits to managing these with the Flux Kustomize Controller. + +It is fairly straigtforward to use Kustomize `configMapGenerator` to [trigger a Helm release upgrade every time the encoded values change](https://toolkit.fluxcd.io/guides/helmreleases/#refer-to-values-in-configmaps-generated-with-kustomize). +This common use case currently solveable in Helm by [adding specially crafted annotations](https://helm.sh/docs/howto/charts_tips_and_tricks/#automatically-roll-deployments) to a chart. +The Flux Kustomize Controller method allows you to accomplish this on any chart without additional templated annotations. + +You may also use Kustomize Controller built-in [Mozilla SOPS integration](https://toolkit.fluxcd.io/components/kustomize/kustomization/#secrets-decryption) to securely manage your encrypted secrets stored in git. +See the [Flux SOPS guide](https://toolkit.fluxcd.io/guides/mozilla-sops/) for step-by-step instructions through various use cases. + +## Automatic Release Upgrades + +If you want Helm Controller to automatically upgrade your releases when a new chart version is available in the release's referenced `HelmRepository`, you may specify a SemVer range (i.e. `>=4.0.0 <5.0.0`) instead of a fixed version. + +This is useful if your release should use a fixed MAJOR chart version, but want the latest MINOR or PATCH versions as they become available. + +For full SemVer range syntax, see `Masterminds/semver` [Checking Version Constraints](https://github.com/Masterminds/semver/blob/master/README.md#checking-version-constraints) documentation. + +## Automatic Uninstalls and Rollback + +The Helm Controller offers an extensive set of configuration options to remediate when a Helm release fails, using [spec.install.remediate](https://toolkit.fluxcd.io/components/helm/api/#helm.toolkit.fluxcd.io/v2beta1.InstallRemediation), [spec.upgrade.remediate](https://toolkit.fluxcd.io/components/helm/api/#helm.toolkit.fluxcd.io/v2beta1.UpgradeRemediation), [spec.rollback](https://toolkit.fluxcd.io/components/helm/api/#helm.toolkit.fluxcd.io/v2beta1.Rollback) and [spec.uninstall](https://toolkit.fluxcd.io/components/helm/api/#helm.toolkit.fluxcd.io/v2beta1.Uninstall). +Features include the option to remediate with an uninstall after an upgrade failure, and the option to keep a failed release for debugging purposes when it has run out of retries. + +Here is an example for configuring automated uninstalls (for all available fields, consult the `InstallRemediation` and `Uninstall` API references linked above): + +```yaml +apiVersion: helm.toolkit.fluxcd.io/v2beta1 +kind: HelmRelease +metadata: + name: my-release + namespace: default +spec: + # ...omitted for brevity + install: + # Remediation configuration for when the Helm install + # (or sequent Helm test) action fails + remediation: + # Number of retries that should be attempted on failures before + # bailing, a negative integer equals to unlimited retries + retries: -1 + # Configuration options for the Helm uninstall action + uninstall: + timeout: 5m + disableHooks: false + keepHistory: false +``` + +Here is an example of automated rollback configuration (for all available fields, consult the `UpgradeRemediation` and `Rollback` API references linked above): + +```yaml +apiVersion: helm.toolkit.fluxcd.io/v2beta1 +kind: HelmRelease +metadata: + name: my-release + namespace: default +spec: + # ...omitted for brevity + upgrade: + # Remediaton configuration for when an Helm upgrade action fails + remediation: + # Amount of retries to attempt after a failure, + # setting this to 0 means no remedation will be + # attempted + retries: 5 + # Configuration options for the Helm rollback action + rollback: + timeout: 5m + disableWait: false + disableHooks: false + recreate: false + force: false + cleanupOnFail: false +``` + ## Next Steps - [Guides > Manage Helm Releases](/guides/helmreleases/)