diff --git a/docs/use-cases/helm.md b/docs/use-cases/helm.md new file mode 100644 index 00000000..efc0e938 --- /dev/null +++ b/docs/use-cases/helm.md @@ -0,0 +1,208 @@ +# Flux for Helm Users + +Welcome Helm users! +We think Flux's Helm Controller is the best way to do Helm according to GitOps principles, and we're dedicated to doing what we can to help you feel the same way. + +## What Does Flux add to Helm? + +Helm 3 was designed with both a client and an SDK, but no running software agents. +This architecture intended anything outside of the client scope to be addressed by other tools in the ecosystem, which could then make use of Helm's SDK. + +Built on Kubernetes controller-runtime, Flux's Helm Controller is an example of a mature software agent that uses Helm's SDK to full effect. + + +Flux's biggest addition to Helm is a structured declaration layer for your releases that automatically gets reconciled to your cluster based on your configured rules: + +- While the Helm client commands let you imperatively do things +- Flux Helm Custom Resources let you declare what you want the Helm SDK to do automatically + +Additional benefits Flux adds to Helm include: + +- Managing / structuring multiple environments +- A control loop, with configurable retry logic +- Automated drift detection between the desired and actual state of your operations +- Automated responses to that drift, including reconciliation, notifications, and unified logging + +## Getting Started + +The simplest way to explain is by example. +Lets translate imperative Helm commands to Flux Helm Controller Custom Resources: + +Helm client: + +```console +helm repo add traefik https://helm.traefik.io/traefik +helm install my-traefik traefik/traefik \ + --version 9.18.2 \ + --namespace traefik +``` + +Flux client: + +```console +flux create source helm traefik --url https://helm.traefik.io/traefik +flux create helmrelease --chart my-traefik \ + --source HelmRepository/traefik \ + --chart-version 9.18.2 \ + --namespace traefik +``` + +The main difference is Flux client will not imperatively create resources in the cluster. +Instead these commands create Custom Resource *files*, which are committed to version control as instructions only (note: you may use the `--export` flag to manage any file edits with finer grained control before pushing to version control). +Separately, the Flux Helm Controller software agent automatically reconciles these instructions with the running state of your cluster based on your configured rules. + +Lets check out what the Custom Resoruce instruction files look like: + +```yaml +# /flux/boot/traefik/helmrepo.yaml +apiVersion: source.toolkit.fluxcd.io/v1beta1 +kind: HelmRepository +metadata: + name: traefik + namespace: traefik +spec: + interval: 1m0s + url: https://helm.traefik.io/traefik +``` + +```yaml +# /flux/boot/traefik/helmrelease.yaml +apiVersion: helm.toolkit.fluxcd.io/v2beta1 +kind: HelmRelease +metadata: + name: traefik + namespace: traefik +spec: + chart: + spec: + chart: traefik + sourceRef: + kind: HelmRepository + name: traefik + version: 9.18.2 + interval: 1m0s +``` + + + +Once these are applied to your cluster, the Flux Helm Controller automatically uses the Helm SDK to do your bidding according to the rules you've set. + +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/) +- [Toolkit Components > Helm Controller](/components/helm/controller/) +- [Migration > Migrate to the Helm Controller](/guides/helm-operator-migration/) diff --git a/mkdocs.yml b/mkdocs.yml index ac7a942d..63168558 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -66,6 +66,7 @@ nav: - Sortable image tags to use with automation: guides/sortable-image-tags.md - Use Cases: - Azure: use-cases/azure.md + - Helm: use-cases/helm.md - Toolkit Components: - Overview: components/index.md - Source Controller: