🧬 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	[]

Short helmwave.ymlFull helmwave.yml

project: "HelloWorld"
version: "0.28.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.28.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
      - 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"
        cafile: ""
        certfile: ""
        keyfile: ""
        insecureskiptlsverify: false
        keyring: ""
        password: ""
        passcredentialsall: false
        repourl: ""
        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
      devel: 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

private oci public oci

project: "Example: oci private"
version: "0.28.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.28.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	🙅	array	[]
post_up	🙅	array	[]
pre_down	🙅	array	[]
post_down	🙅	array	[]
pre_build	🙅	array	[]
post_build	🙅	array	[]
pre_rollback	🙅	array	[]
post_rollback	🙅	array	[]

short syntaxfull syntax

version: 0.28.1
lifecycle:
  pre_build:
    - echo "run global pre_build script"

version: 0.28.1
lifecycle:
  pre_build:
    - cmd: echo 
      args: ['"run', 'global', 'pre_build', 'script"']
      show: true

flowchart LR pre_build --> post_build post_build --> pre_up --> post_up post_build --> pre_down --> post_down post_build --> pre_rollback --> post_rollback

example

releases[]¶

Almost all options that are here are native helm options.

field	required	type	default	`helmwave build`
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	[]	✅
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
devel	🙅	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	""
insecure	🙅	bool	false
keyring	🙅	string	""
pass_credentials	🙅	bool	false
verify	🙅	bool	false

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

short syntaxlong syntax

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

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

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
render	🙅	bool	true

short syntaxfull syntax

values:
  - values.yaml
  - values2.yaml

values:
  - src: values.yaml
    delimiter_left: "{{"
    delimiter_right: "}}"
    strict: false
    render: true

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

render¶

Introduced in v0.20.0

Allows disabling templating values at all.

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 for 3-tier application

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:

<release-name><release-name>@<namespace>

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

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¶

Introduced in v0.12.0

Use development versions, too. Equivalent to 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.