community.kubernetes.helm – Manages Kubernetes packages with the Helm package manager

Note

This plugin is part of the community.kubernetes collection (version 1.2.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.kubernetes.

To use it in a playbook, specify: community.kubernetes.helm.

New in version 0.11.0: of community.kubernetes

Synopsis

  • Install, upgrade, delete packages with the Helm package manager.

Note

This module has a corresponding action plugin.

Requirements

The below requirements are needed on the host that executes this module.

Parameters

Parameter

Comments

api_key

string

added in 1.2.0 of community.kubernetes

Token used to authenticate with the API. Can also be specified via K8S_AUTH_API_KEY environment variable.

atomic

boolean

If set, the installation process deletes the installation on failure.

Choices:

  • no ← (default)

  • yes

binary_path

path

The path of a helm binary to use.

ca_cert

aliases: ssl_ca_cert

path

added in 1.2.0 of community.kubernetes

Path to a CA certificate used to authenticate with the API. The full certificate chain must be provided to avoid certificate validation errors. Can also be specified via K8S_AUTH_SSL_CA_CERT environment variable.

chart_ref

path

chart_reference on chart repository.

path to a packaged chart.

path to an unpacked chart directory.

absolute URL.

Required when release_state is set to present.

chart_repo_url

string

Chart repository URL where to locate the requested chart.

chart_version

string

Chart version to install. If this is not specified, the latest version is installed.

context

aliases: kube_context

string

Helm option to specify which kubeconfig context to use.

If the value is not specified in the task, the value of environment variable K8S_AUTH_CONTEXT will be used instead.

create_namespace

boolean

added in 0.11.1 of community.kubernetes

Create the release namespace if not present.

Choices:

  • no ← (default)

  • yes

disable_hook

boolean

Helm option to disable hook on install/upgrade/delete.

Choices:

  • no ← (default)

  • yes

force

boolean

Helm option to force reinstall, ignore on new install.

Choices:

  • no ← (default)

  • yes

host

string

added in 1.2.0 of community.kubernetes

Provide a URL for accessing the API. Can also be specified via K8S_AUTH_HOST environment variable.

kubeconfig

aliases: kubeconfig_path

path

Helm option to specify kubeconfig path to use.

If the value is not specified in the task, the value of environment variable K8S_AUTH_KUBECONFIG will be used instead.

purge

boolean

Remove the release from the store and make its name free for later use.

Choices:

  • no

  • yes ← (default)

release_name

aliases: name

string / required

Release name to manage.

release_namespace

aliases: namespace

string / required

Kubernetes namespace where the chart should be installed.

release_state

aliases: state

string

Desirated state of release.

Choices:

  • present ← (default)

  • absent

release_values

aliases: values

dictionary

Value to pass to chart.

Default: {}

replace

boolean

added in 1.11.0 of community.kubernetes

Reuse the given name, only if that name is a deleted release which remains in the history.

This is unsafe in production environment.

Choices:

  • no ← (default)

  • yes

skip_crds

boolean

added in 1.2.0 of community.kubernetes

Skip custom resource definitions when installing or upgrading.

Choices:

  • no ← (default)

  • yes

update_repo_cache

boolean

Run helm repo update before the operation. Can be run as part of the package installation or as a separate step.

Choices:

  • no ← (default)

  • yes

validate_certs

aliases: verify_ssl

boolean

added in 1.2.0 of community.kubernetes

Whether or not to verify the API server’s SSL certificates. Can also be specified via K8S_AUTH_VERIFY_SSL environment variable.

Choices:

  • no

  • yes ← (default)

values_files

list / elements=string

added in 1.1.0 of community.kubernetes

Value files to pass to chart.

Paths will be read from the target host’s filesystem, not the host running ansible.

values_files option is evaluated before values option if both are used.

Paths are evaluated in the order the paths are specified.

Default: []

wait

boolean

Wait until all Pods, PVCs, Services, and minimum number of Pods of a Deployment are in a ready state before marking the release as successful.

Choices:

  • no ← (default)

  • yes

wait_timeout

string

Timeout when wait option is enabled (helm2 is a number of seconds, helm3 is a duration).

Examples

- name: Deploy latest version of Prometheus chart inside monitoring namespace (and create it)
  community.kubernetes.helm:
    name: test
    chart_ref: stable/prometheus
    release_namespace: monitoring
    create_namespace: true

# From repository
- name: Add stable chart repo
  community.kubernetes.helm_repository:
    name: stable
    repo_url: "https://kubernetes.github.io/ingress-nginx"

- name: Deploy latest version of Grafana chart inside monitoring namespace with values
  community.kubernetes.helm:
    name: test
    chart_ref: stable/grafana
    release_namespace: monitoring
    values:
      replicas: 2

- name: Deploy Grafana chart on 5.0.12 with values loaded from template
  community.kubernetes.helm:
    name: test
    chart_ref: stable/grafana
    chart_version: 5.0.12
    values: "{{ lookup('template', 'somefile.yaml') | from_yaml }}"

- name: Deploy Grafana chart using values files on target
  community.kubernetes.helm:
    name: test
    chart_ref: stable/grafana
    release_namespace: monitoring
    values_files:
      - /path/to/values.yaml

- name: Remove test release and waiting suppression ending
  community.kubernetes.helm:
    name: test
    state: absent
    wait: true

# From git
- name: Git clone stable repo on HEAD
  ansible.builtin.git:
    repo: "http://github.com/helm/charts.git"
    dest: /tmp/helm_repo

- name: Deploy Grafana chart from local path
  community.kubernetes.helm:
    name: test
    chart_ref: /tmp/helm_repo/stable/grafana
    release_namespace: monitoring

# From url
- name: Deploy Grafana chart on 5.6.0 from url
  community.kubernetes.helm:
    name: test
    chart_ref: "https://github.com/grafana/helm-charts/releases/download/grafana-5.6.0/grafana-5.6.0.tgz"
    release_namespace: monitoring

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

command

string

Full helm command built by this module, in case you want to re-run the command outside the module or debug a problem.

Returned: always

Sample: “helm upgrade …”

status

complex

A dictionary of status output

Returned: on success Creation/Upgrade/Already deploy

appversion

string

Version of app deployed

Returned: always

chart

string

Chart name and chart version

Returned: always

name

string

Name of the release

Returned: always

namespace

string

Namespace where the release is deployed

Returned: always

revision

string

Number of time where the release has been updated

Returned: always

status

string

Status of release (can be DEPLOYED, FAILED, …)

Returned: always

updated

string

The Date of last update

Returned: always

values

string

Dict of Values used to deploy

Returned: always

stderr

string

Full helm command stderr, in case you want to display it or examine the event log

Returned: always

Sample: “”

stdout

string

Full helm command stdout, in case you want to display it or examine the event log

Returned: always

Sample: “”

Authors

  • Lucas Boisserie (@LucasBoisserie)

  • Matthieu Diehr (@d-matt)