Skip to content

🧬 helmwave.yml¢

This documentation describes all entities inside a helmwave.yml

field required type default
project πŸ™… string ""
version πŸ™… string ""
repositories πŸ™… array []
registries πŸ™… array []
lifecycle πŸ™… object {}
releases πŸ™… array []
project: "HelloWorld"
version: "0.32.1"
repositories: []
registries: []
releases: []
lifecycle:
  pre_up: []
  post_up: []
  pre_down: []
  post_down: []
  pre_build: []
  post_build: []
  pre_rollback: []
  post_rollback: []
project: "HelloWorld"
version: "0.32.1"

repositories:
    - name: stable
      url: https://localhost:8080
      # private repositories
      username: user
      password: 12345679

      # cert
      certFile: ./cert.pem
      keyFile: ./key.pem
      caFile: ./ca.pem

lifecycle:
    pre_build:
      - cmd: "ls"
        args: ["-l", "-a"]
        show: false
        allow_failure: false
      - echo "run global pre_build script"
    post_build:
      - echo "run global post_build script"

registries:
    - host: https://localhost:5000
      # private registries
      username: oci_user
      password: 98765431
      insecure: false


releases:
    - name: my
      namespace: prod
      chart:
        name: stable/my-chart
        version: "0.2.0"
        ca_file: ""
        cert_file: ""
        key_file: ""
        insecure: false
        keyring: ""
        password: ""
        pass_credentials: false
        repo_url: ""
        username: ""
        verify: false

      store:
        greeting: "HelloWorld"

      lifecycle:
        pre_up:
          - echo "running pre_up script for my"
        post_up:
          - echo "running post_up script for my"
        pre_build:
          - echo "running pre_build script for my"
        post_build:
          - echo "running post_build script for my"

      depends_on:
        - name: db@prod
          tag: prod
          optional: false

      values:
        - src: values.yml
          delimiter_left: "[["
          delimiter_right: "]]"
          render: false
          strict: true

      tags:
        - my
        - product

      post_renderer: "./gomplate"
      offline_kube_version: "1.22.0"
      timeout: "5m"
      max_history: 3
      context: prod
      description: "my chart"
      pending_release_strategy: rollback
      allow_failure: false
      atomic: true
      cleanup_on_fail: false
      create_namespace: false
      disable_hooks: false
      disable_openapi_validation: false
      force: false
      enable_dns: false
      recreate: false
      reset_values: false
      reuse_values: false
      skip_crds: false
      sub_notes: false
      wait: true
      wait_for_jobs: true

projectΒΆ

Reserved for the future.

versionΒΆ

Helmwave will check the current version and project version.

In the future, it is planned to check major compatibility.

registries[]ΒΆ

Introduced in v0.19.0

Describe which OCI registries need to be added.

field required type default
host βœ… string ""
username πŸ™… string ""
password πŸ™… string ""
insecure πŸ™… bool false
project: "Example: oci private"
version: "0.32.1"

registries:
  - host: localhost:5000
    username: <pass_username_here>
    password: <pass_password_here>

releases:
  - name: my
    chart:
      name: oci://localhost:5000/my-chart
      version: 0.2.0 # best practice
project: "Example: oci public"
version: "0.32.1"

registries:
  - host: ghcr.io

releases:
  - name: my
    chart:
      name: oci://ghcr.io/helmwave/unit-test-oci
      version: 0.1.0 # best practice

hostΒΆ

Host of the registry.

usernameΒΆ

Username for the registry.

only if registry is private

passwordΒΆ

Password for the registry.

only if registry is private

repositories[]ΒΆ

helm repositories also know as helm repo add

field required type default
name βœ… string ""
url βœ… url ""
username πŸ™… string ""
password πŸ™… string ""
force πŸ™… bool false
certFile πŸ™… string ""
keyFile πŸ™… string ""
caFile πŸ™… string ""
insecure_skip_tls_verify πŸ™… bool false
pass_credentials_all πŸ™… bool false

This repository will be stored in a local helm repositories database.

nameΒΆ

Local name alias.

urlΒΆ

URL of the repository.

usernameΒΆ

Username for the repository.

passwordΒΆ

Password for the repository.

forceΒΆ

Update existing repository exists if settings differ.

lifecycleΒΆ

Aka global hooks. Introduced in v0.28.0

We don't call lifecycle the hooks on purpose so as not to confuse you with the original functionality of helm hooks.

field required type default
pre_up πŸ™… []Hook []
post_up πŸ™… []Hook []
pre_down πŸ™… []Hook []
post_down πŸ™… []Hook []
pre_build πŸ™… []Hook []
post_build πŸ™… []Hook []
pre_rollback πŸ™… []Hook []
post_rollback πŸ™… []Hook []
flowchart LR pre_build --> post_build post_build --> pre_up --> post_up post_build --> pre_down --> post_down post_build --> pre_rollback --> post_rollback

environment

Introduced in v0.29.0

To each lifecycle command several environment variables are passed:

  • ${HELMWAVE_LIFECYCLE_TYPE} - contains lifecycle stage/type (pre_build/post_build/etc.)
  • ${HELMWAVE_LIFECYCLE_RELEASE_UNIQNAME} - (only for per-release lifecycle) contains release uniqname (release@namespace)

** Hook **

field required type default
cmd βœ… string ""
args πŸ™… array []
show πŸ™… bool true
allow_failure πŸ™… bool false

example

cmd, argsΒΆ

version: 0.32.1
lifecycle:
  pre_build:
    - echo "run global pre_build script"
version: 0.32.1
lifecycle:
  pre_build:
    - cmd: echo 
      args:
        - "run global pre_build script"
      show: true
      allow_failure: false

showΒΆ

Introduced in v0.28.0

Show output of the command.

allow_failureΒΆ

Introduced in v0.29.0

Allow failure of the command.

monitors[]ΒΆ

Introduced in v0.32.0

Monitors run after all dependant releases succeeded. They are triggered every interval and end when:

  • Either success_threshold is met - monitor succeeds
  • Either failure_threshold is met - monitor fails
  • Or total_timeout is triggered - monitor fails
field required type default
name βœ… string ""
type βœ… string ""
total_timeout πŸ™… interval 5m
iteration_timeout πŸ™… interval 10s
interval πŸ™… interval 1m
success_threshold πŸ™… int 3
failure_threshold πŸ™… int 3
prometheus πŸ™… object {}
http πŸ™… object {}

example

nameΒΆ

Monitor name, must be unique.

typeΒΆ

Type of monitor to run. Must be one of:

  • prometheus
  • http

total_timeoutΒΆ

Total timeout for whole monitor run. If monitor haven't finished within total_timeout, it is considered as failed.

iteration_timoutΒΆ

Timeout for each monitor iteration. If monitor iteration haven't finished within iteration_timeout, iteration is considered as failed.

intervalΒΆ

Interval between iterations. Must be lower than iteration_timeout.

success_thresholdΒΆ

Count of sequential succeeded iterations that make monitor succeed.

failure_thresholdΒΆ

Count of sequential failed iterations that make monitor fail.

prometheusΒΆ

field required type default
url βœ… string ""
expr βœ… string ""
insecure πŸ™… bool false

urlΒΆ

Prometheus base URL

exprΒΆ

Prometheus expression to query on each iteration. Iteration is considered successful if expression returns 1 or more rows.

insecureΒΆ

Whether to skip SSL certificate validation

httpΒΆ

field required type default
url βœ… string ""
expected_codes βœ… []int []
method πŸ™… string "HEAD"
body πŸ™… string ""
headers πŸ™… object {}
insecure πŸ™… bool false

urlΒΆ

URL to query

expected_codesΒΆ

List of expected HTTP response codes that are considered to be successful

methodΒΆ

HTTP method to query

bodyΒΆ

HTTP body to send

headersΒΆ

Map of HTTP headers to set in request

insecureΒΆ

Whether to skip SSL certificate validation

releases[]ΒΆ

Almost all options that are here are native helm options.

field required type default helmwave build helm option
name βœ… string "" βœ…
namespace βœ… string "" βœ…
chart βœ… string or object {} βœ…
create_namespace πŸ™… bool false
values πŸ™… array [] βœ…
tags πŸ™… array [] βœ…
offline_kube_version πŸ™… string "" βœ…
store πŸ™… object {} βœ…
lifecycle πŸ™… object {} βœ…
depends_on πŸ™… array [] βœ…
monitors πŸ™… array [] βœ…
allow_failure πŸ™… bool false
pending_release_strategy πŸ™… string ""
wait πŸ™… bool false
wait_for_jobs πŸ™… bool false
timeout πŸ™… interval 5m
max_history πŸ™… int 0
context πŸ™… string ""
description πŸ™… string ""
atomic πŸ™… bool false
cleanup_on_fail πŸ™… bool false
disable_hooks πŸ™… bool false
disable_open_api_validation πŸ™… bool false
force πŸ™… bool false
enable_dns πŸ™… bool false
recreate πŸ™… bool false
reset_values πŸ™… bool false
reuse_values πŸ™… bool false
skip_crds πŸ™… bool false
sub_notes πŸ™… bool false
post_renderer πŸ™… array [] βœ…

nameΒΆ

Introduced in v0.5.0

Release name. I hope you know what it is.

namespaceΒΆ

Introduced in v0.5.0

kubernetes namespace.

chartΒΆ

Introduced in v0.5.0

field required type default
name βœ… string ""
version πŸ™… string ""
username πŸ™… string ""
password πŸ™… string ""
ca_file πŸ™… string ""
cert_file πŸ™… string ""
key_file πŸ™… string ""
repo_url πŸ™… string ""
insecure πŸ™… bool false
keyring πŸ™… string ""
pass_credentials πŸ™… bool false
verify πŸ™… bool false
skip_dependency_update πŸ™… bool false
skip_refresh πŸ™… bool false

chart can be an object or a string. If it's a string, it will be treated as a name.

Introduced in v0.20.0

releases:
  - name: my-release
    namespace: my-namespace
    chart: my-chart
releases:
  - name: my-release
    namespace: my-namespace
    chart:
      name: my-chart

!!! tip "If chart is remote it will be downloaded into .helmwave/charts and downloaded archive will be used during deploy."

nameΒΆ

Can be oci://, local or repository chart.

releases:
  - name: my-release
    namespace: my-namespace
    chart: oci://my-registry.io/my-chart
releases:
  - name: my-release
    namespace: my-namespace
    chart: ./my-chart
releases:
  - name: my-release
    namespace: my-namespace
    chart: bitnami/nats

versionΒΆ

Chart version. If not set, latest will be used.

releases:
  - name: my-release
    namespace: my-namespace
    chart:
      name: my-chart
      version: 1.2.3

skip_dependency_updateΒΆ

Introduced in v0.29.1

Disable Helm dependency update.

skip_refreshΒΆ

Introduced in v0.29.1

Disable Helm repository refresh.

create_namespaceΒΆ

Introduced in v0.12.0

If set to true Helmwave will create the release namespace if not present.

helm upgrade --install --create-namespace my-release my-chart --namespace my-namespace
releases:
  - name: my-release
    namespace: my-namespace
    chart: my-chart
    create_namespace: true

values[]ΒΆ

Introduced in v0.5.0

values can be an object or a string. If it's a string, it will be treated as a src field.

field required type default
src βœ… string ""
delimiter_left πŸ™… string "{{"
delimiter_right πŸ™… string "}}"
strict πŸ™… bool false
renderer πŸ™… string ""
values:
  - values.yaml
  - values2.yaml
values:
  - src: values.yaml
    delimiter_left: "{{"
    delimiter_right: "}}"
    strict: false
    renderer: ""

srcΒΆ

Path to values file. It can be local or remote.

delimiter_left, delimiter_rightΒΆ

Introduced in v0.24.0

You can change the delimiter that helmwave uses to render values.

example

rendererΒΆ

Introduced in v0.32.0

Allows overriding how values file is rendered. These renderers are supported:

  • sprig - template file with sprig (overrides global --templater argument)
  • gomplate - template file with gomplate (overrides global --templater argument)
  • copy - do not template file at all (overrides global --templater argument)
  • sops - use sops to decode encrypted file

  • example

  • example

strictΒΆ

Introduced in v0.20.0

Allows to fail if values file doesn't exist.

example

tags[]ΒΆ

Aka labels. Introduced in v0.4.0

Tags allow you to choose releases for build.

example

offline_kube_versionΒΆ

Introduced in v0.27.3

If offline_kube_version set helmwave will use this version to build plan. Without this option, helmwave will ask kubernetes for a version. It is very useful if you want to build a plan without access to a cluster.

Combine offline_kube_version and --diff-mode=local or --diff-mode=none to build a plan without kubernetes.

example

storeΒΆ

Introduced in v0.2.0

It allows passing your custom fields from helmwave.yml to values.

example

lifecycleΒΆ

Aka hooks. Introduced in v0.28.0

example

depends_on[]ΒΆ

Introduced in v0.9.0

depends_on can be an object or a string. If it's a string, it will be treated as a name.

field required type default
name πŸ™… string ""
tag πŸ™… string ""
optional πŸ™… bool false

depends_on is a list of releases that allow you to deploy a sequence.

!!! example "Example for 3-tier application"

```mermaid
graph LR
    frontend --> backend --> db;
```
*If you don't see a graph, please reload the page.*

Your helmwave.yml should look like this:

releases:
  - name: frontend
    depends_on:
      - backend
    namespace: test

  - name: backend
    depends_on:
      - db
    namespace: test

  - name: db
    allow_failure: false
    namespace: test

nameΒΆ

Name of release (dependency) that has to be installed/upgraded before this release (dependant). If dependency is not in a plan, it will be added to a plan.

Name support 2 kind of definitions: uniq name <release-name>@<namespace> or just <release-name>. If namespace is not specified, it will be taken from namespace filed of release.

The same configuration can be written in 2 ways:

Introduced in v0.21.1

releases:
  - name: backend
    namespace: test
    depends_on:
      - name: redis

- name: redis
  namespace: test
releases:
  - name: backend
    namespace: test
    depends_on:
      - name: redis@test

- name: redis
  namespace: test

Both of them will be normalized to redis@test in a planfile.

tagΒΆ

Introduced in v0.24.0

You can include all releases that match this tag to be added as dependencies. If a tag is not in a plan, it will be added to a plan.

The planfile (.helmwave/planfile by default) will have a normalized list of releases instead of tags.

optionalΒΆ

Introduced in v0.24.0

If dependency is not found in all available releases, helmwave will not fail due to missing dependency.

It allows setting explicit dependencies between releases. Dependant release will start upgrading only after all its dependencies finished upgrading

monitors[]ΒΆ

Introduced in v0.32.0

Which monitors should be triggered after the releases is successfully deployed.

field required type default
name βœ… string ""
action πŸ™… string ""

example

nameΒΆ

Name of the monitor to trigger

actionΒΆ

Action to perform if the monitor is failed. Should be one of:

  • "" - do nothing
  • rollback - rollback release to the previous version
  • uninstall - uninstall release

If multiple monitors of the release failed and they have different actions, chosen action is a random one from the list.

allow_failureΒΆ

Introduced in v0.15.0

Allows all dependant releases to proceed even if release failed.

pending_release_strategyΒΆ

Introduced in v0.21.0

Strategy to handle releases in pending statuses (pending-install, pending-upgrade, pending-rollback)

If helmwave tries to upgrade release that is currently in one of the pending statuses, it will follow specified strategy:

  • "" (or not specified) - do nothing. helm will fail in this case;
  • rollback - rollback release to a previous version. Upgrade will happen after rollback is complete;
  • uninstall - uninstall release. Upgrade will happen after uninstall is complete.

waitΒΆ

We recommend using wait for all releases. It will wait for all resources to be ready.

wait_for_jobsΒΆ

Introduced in v0.12.0

We recommend using wait_for_jobs for all releases. It will wait for all jobs to be completed.

timeoutΒΆ

Introduced in v0.5.0

Time to wait for release to install.

if you enable kubedog this option will be required.

max_historyΒΆ

Introduced in v0.5.0

Limit the maximum number of revisions saved per release. Use 0 for no limit (default 0)

Recommendation is using 3 for this option.

previous release + current release + next release = 3

contextΒΆ

Introduced in v0.24.0

Allows using custom kube-context for release.

Kubedog can't be enabled when there are releases in multiple contexts.

descriptionΒΆ

Introduced in v0.12.0

Additional information about release.

atomicΒΆ

Introduced in v0.5.0

if set, upgrade process rolls back changes made in case of failed upgrade.

cleanup_on_failΒΆ

Introduced in v0.12.0

Allow deletion of new resources created in this upgrade when upgrade fails.

develΒΆ

Removed in v0.29.3 as it wasn't functioning properly.

If you need to use development version, set version: ">0.0.0-0".

disable_hooksΒΆ

Introduced in v0.12.0

Disable pre/post upgrade helm hooks

disable_open_api_validationΒΆ

Introduced in v0.12.0

If set, the upgrade process will not validate rendered templates against the Kubernetes OpenAPI Schema

forceΒΆ

Introduced in v0.5.0

Force resource updates through a replacement strategy

We don't recommend using this option.

enable_dnsΒΆ

Introduced in v0.27.1

Enable DNS resolution in templates.

recreateΒΆ

Introduced in v0.5.0

Allows deleting and then creating resources (pods) when needed instead of updating.

We don't recommend using this option.

reset_valuesΒΆ

Introduced in v0.5.0

When upgrading, reset the values to the ones built into the chart.

reuse_valuesΒΆ

Introduced in v0.5.0

When upgrading, reuse the last release's values and merge it into the new configuration.

We don't recommend using this option.

skip_crdsΒΆ

Introduced in v0.12.0

If set, no CRDs will be installed. By default, CRDs are installed if not already present.

Be careful with this option.

  • If you have a release that depends on CRDs, it will fail.
  • Sometimes you should enable installCRD: true in your chart like cert-manager.

sub_notesΒΆ

Introduced in v0.12.0

If set, render sub chart notes along with the parent. This option determines whether sub-notes are rendered in the chart.

post_rendererΒΆ

Introduced in v0.24.0

You can use custom commands to change rendered manifests.

show_notesΒΆ

Introduced in v0.31.0

If enabled, rendered chart notes will be shown after successful release.