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

Note

This plugin is part of the kubernetes.core collection (version 2.2.2).

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 kubernetes.core.

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

New in version 0.11.0: of kubernetes.core

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 Choices/Defaults Comments
api_key
string
added in 1.2.0 of kubernetes.core
Token used to authenticate with the API. Can also be specified via K8S_AUTH_API_KEY environment variable.
atomic
boolean
    Choices:
  • no ←
  • yes
If set, the installation process deletes the installation on failure.
binary_path
path
The path of a helm binary to use.
ca_cert
path
added in 1.2.0 of kubernetes.core
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.

aliases: ssl_ca_cert
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
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.

aliases: kube_context
create_namespace
boolean
added in 0.11.1 of kubernetes.core
    Choices:
  • no ←
  • yes
Create the release namespace if not present.
disable_hook
boolean
    Choices:
  • no ←
  • yes
Helm option to disable hook on install/upgrade/delete.
force
boolean
    Choices:
  • no ←
  • yes
Helm option to force reinstall, ignore on new install.
history_max
integer
added in 2.2.0 of kubernetes.core
Limit the maximum number of revisions saved per release.
mutually exclusive with with replace.
host
string
added in 1.2.0 of kubernetes.core
Provide a URL for accessing the API. Can also be specified via K8S_AUTH_HOST environment variable.
kubeconfig
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.

aliases: kubeconfig_path
purge
boolean
    Choices:
  • no
  • yes ←
Remove the release from the store and make its name free for later use.
release_name
string / required
Release name to manage.

aliases: name
release_namespace
string / required
Kubernetes namespace where the chart should be installed.

aliases: namespace
release_state
string
    Choices:
  • present ←
  • absent
Desirated state of release.

aliases: state
release_values
dictionary
Default:
{}
Value to pass to chart.

aliases: values
replace
boolean
added in 1.11.0 of kubernetes.core
    Choices:
  • no ←
  • yes
Reuse the given name, only if that name is a deleted release which remains in the history.
This is unsafe in production environment.
mutually exclusive with with history_max.
skip_crds
boolean
added in 1.2.0 of kubernetes.core
    Choices:
  • no ←
  • yes
Skip custom resource definitions when installing or upgrading.
update_repo_cache
boolean
    Choices:
  • no ←
  • yes
Run helm repo update before the operation. Can be run as part of the package installation or as a separate step.
validate_certs
boolean
added in 1.2.0 of kubernetes.core
    Choices:
  • no
  • yes ←
Whether or not to verify the API server's SSL certificates. Can also be specified via K8S_AUTH_VERIFY_SSL environment variable.

aliases: verify_ssl
values_files
list / elements=string
added in 1.1.0 of kubernetes.core
Default:
[]
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.
wait
boolean
    Choices:
  • no ←
  • yes
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.
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)
  kubernetes.core.helm:
    name: test
    chart_ref: stable/prometheus
    release_namespace: monitoring
    create_namespace: true

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

- name: Deploy latest version of Grafana chart inside monitoring namespace with values
  kubernetes.core.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
  kubernetes.core.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
  kubernetes.core.helm:
    name: test
    chart_ref: stable/grafana
    release_namespace: monitoring
    values_files:
      - /path/to/values.yaml

- name: Remove test release and waiting suppression ending
  kubernetes.core.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
  kubernetes.core.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
  kubernetes.core.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

# Using complex Values
- name: Deploy new-relic client chart
  kubernetes.core.helm:
    name: newrelic-bundle
    chart_ref: newrelic/nri-bundle
    release_namespace: default
    force: True
    wait: True
    replace: True
    update_repo_cache: True
    disable_hook: True
    values:
      global:
        licenseKey: "{{ nr_license_key }}"
        cluster: "{{ site_name }}"
      newrelic-infrastructure:
        privileged: True
      ksm:
        enabled: True
      prometheus:
        enabled: True
      kubeEvents:
        enabled: True
      logging:
        enabled: True

Return Values

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

Key Returned Description
command
string
always
Full `helm` command built by this module, in case you want to re-run the command outside the module or debug a problem.

Sample:
helm upgrade ...
status
complex
on success Creation/Upgrade/Already deploy
A dictionary of status output

 
appversion
string
always
Version of app deployed

 
chart
string
always
Chart name and chart version

 
name
string
always
Name of the release

 
namespace
string
always
Namespace where the release is deployed

 
revision
string
always
Number of time where the release has been updated

 
status
string
always
Status of release (can be DEPLOYED, FAILED, ...)

 
updated
string
always
The Date of last update

 
values
string
always
Dict of Values used to deploy

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

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



Authors

  • Lucas Boisserie (@LucasBoisserie)

  • Matthieu Diehr (@d-matt)