124 lines
5.9 KiB
Cheetah
124 lines
5.9 KiB
Cheetah
---
|
|
page_title: "helm: helm_release"
|
|
sidebar_current: "docs-helm-release"
|
|
description: |-
|
|
|
|
---
|
|
# Resource: {{ .Name }}
|
|
|
|
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.
|
|
|
|
{{ .SchemaMarkdown }}
|
|
|
|
|
|
## Example Usage - Chart Repository
|
|
|
|
{{tffile "examples/resources/release/example_1.tf"}}
|
|
|
|
## Example Usage - Local Chart
|
|
|
|
In case a Chart is not available from a repository, a path may be used:
|
|
|
|
{{tffile "examples/resources/release/example_2.tf"}}
|
|
|
|
## Example Usage - Chart URL
|
|
|
|
An absolute URL to the .tgz of the Chart may also be used:
|
|
|
|
{{tffile "examples/resources/release/example_3.tf"}}
|
|
|
|
## Example Usage - Chart Repository configured from OCI Registry
|
|
|
|
Provider supports grabbing charts from an OCI repository:
|
|
|
|
{{tffile "examples/resources/release/example_4.tf"}}
|
|
|
|
## 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`
|
|
|
|
{{tffile "examples/resources/release/example_5.tf"}}
|
|
|
|
{{tffile "examples/resources/release/example_6.tf"}}
|
|
|
|
## 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`
|
|
|
|
{{tffile "examples/resources/release/example_7.tf"}}
|
|
|
|
The `set`, and `set_sensitive` blocks support:
|
|
|
|
* `name` - (Required) full name of the variable to be set.
|
|
* `value` - (Required) value of the variable to be set.
|
|
* `type` - (Optional) type of the variable to be set. Valid options are `auto`, `string`, and `literal`.
|
|
|
|
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.
|
|
|
|
{{tffile "examples/resources/release/example_8.tf"}}
|
|
|
|
{{tffile "examples/resources/release/example_9.tf"}}
|
|
|
|
{{tffile "examples/resources/release/example_10.tf"}}
|
|
|
|
{{tffile "examples/resources/release/example_11.tf"}}
|
|
|
|
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.
|