upstream/terraform-provider-helm
1
0
Fork 0
mirror of https://github.com/hashicorp/terraform-provider-helm.git synced 2025-12-18 23:26:08 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Migrate to tfplugindocs structure (#1375)

Browse source 
Co-authored-by: Brian Flad <bflad417@gmail.com
This commit is contained in:
Sheneska Williams 2024-05-31 15:02:12 -04:00 committed by GitHub
parent 593d716fdb
commit 97964e8724
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
36 changed files with 1185 additions and 508 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.copywrite.hcl
View file

@ -11,5 +11,6 @@ project {
".release/**",
"helm/testdata/**",
"vendor/**",
"examples/**"
]
}

2
.github/workflows/website.yaml vendored
View file

@ -2,7 +2,7 @@ name: website
on:
push:
paths:
- "website/**"
- "docs/**"
pull_request:
branches:
- main

8
.markdownlinkcheck.json
View file

@ -15,15 +15,15 @@
},
{
"pattern": "^/docs/providers/helm/",
"replacement": "file:///github/workspace/website/docs/"
"replacement": "file:///github/workspace/docs/"
},
{
"pattern": "^(getting-started).html.markdown(#.*)?$",
"replacement": "file:///github/workspace/website/docs/guides/$1.html.md$2"
"replacement": "file:///github/workspace/docs/guides/$1.html.md$2"
},
{
"pattern": "^file:///github/workspace/website/docs/guides/(.*)\\.markdown(#.*)?$",
"replacement": "file:///github/workspace/website/docs/guides/$1.md$2"
"pattern": "^file:///github/workspace/docs/guides/(.*)\\.markdown(#.*)?$",
"replacement": "file:///github/workspace/docs/guides/$1.md$2"
}
]
}

2
.markdownlint.yml
View file

@ -14,4 +14,6 @@ MD006: false
MD012: false
MD013: false
MD014: false
MD022: false
MD024: false
MD033: false

2
GNUmakefile
View file

@ -122,7 +122,7 @@ PROVIDER_DIR_DOCKER := $(abspath $(lastword $(dir $(MAKEFILE_LIST))))
website-lint:
@echo "==> Checking website against linters..."
@echo "==> Running markdownlint-cli using DOCKER='$(DOCKER)', DOCKER_RUN_OPTS='$(DOCKER_RUN_OPTS)' and DOCKER_VOLUME_OPTS='$(DOCKER_VOLUME_OPTS)'"
@$(DOCKER) run --rm $(DOCKER_RUN_OPTS) -v $(PROVIDER_DIR_DOCKER):/workspace:$(DOCKER_VOLUME_OPTS) -w /workspace 06kellyjac/markdownlint-cli ./website \
@$(DOCKER) run --rm $(DOCKER_RUN_OPTS) -v $(PROVIDER_DIR_DOCKER):/workspace:$(DOCKER_VOLUME_OPTS) -w /workspace 06kellyjac/markdownlint-cli ./docs \
&& (echo; echo "PASS - website markdown files pass linting"; echo ) \
|| (echo; echo "FAIL - issues found in website markdown files"; echo ; exit 1)
@echo "==> Checking for broken links..."

221
docs/data-sources/template.md Normal file
View file

@ -0,0 +1,221 @@
---
page_title: "helm: helm_template"
sidebar_current: "docs-helm-template"
description: |-
---
# Data Source: helm_template
Render chart templates locally.
`helm_template` renders chart templates locally and exposes the rendered manifests in the data source attributes. `helm_template` mimics the functionality of the `helm template` command.
The arguments aim to be identical to the `helm_release` resource.
For further details on the `helm template` command, refer to the [Helm documentation](https://helm.sh/docs/helm/helm_template/).
<!-- schema generated by tfplugindocs -->
## Schema
### Required
- `chart` (String) Chart name to be installed. A path may be used.
- `name` (String) Release name.
### Optional
- `api_versions` (List of String) Kubernetes api versions used for Capabilities.APIVersions
- `atomic` (Boolean) If set, installation process purges chart on fail. The wait flag will be set automatically if atomic is used
- `crds` (List of String) List of rendered CRDs from the chart.
- `create_namespace` (Boolean) Create the namespace if it does not exist
- `dependency_update` (Boolean) Run helm dependency update before installing the chart
- `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_openapi_validation` (Boolean) If set, the installation process will not validate rendered templates against the Kubernetes OpenAPI Schema
- `disable_webhooks` (Boolean) Prevent hooks from running.
- `include_crds` (Boolean) Include CRDs in the templated output
- `is_upgrade` (Boolean) Set .Release.IsUpgrade instead of .Release.IsInstall
- `keyring` (String) Location of public keys used for verification. Used only if `verify` is true
- `kube_version` (String) Kubernetes version used for Capabilities.KubeVersion
- `manifest` (String) Concatenated rendered chart templates. This corresponds to the output of the `helm template` command.
- `manifests` (Map of String) Map of rendered chart templates indexed by the template name.
- `namespace` (String) Namespace to install the release into.
- `notes` (String) Rendered notes if the chart contains a `NOTES.txt`.
- `pass_credentials` (Boolean) Pass credentials to all domains
- `postrender` (Block List, Max: 1) Postrender command configuration. (see [below for nested schema](#nestedblock--postrender))
- `render_subchart_notes` (Boolean) If set, render subchart notes along with the parent
- `replace` (Boolean) Re-use the given name, even if that name is already used. This is unsafe in production
- `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
- `reuse_values` (Boolean) When upgrading, reuse the last release's values and merge in any overrides. If 'reset_values' is specified, this is ignored
- `set` (Block Set) Custom values to be merged with the values. (see [below for nested schema](#nestedblock--set))
- `set_list` (Block List) Custom sensitive 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))
- `set_string` (Block Set, Deprecated) Custom string values to be merged with the values. (see [below for nested schema](#nestedblock--set_string))
- `show_only` (List of String) Only show manifests rendered from the given templates
- `skip_crds` (Boolean) If set, no CRDs will be installed. By default, CRDs are installed if not already present
- `skip_tests` (Boolean) If set, tests will not be rendered. By default, tests are rendered
- `timeout` (Number) Time in seconds to wait for any individual kubernetes operation.
- `validate` (Boolean) Validate your manifests against the Kubernetes cluster you are currently pointing at. This is the same validation performed on an install
- `values` (List of String) List of values in raw yaml format to pass to helm.
- `verify` (Boolean) Verify the package before installing it.
- `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.
### Read-Only
- `id` (String) The ID of this resource.
<a id="nestedblock--postrender"></a>
### Nested Schema for `postrender`
Required:
- `binary_path` (String) The command binary path.
<a id="nestedblock--set"></a>
### Nested Schema for `set`
Required:
- `name` (String)
- `value` (String)
Optional:
- `type` (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="nestedblock--set_string"></a>
### Nested Schema for `set_string`
Required:
- `name` (String)
- `value` (String)
## Example Usage
### Render all chart templates
The following example renders all templates of the `mariadb` chart of the official Helm stable repository. Concatenated manifests are exposed as output variable `mariadb_instance_manifest`.
```terraform
data "helm_template" "mariadb_instance" {
name = "mariadb-instance"
namespace = "default"
repository = "https://charts.helm.sh/stable"
chart = "mariadb"
version = "7.1.0"
set {
name = "service.port"
value = "13306"
}
set_sensitive {
name = "rootUser.password"
value = "s3cr3t!"
}
}
resource "local_file" "mariadb_manifests" {
for_each = data.helm_template.mariadb_instance.manifests
filename = "./${each.key}"
content = each.value
}
output "mariadb_instance_manifest" {
value = data.helm_template.mariadb_instance.manifest
}
output "mariadb_instance_manifests" {
value = data.helm_template.mariadb_instance.manifests
}
output "mariadb_instance_notes" {
value = data.helm_template.mariadb_instance.notes
}
```
### Render selected chart templates
The following example renders only the templates `master-statefulset.yaml` and `master-svc.yaml` of the `mariadb` chart of the official Helm stable repository.
```terraform
data "helm_template" "mariadb_instance" {
name = "mariadb-instance"
namespace = "default"
repository = "https://charts.helm.sh/stable"
chart = "mariadb"
version = "7.1.0"
show_only = [
"templates/master-statefulset.yaml",
"templates/master-svc.yaml",
]
set {
name = "service.port"
value = "13306"
}
set_sensitive {
name = "rootUser.password"
value = "s3cr3t!"
}
}
resource "local_file" "mariadb_manifests" {
for_each = data.helm_template.mariadb_instance.manifests
filename = "./${each.key}"
content = each.value
}
output "mariadb_instance_manifest" {
value = data.helm_template.mariadb_instance.manifest
}
output "mariadb_instance_manifests" {
value = data.helm_template.mariadb_instance.manifests
}
output "mariadb_instance_notes" {
value = data.helm_template.mariadb_instance.notes
}
```

72
docs/guides/v2-upgrade-guide.md Normal file
View file

@ -0,0 +1,72 @@
---
layout : "helm"
page_title: "Helm: Upgrade Guide for Helm Provider v2.0.0"
description: |-
This guide covers the changes introduced in v2.0.0 of the Helm provider and what you may need to do to upgrade your configuration.
---
# Upgrading to v2.0.0 of the Helm provider
This guide covers the changes introduced in v2.0.0 of the Helm provider and what you may need to do to upgrade your configuration.
## Changes in v2.0.0
### Changes to Kubernetes credentials supplied in the provider block
We have made several changes to the way access to Kubernetes is configured in the provider block.
1. The `load_config_file` attribute has been removed.
2. Support for the `KUBECONFIG` environment variable has been dropped and replaced with `KUBE_CONFIG_PATH`.
3. The `config_path` attribute will no longer default to `~/.kube/config` and must be set explicitly.
The above changes have been made to encourage the best practise of configuring access to Kubernetes in the provider block explicitly, instead of relying upon default paths or `KUBECONFIG` being set. We have done this because allowing the provider to configure its access to Kubernetes implicitly caused confusion with a subset of our users. It also created risk for users who use Terraform to manage multiple clusters. Requiring explicit configuring for kubernetes in the provider block eliminates the possibility that the configuration will be applied to the wrong cluster.
You will therefore need to explicity configure access to your Kubernetes cluster in the provider block going forward. For many users this will simply mean specifying the `config_path` attribute in the provider block. Users already explicitly configuring the provider should not be affected by this change, but will need to remove the `load_config_file` attribute if they are currently using it.
When running Terraform inside a Kubernetes cluster no provider configuration is neccessary, as the provider will detect that is has access to a service account token.
### Removal of the `helm_repository` data source
This feature of the provider caused a fair bit of confusion and was a source of instability as data sources are not supposed to be stateful. This data source performed a stateful operation that modified the filesystem, mirroring similar functionality to the `helm repo add` command. It has been the recommendation for some time to configure repository information explicity at the `helm_resource` level and so the data source has been removed. See the example below.
```hcl
resource "helm_release" "redis" {
name = "redis"
repository = "https://charts.bitnami.com/bitnami"
chart = "redis"
}
```
The provider will continue to work with repositories that are configured with `helm repo add` before Terraform is run.
### Removal of `set_string` in the `helm_release` resource
The addition of a `type` attribute to the `set` block has rendered `set_string` superfluous so it has been removed. See the example below on how to set a string using the `set` block. This is used when the type of a value is an ambigious (e.g strings containing only numbers, true, false) and we want it to be explicitly parsed as a string.
```hcl
resource "helm_release" "redis" {
name = "redis"
repository = "https://charts.bitnami.com/bitnami"
chart = "redis"
set {
name = "test.value"
value = "123456"
type = "string"
}
}
```
### Dropped support for Terraform 0.11
All builds of the Helm provider going forward will no longer work with Terraform 0.11. See [Upgrade Guides](https://www.terraform.io/upgrade-guides/index.html) for how to migrate your configurations to a newer version of Terraform.
### Upgrade to v2 of the Terraform Plugin SDK
Contributors to the provider will be interested to know this upgrade has brought the latest version of the [Terraform Plugin SDK](https://github.com/hashicorp/terraform-plugin-sdk) which introduced a number of enhancements to the developer experience. Details of the changes introduced can be found under [Extending Terraform](https://www.terraform.io/docs/extend/guides/v2-upgrade-guide.html).
## Helm 2
We removed support in the provider for Helm 2 earlier this year. In accordance with the [Helm v2 deprecation timeline](https://helm.sh/blog/helm-v2-deprecation-timeline/) we will no longer be accepting PRs or handling issues that relate to Helm 2 going forward.

40
website/docs/index.html.markdown → docs/index.md
View file

@ -1,5 +1,4 @@
---
layout: "helm"
page_title: "Provider: Helm"
sidebar_current: "docs-helm-index"
description: |-
@ -14,15 +13,15 @@ Try the [hands-on tutorial](https://learn.hashicorp.com/tutorials/terraform/helm
## Resources
* [Resource: helm_release](r/release.html)
* [Resource: helm_release](r/release.md)
## Data Sources
* [Data Source: helm_template](d/template.html)
* [Data Source: helm_template](d/template.md)
## Example Usage
```hcl
```terraform
provider "helm" {
kubernetes {
config_path = "~/.kube/config"
@ -66,21 +65,20 @@ resource "helm_release" "nginx_ingress" {
The Helm provider can get its configuration in two ways:
1. _Explicitly_ by supplying attributes to the provider block. This includes:
1. *Explicitly* by supplying attributes to the provider block. This includes:
* [Using a kubeconfig file](#file-config)
* [Supplying credentials](#credentials-config)
* [Exec plugins](#exec-plugins)
2. _Implicitly_ through environment variables. This includes:
2. *Implicitly* through environment variables. This includes:
* [Using the in-cluster config](#in-cluster-config)
For a full list of supported provider authentication arguments and their corresponding environment variables, see the [argument reference](#argument-reference) below.
### File config
The easiest way is to supply a path to your kubeconfig file using the `config_path` attribute or using the `KUBE_CONFIG_PATH` environment variable. A kubeconfig file may have multiple contexts. If `config_context` is not specified, the provider will use the `default` context.
```hcl
```terraform
provider "helm" {
kubernetes {
config_path = "~/.kube/config"
@ -90,7 +88,7 @@ provider "helm" {
The provider also supports multiple paths in the same way that kubectl does using the `config_paths` attribute or `KUBE_CONFIG_PATHS` environment variable.
```hcl
```terraform
provider "helm" {
kubernetes {
config_paths = [
@ -105,7 +103,7 @@ provider "helm" {
You can also configure the host, basic auth credentials, and client certificate authentication explicitly or through environment variables.
```hcl
```terraform
provider "helm" {
kubernetes {
host = "https://cluster_endpoint:port"
@ -127,7 +125,7 @@ If you want to connect to a different cluster than the one terraform is running
Some cloud providers have short-lived authentication tokens that can expire relatively quickly. To ensure the Kubernetes provider is receiving valid credentials, an exec-based plugin can be used to fetch a new token before initializing the provider. For example, on EKS, the command `eks get-token` can be used:
```hcl
```terraform
provider "helm" {
kubernetes {
host = var.cluster_endpoint
@ -141,6 +139,23 @@ provider "helm" {
}
```
For example, to [authenticate with GKE](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/using_gke_with_terraform#using-the-kubernetes-and-helm-providers), the `gke-cloud-auth-plugin` can be used:
```terraform
provider "helm" {
kubernetes{
host = "https://${data.google_container_cluster.my_cluster.endpoint}"
token = data.google_client_config.provider.access_token
cluster_ca_certificate = base64decode(
data.google_container_cluster.my_cluster.master_auth[0].cluster_ca_certificate,)
exec {
api_version = "client.authentication.k8s.io/v1beta1"
command = "gke-gcloud-auth-plugin"
}
}
}
```
## Argument Reference
The following arguments are supported:
@ -150,8 +165,7 @@ The following arguments are supported:
* `registry_config_path` - (Optional) The path to the registry config file. Defaults to `HELM_REGISTRY_CONFIG` env if it is set, otherwise uses the default path set by helm.
* `repository_config_path` - (Optional) The path to the file containing repository names and URLs. Defaults to `HELM_REPOSITORY_CONFIG` env if it is set, otherwise uses the default path set by helm.
* `repository_cache` - (Optional) The path to the file containing cached repository indexes. Defaults to `HELM_REPOSITORY_CACHE` env if it is set, otherwise uses the default path set by helm.
* `helm_driver` - (Optional) "The backend storage driver. Valid values are: `configmap`, `secret`, `memory`, `sql`. Defaults to `secret`.
Note: Regarding the sql driver, as of helm v3.2.0 SQL support exists only for the postgres dialect. The connection string can be configured by setting the `HELM_DRIVER_SQL_CONNECTION_STRING` environment variable e.g. `HELM_DRIVER_SQL_CONNECTION_STRING=postgres://username:password@host/dbname` more info [here](https://pkg.go.dev/github.com/lib/pq).
* `helm_driver` - (Optional) "The backend storage driver. Valid values are: `configmap`, `secret`, `memory`, `sql`. Defaults to `secret`. Note: Regarding the sql driver, as of helm v3.2.0 SQL support exists only for the postgres dialect. The connection string can be configured by setting the `HELM_DRIVER_SQL_CONNECTION_STRING` environment variable e.g. `HELM_DRIVER_SQL_CONNECTION_STRING=postgres://username:password@host/dbname` more info [here](https://pkg.go.dev/github.com/lib/pq).
* `burst_limit` - (Optional) The helm burst limit to use. Set this value higher if your cluster has many CRDs. Default: `100`
* `kubernetes` - Kubernetes configuration block.
* `registry` - Private OCI registry configuration block. Can be specified multiple times.

333
docs/resources/release.md Normal file
View file

@ -0,0 +1,333 @@
---
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
- `cleanup_on_fail` (Boolean) Allow deletion of new resources created in this upgrade when upgrade fails
- `create_namespace` (Boolean) Create the namespace if it does not exist
- `dependency_update` (Boolean) Run helm dependency update before installing the chart
- `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
- `disable_webhooks` (Boolean) Prevent hooks from running.
- `force_update` (Boolean) Force resource update through delete/recreate if needed.
- `keyring` (String) Location of public keys used for verification. Used only if `verify` is true
- `lint` (Boolean) Run helm lint when planning
- `max_history` (Number) Limit the maximum number of revisions saved per release. Use 0 for no limit
- `namespace` (String) Namespace to install the release into.
- `pass_credentials` (Boolean) Pass credentials to all domains
- `postrender` (Block List, Max: 1) Postrender command configuration. (see [below for nested schema](#nestedblock--postrender))
- `recreate_pods` (Boolean) Perform pods restart during upgrade/rollback
- `render_subchart_notes` (Boolean) If set, render subchart notes along with the parent
- `replace` (Boolean) Re-use the given name, even if that name is already used. This is unsafe in production
- `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
- `reuse_values` (Boolean) When upgrading, reuse the last release's values and merge in any overrides. If 'reset_values' is specified, this is ignored
- `set` (Block Set) Custom values to be merged with the values. (see [below for nested schema](#nestedblock--set))
- `set_list` (Block List) Custom sensitive 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
- `timeout` (Number) Time in seconds to wait for any individual kubernetes operation.
- `values` (List of String) List of values in raw yaml format to pass to helm.
- `verify` (Boolean) Verify the package before installing it.
- `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.
- `wait_for_jobs` (Boolean) If wait is enabled, will wait until all Jobs have been completed before marking the release as successful.
### 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)
- `value` (String)
Optional:
- `type` (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)
- `name` (String)
- `namespace` (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"
values = [
"${file("values.yaml")}"
]
set {
name = "cluster.enabled"
value = "true"
}
set {
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"
}
# localhost registry with password protection
registry {
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) 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.
## 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.

37
examples/data-sources/template/example_1.tf Normal file
View file

@ -0,0 +1,37 @@
data "helm_template" "mariadb_instance" {
name = "mariadb-instance"
namespace = "default"
repository = "https://charts.helm.sh/stable"
chart = "mariadb"
version = "7.1.0"
set {
name = "service.port"
value = "13306"
}
set_sensitive {
name = "rootUser.password"
value = "s3cr3t!"
}
}
resource "local_file" "mariadb_manifests" {
for_each = data.helm_template.mariadb_instance.manifests
filename = "./${each.key}"
content = each.value
}
output "mariadb_instance_manifest" {
value = data.helm_template.mariadb_instance.manifest
}
output "mariadb_instance_manifests" {
value = data.helm_template.mariadb_instance.manifests
}
output "mariadb_instance_notes" {
value = data.helm_template.mariadb_instance.notes
}

42
examples/data-sources/template/example_2.tf Normal file
View file

@ -0,0 +1,42 @@
data "helm_template" "mariadb_instance" {
name = "mariadb-instance"
namespace = "default"
repository = "https://charts.helm.sh/stable"
chart = "mariadb"
version = "7.1.0"
show_only = [
"templates/master-statefulset.yaml",
"templates/master-svc.yaml",
]
set {
name = "service.port"
value = "13306"
}
set_sensitive {
name = "rootUser.password"
value = "s3cr3t!"
}
}
resource "local_file" "mariadb_manifests" {
for_each = data.helm_template.mariadb_instance.manifests
filename = "./${each.key}"
content = each.value
}
output "mariadb_instance_manifest" {
value = data.helm_template.mariadb_instance.manifest
}
output "mariadb_instance_manifests" {
value = data.helm_template.mariadb_instance.manifests
}
output "mariadb_instance_notes" {
value = data.helm_template.mariadb_instance.notes
}

31
examples/example_1.tf Normal file
View file

@ -0,0 +1,31 @@
provider "helm" {
kubernetes {
config_path = "~/.kube/config"
}
# localhost registry with password protection
registry {
url = "oci://localhost:5000"
username = "username"
password = "password"
}
# private registry
registry {
url = "oci://private.registry"
username = "username"
password = "password"
}
}
resource "helm_release" "nginx_ingress" {
name = "nginx-ingress-controller"
repository = "https://charts.bitnami.com/bitnami"
chart = "nginx-ingress-controller"
set {
name = "service.type"
value = "ClusterIP"
}
}

5
examples/example_2.tf Normal file
View file

@ -0,0 +1,5 @@
provider "helm" {
kubernetes {
config_path = "~/.kube/config"
}
}

8
examples/example_3.tf Normal file
View file

@ -0,0 +1,8 @@
provider "helm" {
kubernetes {
config_paths = [
"/path/to/config_a.yaml",
"/path/to/config_b.yaml"
]
}
}

9
examples/example_4.tf Normal file
View file

@ -0,0 +1,9 @@
provider "helm" {
kubernetes {
host = "https://cluster_endpoint:port"
client_certificate = file("~/.kube/client-cert.pem")
client_key = file("~/.kube/client-key.pem")
cluster_ca_certificate = file("~/.kube/cluster-ca-cert.pem")
}
}

11
examples/example_5.tf Normal file
View file

@ -0,0 +1,11 @@
provider "helm" {
kubernetes {
host = var.cluster_endpoint
cluster_ca_certificate = base64decode(var.cluster_ca_cert)
exec {
api_version = "client.authentication.k8s.io/v1beta1"
args = ["eks", "get-token", "--cluster-name", var.cluster_name]
command = "aws"
}
}
}

12
examples/example_6.tf Normal file
View file

@ -0,0 +1,12 @@
provider "helm" {
kubernetes{
host = "https://${data.google_container_cluster.my_cluster.endpoint}"
token = data.google_client_config.provider.access_token
cluster_ca_certificate = base64decode(
data.google_container_cluster.my_cluster.master_auth[0].cluster_ca_certificate,)
exec {
api_version = "client.authentication.k8s.io/v1beta1"
command = "gke-gcloud-auth-plugin"
}
}
}

26
examples/resources/release/example_1.tf Normal file
View file

@ -0,0 +1,26 @@
resource "helm_release" "example" {
name = "my-redis-release"
repository = "https://charts.bitnami.com/bitnami"
chart = "redis"
version = "6.0.1"
values = [
"${file("values.yaml")}"
]
set {
name = "cluster.enabled"
value = "true"
}
set {
name = "metrics.enabled"
value = "true"
}
set {
name = "service.annotations.prometheus\\.io/port"
value = "9127"
type = "string"
}
}

4
examples/resources/release/example_10.tf Normal file
View file

@ -0,0 +1,4 @@
controller:
pod:
annotations:
status.kubernetes.io/restart-on-failure: {"timeout": "30s"}

4
examples/resources/release/example_11.tf Normal file
View file

@ -0,0 +1,4 @@
set {
name = "controller.pod.annotations.status\\.kubernetes\\.io/restart-on-failure"
value = "\\{\"timeout\": \"30s\"\\}"
}

4
examples/resources/release/example_2.tf Normal file
View file

@ -0,0 +1,4 @@
resource "helm_release" "example" {
name = "my-local-chart"
chart = "./charts/example"
}

4
examples/resources/release/example_3.tf Normal file
View file

@ -0,0 +1,4 @@
resource "helm_release" "example" {
name = "redis"
chart = "https://charts.bitnami.com/bitnami/redis-10.7.16.tgz"
}

21
examples/resources/release/example_4.tf Normal file
View file

@ -0,0 +1,21 @@
provider "helm" {
kubernetes {
config_path = "~/.kube/config"
}
# localhost registry with password protection
registry {
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"
}

25
examples/resources/release/example_5.tf Normal file
View file

@ -0,0 +1,25 @@
# 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"
}

25
examples/resources/release/example_6.tf Normal file
View file

@ -0,0 +1,25 @@
# 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"
}

7
examples/resources/release/example_7.tf Normal file
View file

@ -0,0 +1,7 @@
# run this first: `helm repo add bitnami https://charts.bitnami.com/bitnami`
resource "helm_release" "example" {
name = "redis"
chart = "bitnami/redis"
}

4
examples/resources/release/example_8.tf Normal file
View file

@ -0,0 +1,4 @@
set {
name = "grafana.ingress.annotations.alb\\.ingress\\.kubernetes\\.io/group\\.name"
value = "shared-ingress"
}

4
examples/resources/release/example_9.tf Normal file
View file

@ -0,0 +1,4 @@
set_list {
name = "hashicorp"
value = ["terraform", "nomad", "vault"]
}

2
scripts/markdown-link-check.sh
View file

@ -35,7 +35,7 @@ ${DOCKER} run ${DOCKER_RUN_OPTS} --rm -t \
-w /github/workspace \
--entrypoint /usr/bin/find \
docker.io/robertbeal/markdown-link-checker \
website \( -type f -name "*.md" -or -name "*.markdown" \) -exec markdown-link-check --config .markdownlinkcheck.json --quiet --verbose {} \; \
docs/resources docs/data-sources \( -type f -name "*.md" -or -name "*.markdown" \) -exec markdown-link-check --config .markdownlinkcheck.json --quiet --verbose {} \; \
| tee -a "${output_file}"
touch "${error_file}"

31
templates/data-sources/template.md.tmpl Normal file
View file

@ -0,0 +1,31 @@
---
page_title: "helm: helm_template"
sidebar_current: "docs-helm-template"
description: |-
---
# Data Source: {{ .Name }}
Render chart templates locally.
`helm_template` renders chart templates locally and exposes the rendered manifests in the data source attributes. `helm_template` mimics the functionality of the `helm template` command.
The arguments aim to be identical to the `helm_release` resource.
For further details on the `helm template` command, refer to the [Helm documentation](https://helm.sh/docs/helm/helm_template/).
{{ .SchemaMarkdown }}
## Example Usage
### Render all chart templates
The following example renders all templates of the `mariadb` chart of the official Helm stable repository. Concatenated manifests are exposed as output variable `mariadb_instance_manifest`.
{{tffile "examples/data-sources/template/example_1.tf"}}
### Render selected chart templates
The following example renders only the templates `master-statefulset.yaml` and `master-svc.yaml` of the `mariadb` chart of the official Helm stable repository.
{{tffile "examples/data-sources/template/example_2.tf"}}

0
website/docs/guides/v2-upgrade-guide.markdown → templates/guides/v2-upgrade-guide.md
View file

126
templates/index.md.tmpl Normal file
View file

@ -0,0 +1,126 @@
---
page_title: "Provider: Helm"
sidebar_current: "docs-helm-index"
description: |-
The Helm provider is used to deploy software packages in Kubernetes. The provider needs to be configured with the proper credentials before it can be used.
---
{{/* This template serves as a starting point for documentation generation, and can be customized with hardcoded values and/or doc gen templates.
For example, the {{ .SchemaMarkdown }} template can be used to replace manual schema documentation if descriptions of schema attributes are added in the provider source code. */ -}}
# Helm Provider
The Helm provider is used to deploy software packages in Kubernetes. The provider needs to be configured with the proper credentials before it can be used.
Try the [hands-on tutorial](https://learn.hashicorp.com/tutorials/terraform/helm-provider?in=terraform/kubernetes) on the Helm provider on the HashiCorp Learn site.
## Resources
* [Resource: helm_release](r/release.md)
## Data Sources
* [Data Source: helm_template](d/template.html)
## Example Usage
{{tffile "examples/example_1.tf"}}
## Requirements
~> NOTE: The provider does not use the `KUBECONFIG` environment variable by default. See the attribute reference below for the environment variables that map to provider block attributes.
- You must have a Kubernetes cluster available. We support version 1.14.0 or higher.
## Authentication
The Helm provider can get its configuration in two ways:
1. *Explicitly* by supplying attributes to the provider block. This includes:
* [Using a kubeconfig file](#file-config)
* [Supplying credentials](#credentials-config)
* [Exec plugins](#exec-plugins)
2. *Implicitly* through environment variables. This includes:
* [Using the in-cluster config](#in-cluster-config)
For a full list of supported provider authentication arguments and their corresponding environment variables, see the [argument reference](#argument-reference) below.
### File config
The easiest way is to supply a path to your kubeconfig file using the `config_path` attribute or using the `KUBE_CONFIG_PATH` environment variable. A kubeconfig file may have multiple contexts. If `config_context` is not specified, the provider will use the `default` context.
{{tffile "examples/example_2.tf"}}
The provider also supports multiple paths in the same way that kubectl does using the `config_paths` attribute or `KUBE_CONFIG_PATHS` environment variable.
{{tffile "examples/example_3.tf"}}
### Credentials config
You can also configure the host, basic auth credentials, and client certificate authentication explicitly or through environment variables.
{{tffile "examples/example_4.tf"}}
### In-cluster Config
The provider uses the `KUBERNETES_SERVICE_HOST` and `KUBERNETES_SERVICE_PORT` environment variables to detect when it is running inside a cluster, so in this case you do not need to specify any attributes in the provider block if you want to connect to the local kubernetes cluster.
If you want to connect to a different cluster than the one terraform is running inside, configure the provider as [above](#credentials-config).
## Exec plugins
Some cloud providers have short-lived authentication tokens that can expire relatively quickly. To ensure the Kubernetes provider is receiving valid credentials, an exec-based plugin can be used to fetch a new token before initializing the provider. For example, on EKS, the command `eks get-token` can be used:
{{tffile "examples/example_5.tf"}}
For example, to [authenticate with GKE](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/using_gke_with_terraform#using-the-kubernetes-and-helm-providers), the `gke-cloud-auth-plugin` can be used:
{{tffile "examples/example_6.tf"}}
## Argument Reference
The following arguments are supported:
* `debug` - (Optional) - Debug indicates whether or not Helm is running in Debug mode. Defaults to `false`.
* `plugins_path` - (Optional) The path to the plugins directory. Defaults to `HELM_PLUGINS` env if it is set, otherwise uses the default path set by helm.
* `registry_config_path` - (Optional) The path to the registry config file. Defaults to `HELM_REGISTRY_CONFIG` env if it is set, otherwise uses the default path set by helm.
* `repository_config_path` - (Optional) The path to the file containing repository names and URLs. Defaults to `HELM_REPOSITORY_CONFIG` env if it is set, otherwise uses the default path set by helm.
* `repository_cache` - (Optional) The path to the file containing cached repository indexes. Defaults to `HELM_REPOSITORY_CACHE` env if it is set, otherwise uses the default path set by helm.
* `helm_driver` - (Optional) "The backend storage driver. Valid values are: `configmap`, `secret`, `memory`, `sql`. Defaults to `secret`. Note: Regarding the sql driver, as of helm v3.2.0 SQL support exists only for the postgres dialect. The connection string can be configured by setting the `HELM_DRIVER_SQL_CONNECTION_STRING` environment variable e.g. `HELM_DRIVER_SQL_CONNECTION_STRING=postgres://username:password@host/dbname` more info [here](https://pkg.go.dev/github.com/lib/pq).
* `burst_limit` - (Optional) The helm burst limit to use. Set this value higher if your cluster has many CRDs. Default: `100`
* `kubernetes` - Kubernetes configuration block.
* `registry` - Private OCI registry configuration block. Can be specified multiple times.
The `kubernetes` block supports:
* `config_path` - (Optional) Path to the kube config file. Can be sourced from `KUBE_CONFIG_PATH`.
* `config_paths` - (Optional) A list of paths to the kube config files. Can be sourced from `KUBE_CONFIG_PATHS`.
* `host` - (Optional) The hostname (in form of URI) of the Kubernetes API. Can be sourced from `KUBE_HOST`.
* `username` - (Optional) The username to use for HTTP basic authentication when accessing the Kubernetes API. Can be sourced from `KUBE_USER`.
* `password` - (Optional) The password to use for HTTP basic authentication when accessing the Kubernetes API. Can be sourced from `KUBE_PASSWORD`.
* `token` - (Optional) The bearer token to use for authentication when accessing the Kubernetes API. Can be sourced from `KUBE_TOKEN`.
* `insecure` - (Optional) Whether server should be accessed without verifying the TLS certificate. Can be sourced from `KUBE_INSECURE`.
* `tls_server_name` - (Optional) Server name passed to the server for SNI and is used in the client to check server certificates against. Can be sourced from `KUBE_TLS_SERVER_NAME`.
* `client_certificate` - (Optional) PEM-encoded client certificate for TLS authentication. Can be sourced from `KUBE_CLIENT_CERT_DATA`.
* `client_key` - (Optional) PEM-encoded client certificate key for TLS authentication. Can be sourced from `KUBE_CLIENT_KEY_DATA`.
* `cluster_ca_certificate` - (Optional) PEM-encoded root certificates bundle for TLS authentication. Can be sourced from `KUBE_CLUSTER_CA_CERT_DATA`.
* `config_context` - (Optional) Context to choose from the config file. Can be sourced from `KUBE_CTX`.
* `proxy_url` - (Optional) URL to the proxy to be used for all API requests. URLs with "http", "https", and "socks5" schemes are supported. Can be sourced from `KUBE_PROXY_URL`.
* `exec` - (Optional) Configuration block to use an [exec-based credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins), e.g. call an external command to receive user credentials.
* `api_version` - (Required) API version to use when decoding the ExecCredentials resource, e.g. `client.authentication.k8s.io/v1beta1`.
* `command` - (Required) Command to execute.
* `args` - (Optional) List of arguments to pass when executing the plugin.
* `env` - (Optional) Map of environment variables to set when executing the plugin.
The `registry` block has options:
* `url` - (Required) url to the registry in format `oci://host:port`
* `username` - (Required) username to registry
* `password` - (Required) password to registry
## Experiments
The provider takes an `experiments` block that allows you enable experimental features by setting them to `true`.
* `manifest` - Enable storing of the rendered manifest for `helm_release` so the full diff of what is changing can been seen in the plan.

82
templates/resources/release.md.tmpl Normal file
View file

@ -0,0 +1,82 @@
---
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`, `set_list`, 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` 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.
{{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.
## 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.

168
website/docs/d/template.html.markdown
View file

@ -1,168 +0,0 @@
---
layout: "helm"
page_title: "helm: helm_template"
sidebar_current: "docs-helm-template"
description: |-
---
# Data Source: helm_template
Render chart templates locally.
`helm_template` renders chart templates locally and exposes the rendered manifests in the data source attributes. `helm_template` mimics the functionality of the `helm template` command.
The arguments aim to be identical to the `helm_release` resource.
For further details on the `helm template` command, refer to the [Helm documentation](https://helm.sh/docs/helm/helm_template/).
## Example Usage
### Render all chart templates
The following example renders all templates of the `mariadb` chart of the official Helm stable repository. Concatenated manifests are exposed as output variable `mariadb_instance_manifest`.
```hcl
data "helm_template" "mariadb_instance" {
name = "mariadb-instance"
namespace = "default"
repository = "https://charts.helm.sh/stable"
chart = "mariadb"
version = "7.1.0"
set {
name = "service.port"
value = "13306"
}
set_sensitive {
name = "rootUser.password"
value = "s3cr3t!"
}
}
resource "local_file" "mariadb_manifests" {
for_each = data.helm_template.mariadb_instance.manifests
filename = "./${each.key}"
content = each.value
}
output "mariadb_instance_manifest" {
value = data.helm_template.mariadb_instance.manifest
}
output "mariadb_instance_manifests" {
value = data.helm_template.mariadb_instance.manifests
}
output "mariadb_instance_notes" {
value = data.helm_template.mariadb_instance.notes
}
```
### Render selected chart templates
The following example renders only the templates `master-statefulset.yaml` and `master-svc.yaml` of the `mariadb` chart of the official Helm stable repository.
```hcl
data "helm_template" "mariadb_instance" {
name = "mariadb-instance"
namespace = "default"
repository = "https://charts.helm.sh/stable"
chart = "mariadb"
version = "7.1.0"
show_only = [
"templates/master-statefulset.yaml",
"templates/master-svc.yaml",
]
set {
name = "service.port"
value = "13306"
}
set_sensitive {
name = "rootUser.password"
value = "s3cr3t!"
}
}
resource "local_file" "mariadb_manifests" {
for_each = data.helm_template.mariadb_instance.manifests
filename = "./${each.key}"
content = each.value
}
output "mariadb_instance_manifest" {
value = data.helm_template.mariadb_instance.manifest
}
output "mariadb_instance_manifests" {
value = data.helm_template.mariadb_instance.manifests
}
output "mariadb_instance_notes" {
value = data.helm_template.mariadb_instance.notes
}
```
## Argument Reference
The following arguments are supported:
* `name` - (Required) Release name.
* `chart` - (Required) Chart name to be rendered. The chart name can be local path, a URL to a chart, or the name of the chart if `repository` is specified. It is also possible to use the `<repository>/<chart>` format here if you are running Terraform on a system that the repository has been added to with `helm repo add` but this is not recommended.
* `repository` - (Optional) Repository URL where to locate the requested chart.
* `repository_key_file` - (Optional) The repositories cert key file
* `repository_cert_file` - (Optional) The repositories cert file
* `repository_ca_file` - (Optional) The Repositories CA File.
* `repository_username` - (Optional) Username for HTTP basic authentication against the repository.
* `repository_password` - (Optional) Password for HTTP basic authentication against the repository.
* `devel` - (Optional) Use chart development versions, too. Equivalent to version '>0.0.0-0'. If version is set, this is ignored.
* `version` - (Optional) Specify the exact chart version to install. If this is not specified, the latest version is installed. `helm_release` will not automatically grab the latest release, version must explicitly upgraded when upgrading an installed chart.
* `namespace` - (Optional) The namespace to install the release into. Defaults to `default`.
* `verify` - (Optional) Verify the package before installing it. Helm uses a provenance file to verify the integrity of the chart; this must be hosted alongside the chart. For more information see the [Helm Documentation](https://helm.sh/docs/topics/provenance/). Defaults to `false`.
* `keyring` - (Optional) Location of public keys used for verification. Used only if `verify` is true. Defaults to `/.gnupg/pubring.gpg` in the location set by `home`
* `timeout` - (Optional) Time in seconds to wait for any individual kubernetes operation (like Jobs for hooks). Defaults to `300` seconds.
* `disable_webhooks` - (Optional) Prevent hooks from running. Defaults to `false`.
* `reuse_values` - (Optional) When upgrading, reuse the last release's values and merge in any overrides. If 'reset_values' is specified, this is ignored. Defaults to `false`.
* `reset_values` - (Optional) When upgrading, reset the values to the ones built into the chart. Defaults to `false`.
* `atomic` - (Optional) If set, installation process purges chart on fail. The wait flag will be set automatically if atomic is used. Defaults to `false`.
* `skip_crds` - (Optional) If set, no CRDs will be installed. By default, CRDs are installed if not already present. Defaults to `false`.
* `skip_tests` - (Optional) If set, tests will not be rendered. By default, tests are rendered. Defaults to `false`.
* `render_subchart_notes` - (Optional) If set, render subchart notes along with the parent. Defaults to `true`.
* `disable_openapi_validation` - (Optional) If set, the installation process will not validate rendered templates against the Kubernetes OpenAPI Schema. Defaults to `false`.
* `wait` - (Optional) Will wait until all resources are in a ready state before marking the release as successful. It will wait for as long as `timeout`. Defaults to `true`.
* `values` - (Optional) List of values in raw yaml to pass to helm. Values will be merged, in order, as Helm does with multiple `-f` options.
* `set` - (Optional) Value block with custom values to be merged with the values yaml.
* `set_list` - (Optional) Value block with list of custom values to be merged with the values yaml.
* `set_sensitive` - (Optional) Value block with custom sensitive values to be merged with the values yaml that won't be exposed in the plan's diff.
* `set_string` - (Optional) Value block with custom STRING values to be merged with the values yaml.
* `dependency_update` - (Optional) Runs helm dependency update before installing the chart. Defaults to `false`.
* `replace` - (Optional) Re-use the given name, even if that name is already used. This is unsafe in production. Defaults to `false`.
* `description` - (Optional) Set release description attribute (visible in the history).
* `postrender` - (Optional) Configure a command to run after helm renders the manifest which can alter the manifest contents.
* `create_namespace` - (Optional) Create the namespace if it does not yet exist. Defaults to `false`.
The following attributes are specific to the `helm_template` data source and not available in the `helm_release` resource:
* `api_versions` - (Optional) List of Kubernetes api versions used for Capabilities.APIVersions.
* `include_crds` - (Optional) Include CRDs in the templated output. Defaults to `false`.
* `is_upgrade` - (Optional) Set .Release.IsUpgrade instead of .Release.IsInstall. Defaults to `false`.
* `show_only` - (Optional) Explicit list of chart templates to render, as Helm does with the `-s` or `--show-only` option. Paths to chart templates are relative to the root folder of the chart, e.g. `templates/deployment.yaml`. If not provided, all templates of the chart are rendered.
* `validate` - (Optional) Validate your manifests against the Kubernetes cluster you are currently pointing at. This is the same validation performed on an install. Defaults to `false`.
* `kube_version` - (Optional) Allows specifying a custom kubernetes version to use when templating.
## Attributes Reference
In addition to the arguments listed above, the following computed attributes are exported:
* `manifests` - Map of rendered chart templates indexed by the template name.
* `crds` - List of CRDs in the chart. Is empty unless `include_crds` is set to `true`.
* `manifest` - Concatenated rendered chart templates. This corresponds to the output of the `helm template` command.
* `notes` - Rendered notes if the chart contains a `NOTES.txt`.

284
website/docs/r/release.html.markdown
View file

@ -1,284 +0,0 @@
---
layout: "helm"
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.
## Example Usage - Chart Repository
```hcl
resource "helm_release" "example" {
name = "my-redis-release"
repository = "https://charts.bitnami.com/bitnami"
chart = "redis"
version = "6.0.1"
values = [
"${file("values.yaml")}"
]
set {
name = "cluster.enabled"
value = "true"
}
set {
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:
```hcl
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:
```hcl
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:
```hcl
provider "helm" {
kubernetes {
config_path = "~/.kube/config"
}
# localhost registry with password protection
registry {
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`
```hcl
# 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"
}
```
```hcl
# 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`
```hcl
# run this first: `helm repo add bitnami https://charts.bitnami.com/bitnami`
resource "helm_release" "example" {
name = "redis"
chart = "bitnami/redis"
}
```
## Argument Reference
The following arguments are supported:
* `name` - (Required) Release name. The length must not be longer than 53 characters.
* `chart` - (Required) Chart name to be installed. The chart name can be local path, a URL to a chart, or the name of the chart if `repository` is specified. It is also possible to use the `<repository>/<chart>` format here if you are running Terraform on a system that the repository has been added to with `helm repo add` but this is not recommended.
* `repository` - (Optional) Repository URL where to locate the requested chart.
* `repository_key_file` - (Optional) The repositories cert key file
* `repository_cert_file` - (Optional) The repositories cert file
* `repository_ca_file` - (Optional) The Repositories CA File.
* `repository_username` - (Optional) Username for HTTP basic authentication against the repository.
* `repository_password` - (Optional) Password for HTTP basic authentication against the repository.
* `devel` - (Optional) Use chart development versions, too. Equivalent to version '>0.0.0-0'. If version is set, this is ignored.
* `version` - (Optional) Specify the exact chart version to install. If this is not specified, the latest version is installed. `helm_release` will not automatically grab the latest release, version must explicitly upgraded when upgrading an installed chart.
* `namespace` - (Optional) The namespace to install the release into. Defaults to `default`.
* `verify` - (Optional) Verify the package before installing it. Helm uses a provenance file to verify the integrity of the chart; this must be hosted alongside the chart. For more information see the [Helm Documentation](https://helm.sh/docs/topics/provenance/). Defaults to `false`.
* `keyring` - (Optional) Location of public keys used for verification. Used only if `verify` is true. Defaults to `/.gnupg/pubring.gpg` in the location set by `home`
* `timeout` - (Optional) Time in seconds to wait for any individual kubernetes operation (like Jobs for hooks). Defaults to `300` seconds.
* `disable_webhooks` - (Optional) Prevent hooks from running. Defaults to `false`.
* `reuse_values` - (Optional) When upgrading, reuse the last release's values and merge in any overrides. If 'reset_values' is specified, this is ignored. Defaults to `false`.
* `reset_values` - (Optional) When upgrading, reset the values to the ones built into the chart. Defaults to `false`.
* `force_update` - (Optional) Force resource update through delete/recreate if needed. Defaults to `false`.
* `recreate_pods` - (Optional) Perform pods restart during upgrade/rollback. Defaults to `false`.
* `cleanup_on_fail` - (Optional) Allow deletion of new resources created in this upgrade when upgrade fails. Defaults to `false`.
* `max_history` - (Optional) Maximum number of release versions stored per release. Defaults to `0` (no limit).
* `atomic` - (Optional) If set, installation process purges chart on fail. The wait flag will be set automatically if atomic is used. Defaults to `false`.
* `skip_crds` - (Optional) If set, no CRDs will be installed. By default, CRDs are installed if not already present. Defaults to `false`.
* `render_subchart_notes` - (Optional) If set, render subchart notes along with the parent. Defaults to `true`.
* `disable_openapi_validation` - (Optional) If set, the installation process will not validate rendered templates against the Kubernetes OpenAPI Schema. Defaults to `false`.
* `wait` - (Optional) Will wait until all resources are in a ready state before marking the release as successful. It will wait for as long as `timeout`. Defaults to `true`.
* `wait_for_jobs` - (Optional) If wait is enabled, will wait until all Jobs have been completed before marking the release as successful. It will wait for as long as `timeout`. Defaults to false.
* `values` - (Optional) List of values in raw yaml to pass to helm. Values will be merged, in order, as Helm does with multiple `-f` options.
* `set` - (Optional) Value block with custom values to be merged with the values yaml.
* `set_list` - (Optional) Value block with list of custom values to be merged with the values yaml.
* `set_sensitive` - (Optional) Value block with custom sensitive values to be merged with the values yaml that won't be exposed in the plan's diff.
* `dependency_update` - (Optional) Runs helm dependency update before installing the chart. Defaults to `false`.
* `replace` - (Optional) Re-use the given name, only if that name is a deleted release which remains in the history. This is unsafe in production. Defaults to `false`.
* `description` - (Optional) Set release description attribute (visible in the history).
* `postrender` - (Optional) Configure a command to run after helm renders the manifest which can alter the manifest contents.
* `pass_credentials` - (Optional) Pass credentials to all domains. Defaults to `false`.
* `lint` - (Optional) Run the helm chart linter during the plan. Defaults to `false`.
* `create_namespace` - (Optional) Create the namespace if it does not yet exist. Defaults to `false`.
The `set`, `set_list`, 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` 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.
```hcl
set {
name = "grafana.ingress.annotations.alb\\.ingress\\.kubernetes\\.io/group\\.name"
value = "shared-ingress"
}
```
```hcl
set_list {
name = "hashicorp"
value = ["terraform", "nomad", "vault"]
}
```
```hcl
controller:
pod:
annotations:
status.kubernetes.io/restart-on-failure: {"timeout": "30s"}
```
```hcl
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.
## Attributes Reference
In addition to the arguments listed above, the following computed attributes are
exported:
* `manifest` - The rendered manifest of the release as JSON. Enable the `manifest` experiment to use this feature.
* `metadata` - Block status of the deployed release.
* `status` - Status of the release.
The `metadata` block supports:
* `chart` - The name of the chart.
* `name` - Name is the name of the release.
* `namespace` - Namespace is the kubernetes namespace of the release.
* `revision` - Version is an int32 which represents the version of the release.
* `version` - A SemVer 2 conformant version string of the chart.
* `app_version` - The version number of the application being deployed.
* `values` - The compounded values from `values` and `set*` attributes.
## 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.

36
website/helm.erb
View file

@ -1,36 +0,0 @@
<% wrap_layout :inner do %>
<% content_for :sidebar do %>
<div class="docs-sidebar hidden-print affix-top" role="complementary">
<ul class="nav docs-sidenav">
<li<%= sidebar_current("docs-home") %>>
<a href="/docs/providers/index.html">All Providers</a>
</li>
<li<%= sidebar_current("docs-helm-index") %>>
<a href="/docs/providers/helm/index.html">Helm Provider</a>
<ul class="nav nav-visible">
<li<%= sidebar_current("docs-helm-guide-v2-upgrade") %>>
<a href="/docs/providers/helm/guides/v2-upgrade-guide.html">v2 Upgrade Guide</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-helm-resource") %>>
<a href="#">Resources</a>
<ul class="nav nav-visible">
<li<%= sidebar_current("docs-helm-resource-release") %>>
<a href="/docs/providers/helm/r/release.html">helm_release</a>
</li>
<li<%= sidebar_current("docs-helm-template") %>>
<a href="/docs/providers/helm/d/template.html">helm_template</a>
</li>
</ul>
</li>
</ul>
</div>
<% end %>
<%= yield %>
<% end %>