Terraform Helm Provider in Practice: Managing Charts with Terraform

Running Helm by hand or through ad-hoc CI scripts leaves gaps in value provenance, diff visibility, and rollback consistency. With Terraform's Helm Provider, you can manage Chart releases declaratively as part of your IaC.

This article focuses on stable features documented by HashiCorp, summarizing the design points you cannot skip in production operations and the angles certification exams tend to test.

Helm Provider Basics and the Big Picture

Terraform's Helm Provider integrates Helm CLI-equivalent operations into the Terraform plan/apply workflow and manages state through the helm_release resource. This makes diffs visible in plan and automates upgrades on apply.

Charts can be fetched from a repository URL or a local path. The provider uses Kubernetes API connection information (kubeconfig or explicit credentials) to run Helm install and upgrade operations.

Exam questions tend to target the core helm_release attributes (chart, version, namespace, values, set, atomic, wait, timeout, create_namespace, and so on) and how each one influences plan, apply, and rollback behavior.

• helm_release represents a single Helm release. Destroying it runs the equivalent of helm uninstall.
• plan detects differences in values/set. set_sensitive lets you keep secrets hidden while still participating in diff management.
• atomic=true auto-rolls back on upgrade failure. wait=true and timeout control the wait-for-stabilization behavior.

Terraform x Helm x Kubernetes flow

Minimal helm_release example

provider "helm" {
  kubernetes {
    config_path    = var.kubeconfig_path
    config_context = var.kube_context
  }
}

resource "helm_release" "nginx" {
  name             = "nginx"
  repository       = "https://charts.bitnami.com/bitnami"
  chart            = "nginx"
  version          = "15.0.0"
  namespace        = "web"
  create_namespace = true
  values           = [file("values-prod.yaml")]
  wait             = true
  timeout          = 600
  atomic           = true
}

Provider Configuration and Kubernetes Auth Options

The Helm Provider needs a Kubernetes connection under the hood. Typically you either reference a kubeconfig or explicitly specify host, token, and CA. In multi-cluster operations, the standard play is to set up provider aliases and pass them into modules.

In CI, prefer short-lived tokens (e.g. obtained via OIDC) passed through environment variables and kept out of state. A two-tier setup — kubeconfig locally, explicit credentials in CI — is also common in practice.

• When reading kubeconfig, use kubernetes { load_config_file=true } or specify config_path/context.
• Explicit specification is built on the trio of host/token/cluster_ca_certificate. Grant least-privilege RBAC.
• For multi-cluster setups, use aliases and inject them into modules via providers.

Typical connection patterns (default and alias)

# ローカル: kubeconfig を参照
provider "helm" {
  kubernetes {
    config_path    = var.kubeconfig_path
    config_context = var.kube_context
  }
}

# CI: 明示的に接続（別クラスタに alias で接続）
provider "helm" {
  alias = "eks"
  kubernetes {
    host                   = var.eks_api_endpoint
    token                  = var.eks_bearer_token
    cluster_ca_certificate = var.eks_cluster_ca
  }
}

# モジュール側では providers で注入
module "payments_release" {
  source    = "./modules/release"
  providers = { helm = helm.eks }
  # ... module inputs ...
}

Choosing Between values, set, and set_sensitive

Helm values are provided through values (an array of YAML file strings) and set (individual key=value overrides). In Terraform, diffs of these surface in plan and are propagated to upgrades on apply. For secrets, set_sensitive keeps the value out of plan output.

A maintainable design uses templated values files for the bulk of the configuration and keeps per-environment differences minimal with set. When you need to specify arrays explicitly, set_list is also an option.

• Use values for the overall shape, set for fine adjustments, and set_sensitive for secrets.
• values merges last-wins. Watch out for surprising behavior when overriding arrays.
• If you must keep secrets out of plan output, always use set_sensitive.

Practical example: combining values and set_sensitive

locals {
  values_file = templatefile("${path.module}/values-${var.env}.yaml", {
    image_tag = var.image_tag
  })
}

resource "helm_release" "app" {
  name       = "app"
  repository = var.chart_repository
  chart      = var.chart_name
  version    = var.chart_version
  namespace  = var.namespace

  values = [
    local.values_file
  ]

  set {
    name  = "replicaCount"
    value = tostring(var.replicas)
  }

  set_sensitive {
    name  = "secrets.DB_PASSWORD"
    value = var.db_password
  }

  wait    = true
  timeout = 900
  atomic  = true
}

Lifecycle and Drift Mitigation

Terraform keeps the desired state of helm_release in state and detects drift via plan. Running helm upgrade by hand causes drift that the next plan will surface. In operations, enforcing the principle that all changes go through Terraform minimizes drift.

Upgrade stability hinges on configuring wait=true and timeout appropriately. Enabling atomic=true triggers Helm's rollback on failure, avoiding half-applied states.

When taking an existing Helm release under Terraform management, use import. After importing, verify with plan that the resource declaration and the live release are aligned.

• Unify operational changes through Terraform and reserve manual helm for emergencies only.
• Balance stability and speed with the right combination of wait/timeout/atomic.
• After import, always verify that chart/version/values are consistent with the live release.

Flow for importing an existing release

# 1) 先にリソース宣言（最小）
resource "helm_release" "postgres" {
  name       = "postgres"
  namespace  = "data"
  repository = "https://charts.bitnami.com/bitnami"
  chart      = "postgresql"
}

# 2) 既存の Helm リリースを import（namespace/name 形式の ID を利用可能）
# terraform import helm_release.postgres data/postgres

# 3) chart/version/values を合わせ、plan で差分を確認して整合を取る

Modularization and CI/CD Integration

Confine per-environment differences to module inputs and values templates, and always pin Chart versions. That ensures reproducible plans and stable CI/CD applies.

For multi-cluster or multi-namespace setups, split modules per project and switch target clusters via provider aliases. Even when using workspaces, keep readability with an explicit var env.

• Pin Chart versions and review diffs via PR when bumping them.
• Pass environment names as explicit variables and absorb them in template rendering.
• In CI, persist plan as an artifact and review it before apply.

Module composition and provider alias injection

# ルート側
provider "helm" {
  alias = "prod"
  kubernetes {
    host                   = var.prod_host
    token                  = var.prod_token
    cluster_ca_certificate = var.prod_ca
  }
}

module "orders" {
  source    = "./modules/release"
  providers = { helm = helm.prod }

  name            = "orders"
  namespace       = "app"
  chart_repository= "oci://registry.example.com/helm"
  chart_name      = "orders"
  chart_version   = "1.2.3"
  env             = "prod"
}

# modules/release/main.tf（例）
resource "helm_release" "this" {
  name       = var.name
  namespace  = var.namespace
  repository = var.chart_repository
  chart      = var.chart_name
  version    = var.chart_version
  values     = [templatefile("${path.module}/values-${var.env}.yaml", {})]
  wait       = true
  timeout    = 900
  atomic     = true
}

Security and Secret Handling

Handle secret values by combining Terraform's sensitive variables with helm_release's set_sensitive. That minimizes exposure in plan/apply output and in state. Keep kubeconfigs and tokens out of the repository — pass them from short-lived sources for safety.

Follow the principle of least privilege for RBAC and scope permissions to the target namespace. When repository authentication is required, pass repository_username / repository_password and related parameters via variables.

• Combine var.sensitive=true with set_sensitive for secrets.
• Encrypt state and protect the backend (remote state plus access control).
• Use short-lived tokens in CI environment variables and suppress them in log output.

Safely passing in secrets

variable "db_password" {
  type      = string
  sensitive = true
}

resource "helm_release" "db" {
  name       = "db"
  repository = "https://charts.bitnami.com/bitnami"
  chart      = "postgresql"
  version    = "12.6.0"
  namespace  = "data"

  set_sensitive {
    name  = "global.postgresql.auth.postgresPassword"
    value = var.db_password
  }

  wait    = true
  timeout = 1200
  atomic  = true
}

Check Your Understanding

Frequently Asked Questions