Helmfile

Deploy Kubernetes Helm Charts

Status

Even though Helmfile is used in production environments across multiple organizations, it is still in its early stage of development, hence versioned 0.x.

Helmfile complies to Semantic Versioning 2.0.0 in which v0.x means that there could be backward-incompatible changes for every release.

Note that we will try our best to document any backward incompatibility. And in reality, helmfile had no breaking change for a year or so.

About

Helmfile is a declarative spec for deploying helm charts. It lets you...

• Keep a directory of chart value files and maintain changes in version control.
• Apply CI/CD to configuration changes.
• Periodically sync to avoid skew in environments.

To avoid upgrades for each iteration of helm, the helmfile executable delegates to helm - as a result, helm must be installed.

Highlights

Declarative: Write, version-control, apply the desired state file for visibility and reproducibility.

Modules: Modularize common patterns of your infrastructure, distribute it via Git, S3, etc. to be reused across the entire company (See #648)

Versatility: Manage your cluster consisting of charts, kustomizations, and directories of Kubernetes resources, turning everything to Helm releases (See #673)

Patch: JSON/Strategic-Merge Patch Kubernetes resources before helm-installing, without forking upstream charts (See #673)

Configuration

CAUTION: This documentation is for the development version of Helmfile. If you are looking for the documentation for any of releases, please switch to the corresponding release tag like v0.92.1.

The default name for a helmfile is helmfile.yaml:

```yaml

Chart repositories used from within this state file

Use helm-s3 and helm-git and whatever Helm Downloader plugins

to use repositories other than the official repository or one backend by chartmuseum.

repositories:

To use official "stable" charts a.k.a https://github.com/helm/charts/tree/master/stable

• name: stable url: https://charts.helm.sh/stable

To use official "incubator" charts a.k.a https://github.com/helm/charts/tree/master/incubator

• name: incubator url: https://charts.helm.sh/incubator

helm-git powered repository: You can treat any Git repository as a charts repository

• name: polaris url: git+https://github.com/reactiveops/polaris@deploy/helm?ref=master

Advanced configuration: You can setup basic or tls auth and optionally enable helm OCI integration

• name: roboll url: http://roboll.io/charts certFile: optional_client_cert keyFile: optional_client_key username: optional_username password: optional_password oci: true passCredentials: true

Advanced configuration: You can use a ca bundle to use an https repo

with a self-signed certificate

• name: insecure url: https://charts.my-insecure-domain.com caFile: optional_ca_crt

Advanced configuration: You can skip the verification of TLS for an https repo

• name: skipTLS url: https://ss.my-insecure-domain.com skipTLSVerify: true

context: kube-context # this directive is deprecated, please consider using helmDefaults.kubeContext

Path to alternative helm binary (--helm-binary)

helmBinary: path/to/helm3

Default values to set for args along with dedicated keys that can be set by contributors, cli args take precedence over these.

In other words, unset values results in no flags passed to helm.

See the helm usage (helm SUBCOMMAND -h) for more info on default values when those flags aren't provided.

helmDefaults: tillerNamespace: tiller-namespace #dedicated default key for tiller-namespace tillerless: false #dedicated default key for tillerless kubeContext: kube-context #dedicated default key for kube-context (--kube-context) cleanupOnFail: false #dedicated default key for helm flag --cleanup-on-fail # additional and global args passed to helm (default "") args: - "--set k=v" # verify the chart before upgrading (only works with packaged charts not directories) (default false) verify: true # wait for k8s resources via --wait. (default false) wait: true # if set and --wait enabled, will wait until all Jobs have been completed before marking the release as successful. It will wait for as long as --timeout (default false, Implemented in Helm3.5) waitForJobs: true # time in seconds to wait for any individual Kubernetes operation (like Jobs for hooks, and waits on pod/pvc/svc/deployment readiness) (default 300) timeout: 600 # performs pods restart for the resource if applicable (default false) recreatePods: true # forces resource update through delete/recreate if needed (default false) force: false # enable TLS for request to Tiller (default false) tls: true # path to TLS CA certificate file (default "$HELM_HOME/ca.pem") tlsCACert: "path/to/ca.pem" # path to TLS certificate file (default "$HELM_HOME/cert.pem") tlsCert: "path/to/cert.pem" # path to TLS key file (default "$HELM_HOME/key.pem") tlsKey: "path/to/key.pem" # limit the maximum number of revisions saved per release. Use 0 for no limit. (default 10) historyMax: 10 # when using helm 3.2+, automatically create release namespaces if they do not exist (default true) createNamespace: true # if used with charts museum allows to pull unstable charts for deployment, for example: if 1.2.3 and 1.2.4-dev versions exist and set to true, 1.2.4-dev will be pulled (default false) devel: true # When set to true, skips running helm dep up and helm dep build on this release's chart. # Useful when the chart is broken, like seen in https://github.com/roboll/helmfile/issues/1547 skipDeps: false

these labels will be applied to all releases in a Helmfile. Useful in templating if you have a helmfile per environment or customer and don't want to copy the same label to each release

commonLabels: hello: world

The desired states of Helm releases.

Helmfile runs various helm commands to converge the current state in the live cluster to the desired state defined here.

releases: # Published chart example - name: vault # name of this release namespace: vault # target namespace createNamespace: true # helm 3.2+ automatically create release namespace (default true) labels: # Arbitrary key value pairs for filtering releases foo: bar chart: roboll/vault-secret-manager # the chart being installed to create this release, referenced by repository/chart syntax version: ~1.24.1 # the semver of the chart. range constraint is supported condition: vault.enabled # The values lookup key for filtering releases. Corresponds to the boolean value of vault.enabled, where vault is an arbitrary value missingFileHandler: Warn # set to either "Error" or "Warn". "Error" instructs helmfile to fail when unable to find a values or secrets file. When "Warn", it prints the file and continues. # Values files used for rendering the chart values: # Value files passed via --values - vault.yaml # Inline values, passed via a temporary values file and --values, so that it doesn't suffer from type issues like --set - address: https://vault.example.com # Go template available in inline values and values files. - image: # The end result is more or less YAML. So do quote to prevent number-like strings from accidentally parsed into numbers! # See https://github.com/roboll/helmfile/issues/608 tag: {{ requiredEnv "IMAGE_TAG" | quote }} # Otherwise: # tag: "{{ requiredEnv "IMAGE_TAG" }}" # tag: !!string {{ requiredEnv "IMAGE_TAG" }} db: username: {{ requiredEnv "DB_USERNAME" }} # value taken from environment variable. Quotes are necessary. Will throw an error if the environment variable is not set. $DB_PASSWORD needs to be set in the calling environment ex: export DB_PASSWORD='password1' password: {{ requiredEnv "DB_PASSWORD" }} proxy: # Interpolate environment variable with a fixed string domain: {{ requiredEnv "PLATFORM_ID" }}.my-domain.com scheme: {{ env "SCHEME" | default "https" }} # Use values whenever possible! # set translates to helm's --set key=val, that is known to suffer from type issues like https://github.com/roboll/helmfile/issues/608 set: # single value loaded from a local file, translates to --set-file foo.config=path/to/file - name: foo.config file: path/to/file # set a single array value in an array, translates to --set bar[0]={1,2} - name: bar[0] values: - 1 - 2 # set a templated value - name: namespace value: {{ .Namespace }} # will attempt to decrypt it using helm-secrets plugin secrets: - vault_secret.yaml # Override helmDefaults options for verify, wait, waitForJobs, timeout, recreatePods and force. verify: true wait: true waitForJobs: true timeout: 60 recreatePods: true force: false # set false to uninstall this release on sync. (default true) installed: true # restores previous state in case of failed release (default false) atomic: true # when true, cleans up any new resources created during a failed release (default false) cleanupOnFail: false # name of the tiller namespace (default "") tillerNamespace: vault # if true, will use the helm-tiller plugin (default false) tillerless: false # enable TLS for request to Tiller (default false) tls: true # path to TLS CA certificate file (default "$HELM_HOME/ca.pem") tlsCACert: "path/to/ca.pem" # path to TLS certificate file (default "$HELM_HOME/cert.pem") tlsCert: "path/to/cert.pem" # path to TLS key file (default "$HELM_HOME/key.pem") tlsKey: "path/to/key.pem" # --kube-context to be passed to helm commands # CAUTION: this doesn't work as expected for tilerless: true. # See https://github.com/roboll/helmfile/issues/642 # (default "", which means the standard kubeconfig, either ~/kubeconfig or the file pointed by $KUBECONFIG environment variable) kubeContext: kube-context # passes --disable-validation to helm 3 diff plugin, this requires diff plugin >= 3.1.2 # It may be helpful to deploy charts with helm api v1 CRDS # https://github.com/roboll/helmfile/pull/1373 disableValidation: false # passes --disable-validation to helm 3 diff plugin, this requires diff plugin >= 3.1.2 # It is useful when any release contains custom resources for CRDs that is not yet installed onto the cluster. # https://github.com/roboll/helmfile/pull/1618 disableValidationOnInstall: false # passes --disable-openapi-validation to helm 3 diff plugin, this requires diff plugin >= 3.1.2 # It may be helpful to deploy charts with helm api v1 CRDS # https://github.com/roboll/helmfile/pull/1373 disableOpenAPIValidation: false # limit the maximum number of revisions saved per release. Use 0 for no limit (default 10) historyMax: 10 # When set to true, skips running helm dep up and helm dep build on this release's chart. # Useful when the chart is broken, like seen in https://github.com/roboll/helmfile/issues/1547 skipDeps: false

# Local chart example - name: grafana # name of this release namespace: another # target namespace chart: ../my-charts/grafana # the chart being installed to create this release, referenced by relative path to local helmfile values: - "../../my-values/grafana/values.yaml" # Values file (relative path to manifest) - ./values/{{ requiredEnv "PLATFORM_ENV" }}/config.yaml # Values file taken from path with environment variable. $PLATFORM_ENV must be set in the calling environment. wait: true

Advanced Configuration: Nested States

helmfiles: - # Path to the helmfile state file being processed BEFORE releases in this state file path: path/to/subhelmfile.yaml # Label selector used for filtering releases in the nested state. # For example, name=prometheus in this context is equivalent to processing the nested state like # helmfile -f path/to/subhelmfile.yaml -l name=prometheus sync selectors: - name=prometheus # Override state values values: # Values files merged into the nested state's values - additional.values.yaml # One important aspect of using values here is that they first need to be defined in the values section # of the origin helmfile, so in this example key1 needs to be in the values or environments.NAME.values of path/to/subhelmfile.yaml # Inline state values merged into the nested state's values - key1: val1 - # All the nested state files under helmfiles: is processed in the order of definition. # So it can be used for preparation for your main releases. An example would be creating CRDs required by releases in the parent state file. path: path/to/mycrd.helmfile.yaml - # Terraform-module-like URL for importing a remote directory and use a file in it as a nested-state file