---
page_title: "helm: helm_release"
sidebar_current: "docs-helm-release"
description: |-

---
# Resource: helm_release

A Release is an instance of a chart running in a Kubernetes cluster.

A Chart is a Helm package. It contains all of the resource definitions necessary to run an application, tool, or service inside of a Kubernetes cluster.

`helm_release` describes the desired status of a chart in a kubernetes cluster.

<!-- schema generated by tfplugindocs -->
## Schema

### Required

- `chart` (String) Chart name to be installed. A path may be used.
- `name` (String) Release name. The length must not be longer than 53 characters.

### Optional

- `atomic` (Boolean) If set, installation process purges chart on fail. The wait flag will be set automatically if atomic is used. Defaults to `false`.
- `cleanup_on_fail` (Boolean) Allow deletion of new resources created in this upgrade when upgrade fails. Defaults to `false`.
- `create_namespace` (Boolean) Create the namespace if it does not exist. Defaults to `false`.
- `dependency_update` (Boolean) Run helm dependency update before installing the chart. Defaults to `false`.
- `description` (String) Add a custom description
- `devel` (Boolean) Use chart development versions, too. Equivalent to version '>0.0.0-0'. If `version` is set, this is ignored
- `disable_crd_hooks` (Boolean) Prevent CRD hooks from, running, but run other hooks.  See helm install --no-crd-hook
- `disable_openapi_validation` (Boolean) If set, the installation process will not validate rendered templates against the Kubernetes OpenAPI Schema. Defaults to `false`.
- `disable_webhooks` (Boolean) Prevent hooks from running.Defaults to `false`.
- `force_update` (Boolean) Force resource update through delete/recreate if needed. Defaults to `false`.
- `keyring` (String) Location of public keys used for verification. Used only if `verify` is true. Defaults to `/.gnupg/pubring.gpg` in the location set by `home`.
- `lint` (Boolean) Run helm lint when planning. Defaults to `false`.
- `max_history` (Number) Limit the maximum number of revisions saved per release. Use 0 for no limit. Defaults to 0 (no limit).
- `namespace` (String) Namespace to install the release into. Defaults to `default`.
- `pass_credentials` (Boolean) Pass credentials to all domains. Defaults to `false`.
- `postrender` (Block List, Max: 1) Postrender command configuration. (see [below for nested schema](#nestedblock--postrender))
- `recreate_pods` (Boolean) Perform pods restart during upgrade/rollback. Defaults to `false`.
- `render_subchart_notes` (Boolean) If set, render subchart notes along with the parent. Defaults to `true`.
- `replace` (Boolean) Re-use the given name, even if that name is already used. This is unsafe in production. Defaults to `false`.
- `repository` (String) Repository where to locate the requested chart. If is a URL the chart is installed without installing the repository.
- `repository_ca_file` (String) The Repositories CA File
- `repository_cert_file` (String) The repositories cert file
- `repository_key_file` (String) The repositories cert key file
- `repository_password` (String, Sensitive) Password for HTTP basic authentication
- `repository_username` (String) Username for HTTP basic authentication
- `reset_values` (Boolean) When upgrading, reset the values to the ones built into the chart. Defaults to `false`.
- `reuse_values` (Boolean) When upgrading, reuse the last release's values and merge in any overrides. If 'reset_values' is specified, this is ignored. Defaults to `false`.
- `set` (Block Set) Custom values to be merged with the values. (see [below for nested schema](#nestedblock--set))
- `set_wo` (Attribute List) Custom values to be merged with the values. This is the same as "set" but write-only. (see [below for nested schema](#nestedblock--set))
- `set_wo_revision` (Number) The current revision of the write-only "set_wo" attribute. Incrementing this integer value will cause Terraform to update the write-only value.`  
- `set_list` (Block List) Custom list values to be merged with the values. (see [below for nested schema](#nestedblock--set_list))
- `set_sensitive` (Block Set) Custom sensitive values to be merged with the values. (see [below for nested schema](#nestedblock--set_sensitive))
- `skip_crds` (Boolean) If set, no CRDs will be installed. By default, CRDs are installed if not already present. Defaults to `false`.
- `timeout` (Number) Time in seconds to wait for any individual kubernetes operation. Defaults to 300 seconds.
- `upgrade_install` (Boolean) If true, the provider will install the release at the specified version even if a release not controlled by the provider is present: this is equivalent to running 'helm upgrade --install' with the Helm CLI. WARNING: this may not be suitable for production use -- see the 'Upgrade Mode' note in the provider documentation. Defaults to `false`.
- `values` (List of String) List of values in raw yaml format to pass to helm.
- `verify` (Boolean) Verify the package before installing it.Defaults to `false`.
- `version` (String) Specify the exact chart version to install. If this is not specified, the latest version is installed.
- `wait` (Boolean) Will wait until all resources are in a ready state before marking the release as successful. Defaults to `true`.
- `wait_for_jobs` (Boolean) If wait is enabled, will wait until all Jobs have been completed before marking the release as successful. Defaults to `false``.

### Read-Only

- `id` (String) The ID of this resource.
- `manifest` (String) The rendered manifest as JSON.
- `metadata` (List of Object) Status of the deployed release. (see [below for nested schema](#nestedatt--metadata))
- `status` (String) Status of the release.

<a id="nestedblock--postrender"></a>
### Nested Schema for `postrender`

Required:

- `binary_path` (String) The command binary path.

Optional:

- `args` (List of String) an argument to the post-renderer (can specify multiple)


<a id="nestedblock--set"></a>
### Nested Schema for `set`

Required:

- `name` (String)

Optional:

- `type` (String)
- `value` (String)

<a id="nestedblock--set_list"></a>
### Nested Schema for `set_list`

Required:

- `name` (String)
- `value` (List of String)


<a id="nestedblock--set_sensitive"></a>
### Nested Schema for `set_sensitive`

Required:

- `name` (String)
- `value` (String, Sensitive)

Optional:

- `type` (String)


<a id="nestedatt--metadata"></a>
### Nested Schema for `metadata`

Read-Only:

- `app_version` (String)
- `chart` (String)
- `first_deployed` (Number)
- `last_deployed` (Number)
- `name` (String)
- `namespace` (String)
- `notes` (String)
- `revision` (Number)
- `values` (String)
- `version` (String)





## Example Usage - Chart Repository

```terraform
resource "helm_release" "example" {
  name       = "my-redis-release"
  repository = "https://charts.bitnami.com/bitnami"
  chart      = "redis"
  version    = "6.0.1"

  set = [
    {
      name  = "cluster.enabled"
      value = "true"
    },
    {
      name  = "metrics.enabled"
      value = "true"
    }
  ]

  set = [
    {
      name  = "service.annotations.prometheus\\.io/port"
      value = "9127"
      type  = "string"
    }
  ]
}
```

## Example Usage - Local Chart

In case a Chart is not available from a repository, a path may be used:

```terraform
resource "helm_release" "example" {
  name       = "my-local-chart"
  chart      = "./charts/example"
}
```

## Example Usage - Chart URL

An absolute URL to the .tgz of the Chart may also be used:

```terraform
resource "helm_release" "example" {
  name  = "redis"
  chart = "https://charts.bitnami.com/bitnami/redis-10.7.16.tgz"
}
```

## Example Usage - Chart Repository configured from OCI Registry

Provider supports grabbing charts from an OCI repository:

```terraform
provider "helm" {
  kubernetes = {
    config_path = "~/.kube/config"
  }

  registries = [
    {
      url      = "oci://localhost:5000"
      username = "username"
      password = "password"
    }
  ]
}

resource "helm_release" "example" {
  name        = "testchart"
  namespace   = "helm_registry"
  repository  = "oci://localhost:5000/helm-charts"
  version     = "1.2.3"
  chart       = "test-chart"
}
```

## Example Usage - Chart Repository configured using GCS/S3

The provider also supports helm plugins such as GCS and S3 that add S3/GCS helm repositories by using `helm plugin install`

```terraform
# Install GCS plugin
`helm plugin install https://github.com/hayorov/helm-gcs.git`

# Run follow commands to setup GCS repository

# Init a new repository:
#   helm gcs init gs://bucket/path

# Add your repository to Helm:
#   helm repo add repo-name gs://bucket/path

# Push a chart to your repository:
#   helm gcs push chart.tar.gz repo-name

# Update Helm cache:
#   helm repo update

# Get your chart:

resource "helm_release" "GCS" {
  name        = "GCS"
  repository  = "gs://tf-test-helm-repo/charts"
  chart       = "chart"
}
```

```terraform
# Install AWS S3 plugin
`helm plugin install https://github.com/hypnoglow/helm-s3.git`

# Run follow commands to setup S3 repository

# Init a new repository:
#   helm s3 init s3://my-helm-charts/stable/myapp

# Add your repository to Helm:
#   helm repo add stable-myapp s3://my-helm-charts/stable/myapp/

# Push a chart to your repository:
#   helm s3 push chart.tar.gz repo-name

# Update Helm cache:
#   helm repo update

# Get your chart:

resource "helm_release" "S3" {
  name        = "S3"
  repository  = "s3://tf-test-helm-repo/charts"
  chart       = "chart"
}
```

## Example Usage - Chart Repository configured outside of Terraform

The provider also supports repositories that are added to the local machine outside of Terraform by running `helm repo add`

```terraform
# run this first: `helm repo add bitnami https://charts.bitnami.com/bitnami`

resource "helm_release" "example" {
  name  = "redis"
  chart = "bitnami/redis"
}
```

The `set`, `set_list`, and `set_sensitive` blocks support:

* `name` - (Required) full name of the variable to be set.
* `value` - (Required; Optional for `set`) value of the variable to be set.
* `type` - (Optional) type of the variable to be set. Valid options are `auto` and `string`.

Since Terraform Utilizes HCL as well as Helm using the Helm Template Language, it's necessary to escape the `{}`, `[]`, `.`, and `,` characters twice in order for it to be parsed. `name` should also be set to the `value path`, and `value` is the desired value that will be set.

```terraform
set = [
  {
    name  = "grafana.ingress.annotations.alb\\.ingress\\.kubernetes\\.io/group\\.name"
    value = "shared-ingress"
  }
]
```

```terraform
set_list = [
  {
    name  = "hashicorp"
    value = ["terraform", "nomad", "vault"]
  }
]
```

```terraform
controller:
  pod:
    annotations:
      status.kubernetes.io/restart-on-failure: {"timeout": "30s"}
```

```terraform
set = [
  {
    name  = "controller.pod.annotations.status\\.kubernetes\\.io/restart-on-failure"
    value = "\\{\"timeout\": \"30s\"\\}"
  }
]

```

The `postrender` block supports two attributes:

* `binary_path` - (Required) relative or full path to command binary.
* `args` - (Optional) a list of arguments to supply to the post-renderer.

## Upgrade Mode Notes

When using the Helm CLI directly, it is possible to use `helm upgrade --install` to
_idempotently_ install a release.  For example, `helm upgrade --install mariadb charts/mariadb --verson 7.1.0`
will check to see if there is already a release called `mariadb`: if there is, ensure that it is set to version
7.1.0, and if there is not, install that version from scratch. (See the documentation for the
[helm upgrade](https://helm.sh/docs/helm/helm_upgrade) command for more details.)

 **NOTE:** The mechanics of this approach are subtly different from the defaults and you can easily produce unexpected or undesirable results if you are not careful:
using this approach in production is not necessarily recommended!

If upgrade mode is enabled by setting the `upgrade_install` attribute to `true`, the provider will first check to see
if a release with the given name already exists.  If the release does not already exist, the provider will perform a
from-scratch installation of the chart.  In this case, all resource attributes are honored.

However, if the release _does_ already exist, the provider will attempt to upgrade the release to
the state defined in the resource, using the same strategy as the [helm upgrade](https://helm.sh/docs/helm/helm_upgrade)
command.

When using `upgrade_install`, the `version` attribute is used to determine the version of the chart to install or
upgrade to.  If the `version` attribute is not set, the provider will attempt to determine the version of the chart
from the existing release and will use that version for the upgrade: this is to ensure that using `upgrade_install`
does not inadvertently change the version of the chart being used.

**CRITICAL**: The user-supplied values passed to the chart in the new revision will be the ones specified in the
`helm_release` resource, not the values used in the original installation of the chart. This means that if
you are using `upgrade_install` to manage a release that was originally installed with a different set of values,
you must ensure that the values in the `helm_release` resource are correct, or you may inadvertently change the
configuration of the release. Additionally, since there is no existing terraform state to compare against, you
must manually inspect the installed release's values with the `helm get values` CLI command.

**IMPORTANT**: Even if you are "upgrading" to the same version of the chart that is already present in the cluster,
the `helm_release` resource will still show as "changed" in the terraform plan output, because there is no existing
state for it to compare against. This also means that in the apply stage, the provider will in fact reinstall the
chart, which means that if there are any
[deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/),
[daemonset](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) or
[statefulset](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) resources in the chart, they will
be replaced, which will cause a rolling update of the pods.

## Import

A Helm Release resource can be imported using its namespace and name e.g.

```shell
$ terraform import helm_release.example default/example-name
```

~> **NOTE:** Since the `repository` attribute is not being persisted as metadata by helm, it will not be set to any value by default. All other provider specific attributes will be set to their default values and they can be overriden after running `apply` using the resource definition configuration.