kubernetes.core.helm

Manages Kubernetes packages with the Helm package manager

Version added: 0.11.0

Synopsis
Requirements
Parameters
Notes
Examples
Return Values
Status

Synopsis

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

Requirements

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

helm (https://github.com/helm/helm/releases)
yaml (https://pypi.org/project/PyYAML/)

Parameters

Parameter		Choices/Defaults	Comments
api_key string added in 1.2.0			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			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		Choices: no ← yes	Create the release namespace if not present.
dependency_update boolean added in 2.4.0		Choices: no ← yes	Run standalone `helm dependency update CHART` before the operation. Run inline `--dependency-update` with `helm install` command. This feature is not supported yet with the `helm upgrade` command. So we should consider to use dependency_update options with replace option enabled when specifying chart_repo_url. The dependency_update option require the add of `dependencies` block in `Chart.yaml/requirements.yaml` file. For more information please visit https://helm.sh/docs/helm/helm_dependency/ aliases: dep_up
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			Limit the maximum number of revisions saved per release. mutually exclusive with with `replace`.
host string added in 1.2.0			Provide a URL for accessing the API. Can also be specified via `K8S_AUTH_HOST` environment variable.
kubeconfig raw			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. The configuration can be provided as dictionary. Added in version 2.4.0. aliases: kubeconfig_path
post_renderer string added in 2.4.0			Path to an executable to be used for post rendering.
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		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`.
reset_values boolean added in 2.5.0		Choices: no yes ←	When upgrading package, reset the values to the ones built into the chart.
reuse_values boolean added in 2.5.0		Choices: no yes	When upgrading package, specifies wether to reuse the last release's values and merge in any overrides from parameters release_values, values_files or set_values. If reset_values is set to `True`, this is ignored.
set_values list / elements=dictionary added in 2.4.0			Values to pass to chart configuration
	value string / required		Value to pass to chart configuration (e.g phase=prod).
	value_type -	Choices: raw ← string json file	Use `raw` set individual value. Use `string` to force a string for an individual value. Use `file` to set individual values from a file when the value itself is too long for the command line or is dynamically generated. Use `json` to set json values (scalars/objects/arrays). This feature requires helm>=3.10.0.
skip_crds boolean added in 1.2.0		Choices: no ← yes	Skip custom resource definitions when installing or upgrading.
timeout string added in 2.3.0			A Go duration (described here https://pkg.go.dev/time#ParseDuration) value to wait for Kubernetes commands to complete. This defaults to 5m0s. similar to `wait_timeout` but does not required `wait` to be activated. Mutually exclusive with `wait_timeout`.
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 (see Examples).
validate_certs boolean added in 1.2.0		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		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	When release_state is set to `present`, 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. When release_state is set to `absent`, will wait until all the resources are deleted before returning. It will wait for as long as wait_timeout. This feature requires helm>=3.7.0. Added in version 2.3.0.
wait_timeout string			Timeout when wait option is enabled (helm2 is a number of seconds, helm3 is a duration). The use of wait_timeout to wait for kubernetes commands to complete has been deprecated and will be removed after 2022-12-01.

Notes

Note

The default idempotency check can fail to report changes when release_state is set to present and chart_repo_url is defined. Install helm diff >= 3.4.1 for better results.

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

- name: Separately update the repository cache
  kubernetes.core.helm:
    name: dummy
    namespace: kube-system
    state: absent
    update_repo_cache: true

- name: Deploy Grafana chart using set values on target
  kubernetes.core.helm:
    name: test
    chart_ref: stable/grafana
    release_namespace: monitoring
    set_values:
      - value: phase=prod
        value_type: string

# 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

# Deploy latest version
- name: Deploy latest version of Grafana chart using reuse_values
  kubernetes.core.helm:
    name: test
    chart_ref: stable/grafana
    release_namespace: monitoring
    reuse_values: true
    values:
      replicas: 2
      version: 3e8ec0b2dffa40fb97d5342e4af887de95faa8c61a62480dd7f8aa03dffcf533

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

Status

Authors

Lucas Boisserie (@LucasBoisserie)
Matthieu Diehr (@d-matt)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

kubernetes.core.helm_module.rst

kubernetes.core.helm_module.rst

kubernetes.core.helm

Synopsis

Requirements

Parameters

Notes

Examples

Return Values

Status

Authors

Files

kubernetes.core.helm_module.rst

Latest commit

History

kubernetes.core.helm_module.rst

File metadata and controls

kubernetes.core.helm

Synopsis

Requirements

Parameters

Notes

Examples

Return Values

Status

Authors