Terraform Helm Provider 実践ガイド: Chart を Terraform で管理する

Helm を手運用やCIスクリプトで流すだけだと、値の出自や差分の可視化、ロールバックの一貫性に課題が残ります。Terraform の Helm Provider を使えば、Chart のリリースを IaC の一部として宣言的に管理できます。

本稿は HashiCorp 公式ドキュメントに基づく安定機能を中心に、プロダクション運用で外せない設計ポイントと、認定試験で問われやすい観点をまとめます。

Helm Provider の基本と全体像

Terraform の Helm Provider は、Helm CLI 相当の操作を Terraform の計画・適用フローに組み込み、helm_release リソースとして状態管理します。これにより、plan で差分を可視化し、apply でアップグレードを自動化できます。

Chart の取得元はリポジトリ URL もしくはローカルパスを指定できます。Provider は Kubernetes API への接続情報（kubeconfig または明示的な認証情報）を使って、Helm のインストールやアップグレードを実行します。

試験で狙われやすいのは、helm_release の主要属性（chart、version、namespace、values、set、atomic、wait、timeout、create_namespace など）と、それらが計画・適用・ロールバックにどう影響するかです。

• helm_release は単一の Helm リリースを表す。削除すれば helm uninstall 相当が走る。
• plan では values/set の差分が検出される。set_sensitive は機微情報を伏せたまま差分管理が可能。
• atomic=true はアップグレード失敗時に自動ロールバック。wait=true と timeout は安定化待ちの挙動を制御。

Terraform × Helm × Kubernetes の流れ

最小の helm_release 例

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 設定と Kubernetes 認証の選択肢

Helm Provider は内部で Kubernetes への接続を必要とします。一般的には kubeconfig を参照するか、明示的に host・token・CA を指定します。マルチクラスタ運用では provider の alias を用意し、モジュールに渡して使い分けるのが定石です。

CI では短命トークン（OIDC 経由の取得など）を環境変数から渡し、state には残さない運用が望まれます。手元では kubeconfig を読み、CI では明示指定という二層構えも実務でよく使われます。

• kubeconfig を読む場合は kubernetes { load_config_file=true } または config_path/context を指定。
• 明示指定は host/token/cluster_ca_certificate の三点セットが基本。RBAC は最小権限を付与。
• マルチクラスタは alias 化して providers でモジュールへ注入。

代表的な接続パターン（デフォルトと 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 ...
}

values・set・set_sensitive の使い分け

Helm の値は values（YAML ファイル文字列の配列）と set（個別 key=value 指定）で与えられます。Terraform ではこれらの差分が plan に現れ、apply で Upgrade に反映されます。機微情報は set_sensitive を使うと plan 出力に値を出さずに管理できます。

大きな構成はテンプレート化した values ファイルを使い、環境ごとの差分は set で最小限にするのが保守しやすい設計です。配列を明示する場合は set_list を使う選択肢もあります。

• 大枠は values、微調整は set、秘密は set_sensitive。
• values は後勝ちマージ。配列の上書きは意図せぬ挙動に注意。
• plan 出力に秘密を出したくない場合は必ず set_sensitive。

実践例: values と 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
}

ライフサイクルとドリフト対策

Terraform は helm_release の所望状態を state に保持し、plan で差分を検出します。手動で helm upgrade を実行するとドリフトが発生し、次の plan で差分として検知されます。運用では「変更は Terraform 経由」の原則を徹底するとドリフトを最小化できます。

アップグレードの安定性は wait=true と timeout の適切な設定が鍵です。atomic=true を有効にすると、失敗時に Helm のロールバックが走り、中途半端な状態を避けられます。

既存の Helm リリースを Terraform 管理に取り込む場合は import を使います。取り込み後はリソース宣言と実体の乖離がないか plan で確認します。

• 運用変更は Terraform 経由に統一し、手動 helm は緊急時のみに限定。
• wait/timeout/atomic の組み合わせで安定化と速さのバランスを取る。
• import 後は chart/version/values の整合を必ず検証。

既存リリースの取り込み（import）の流れ

# 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 で差分を確認して整合を取る

モジュール化と CI/CD への組み込み

環境差分はモジュール入力と values テンプレートに閉じ込め、Chart バージョンは必ずピン留めします。これにより、plan の再現性が担保され、CI/CD での apply が安定します。

マルチクラスタ/マルチ名前空間は、プロジェクト単位でモジュールを分け、provider alias で対象クラスタを切り替えます。Workspace を使う場合でも、明示的な var env で可読性を確保しましょう。

• Chart 版は固定し、上げるときは PR で差分をレビュー。
• 環境名は明示的な変数で渡し、テンプレートのレンダリングで吸収。
• CI では plan をアーティファクト化し、apply 前にレビュー。

モジュール構成と provider alias の注入

# ルート側
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
}

セキュリティと秘密情報の扱い

秘密値は Terraform の sensitive 変数と helm_release の set_sensitive を組み合わせて扱います。これにより plan/apply の出力や state での露出を最小化できます。また、kubeconfig やトークンはリポジトリに置かず、短命な発行源から渡すのが安全です。

RBAC は最小権限の原則で、対象名前空間の操作権限に限定します。リポジトリの認証が必要な場合は、repository_username / repository_password などの認証パラメータを変数経由で渡します。

• 機微情報は var.sensitive=true と set_sensitive の併用。
• state の暗号化とバックエンド保護（リモート State + アクセス制御）。
• CI の環境変数は短命トークンを用い、ログ出力を抑制。

機微情報の安全な受け渡し

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
}

問題で確認

よくある質問