Terraform Kubernetes Provider: YAMLとの関係と制限を正しく理解する

Kubernetesの運用では、既存のYAML資産とTerraformのHCLによる一貫管理の両立がよく課題になります。本稿では、Terraform Kubernetes ProviderにおけるYAMLとの関係、実務での制限、そして試験で問われやすい判断ポイントをまとめます。

前提として、TerraformはKubernetes APIに対しCRUDを行うツールであり、kubectl applyの挙動（特にサーバーサイド適用のフィールド所有や競合解決）と同一ではありません。公式の安定仕様と一般的なパターンを中心に、バージョン差異が影響しやすい点は注意書きに留めます。

TerraformとYAMLの位置づけ

TerraformはHCLで記述したリソースをプロバイダ経由でKubernetes APIに反映します。一方、kube yamlはkubectl等のクライアントから適用されます。HelmはYAMLテンプレートをレンダリングし、最終的にはKubernetes APIにYAML（もしくは同等のJSON）を流し込みます。

つまり、最終的に到達する先は同じでも、経路と状態管理の思想が異なります。Terraformは状態管理と計画（plan）に強みがあり、kubectl/HelmはKubernetesの文脈での適用柔軟性に強みがあります。

• HCLで型付きリソースを使う: YAML不要。Terraformの計画と状態管理を最大限活用。
• YAMLを取り込む: yamldecodeで読んでマニフェスト系リソースに渡す（プロバイダの機能差は要確認）。
• Helmを使う: values.yamlを渡し、Chartでまとまった配布物を管理。

Kubernetesへの適用経路（概念）

最小構成のKubernetesプロバイダ（kubeconfigを利用）

terraform {
  required_providers {
    kubernetes = {
      source  = "hashicorp/kubernetes"
      version = ">= 2.0"
    }
  }
}

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

variable "kubeconfig_path" { type = string }
variable "kube_context" { type = string }

型付きリソースの利点と制限

Kubernetes Providerの型付きリソース（例: kubernetes_deployment_v1, kubernetes_service_v1）は、スキーマに沿った事前検証が効き、plan時点での差分可視化が明瞭です。Terraformの参照やfor_eachとの相性も良く、資格試験でも基本パターンとして押さえるべきです。

一方で、すべてのKubernetes APIやCRDが型付きでカバーされるわけではありません。Admission/Mutating Webhookやコントローラによるサーバー側のデフォルト付与・書き換えにより、Terraformが意図しない差分を検出する場合があります。特に、Podテンプレートの注釈やサイドカー自動注入などはplanで毎回差分になりがちです。その場合は、Terraformのlifecycle.ignore_changesで特定フィールドを無視する運用が一般的です。

• 同一オブジェクトをTerraformとkubectl/他ツールで“併用管理”しない（ドリフトの主因）。
• Admission/Mutatingで変わる可能性がある注釈やフィールドはignore_changesで緩和。
• 順序依存するリソース（CRD→CRなど）はdepends_onや分割適用で制御。
• リストの順序が差分要因にならないよう、可能ならset型や安定化したソートを利用。

DeploymentをHCLで管理し、注釈差分を抑制する例

resource "kubernetes_deployment_v1" "web" {
  metadata {
    name      = "web"
    namespace = "default"
    labels = { app = "web" }
    # Admissionやコントローラで変わりやすい注釈は無視
    annotations = { managed-by = "terraform" }
  }

  spec {
    replicas = 2

    selector { match_labels = { app = "web" } }

    template {
      metadata {
        labels = { app = "web" }
        annotations = { sidecar.istio.io/inject = "false" }
      }
      spec {
        container {
          name  = "nginx"
          image = "nginx:1.25"
          port { container_port = 80 }
        }
      }
    }
  }

  lifecycle {
    ignore_changes = [
      metadata[0].annotations,
      spec[0].template[0].metadata[0].annotations
    ]
  }
}

YAMLを直接扱うときの実装パターン

既存のYAMLをそのまま適用したい場合、Terraformのyamldecode関数でHCLのオブジェクトに変換し、汎用マニフェスト系のリソース（例: kubernetes_manifest など、提供可否や名称はプロバイダのバージョンに依存）に渡す方法があります。この方法はCRDや型未対応のAPIにも適用できるため、現実的な落としどころです。

注意点として、YAMLのマルチドキュメントを一括適用する際は分割し、for_eachで安定キー（kind/name/namespace）を付けて管理します。また、CRDとCRは明示的に順序制御（depends_on）してください。

• 単一YAMLはyamldecode(file(path))でオブジェクト化して渡す。
• 複数YAMLはfilesetで集めfor_eachで安定キー管理。
• CRD→CRはdepends_onで順序を保証。
• プロバイダの提供有無・挙動はドキュメントで確認（バージョン差異に注意）。

YAMLを読み込み、汎用マニフェストに渡す（単一ドキュメント）

locals {
  deploy = yamldecode(file("${path.module}/manifests/deploy.yaml"))
}

# プロバイダが提供する汎用マニフェスト系リソース名はバージョンで異なる場合があります
resource "kubernetes_manifest" "deploy" {
  manifest = local.deploy
}

Helm経由のYAMLとTerraform

Helm Providerのhelm_releaseは、Chartの配布物をTerraformのライフサイクルで管理します。values.yamlはそのまま文字列として渡すか、HCLからyamlencodeで生成して渡せます。ChartがCRDを含む場合、CR適用の前にCRDが存在するよう順序を設計します。

helm_releaseはKubernetesオブジェクトを個別リソースとしてTerraform状態に保持するのではなく、リリース単位での管理になります。個々のオブジェクト単位の詳細な差分管理が必要なら、Helmとマニフェスト系リソースを役割分担する設計が適しています。

• valuesはfile("values.yaml")またはyamlencode({ ... })で渡す。
• CRDを含むChartは、CRを適用する他リソースより前にapply（depends_onなど）。
• Chartアップグレード時の破壊的変更はplanで検知しづらい場合があるため慎重に。

helm_releaseでChartを適用し、values.yamlを渡す

terraform {
  required_providers {
    helm = {
      source  = "hashicorp/helm"
      version = ">= 2.9"
    }
    kubernetes = {
      source  = "hashicorp/kubernetes"
      version = ">= 2.0"
    }
  }
}

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"
  namespace  = "web"
  create_namespace = true

  values = [file("${path.module}/values.yaml")]
}

サーバー側のデフォルト・ドリフトの扱い

Kubernetes APIサーバーや各種コントローラは、受け取ったオブジェクトにデフォルト値を付与したり、注釈やフィールドを書き換えます。kubectl apply（特にサーバーサイド適用）とTerraformの適用はフィールド所有や競合解決の挙動が異なるため、混在運用はドリフトの原因になります。基本はどちらかに統一し、やむを得ず併用する場合も責務分離を明確にしてください。

CRDとCRの整合性、イベントチュアルコンシステンシ（適用直後に参照すると未反映のことがある）、リスト順序や生成フィールドの差分は、Terraformのdepends_on、time_sleep（必要な場合）、ignore_changes、for_eachの安定キー化などで抑制します。

• 同一オブジェクトの多元管理を避ける（Terraformかkubectl/Helmかを決める）。
• 生成・変異される注釈やstatusは管理対象にしない（ignore_changes等）。
• CRD→CRは明示的に順序制御。適用直後の参照はリトライ設計。
• リスト順序の不安定差分はキー化やソートで回避。

CRD→CRの順序保証（HelmでCRD、YAMLでCRを適用）

locals {
  cr_files = fileset("${path.module}/crs", "*.yaml")
  cr_objs  = [for f in local.cr_files : yamldecode(file("${path.module}/crs/${f}"))]
  cr_map   = { for m in local.cr_objs : "${m["kind"]}/${m["metadata"]["namespace"]}/${m["metadata"]["name"]}" => m }
}

# 例: CRDを含むChart
resource "helm_release" "crds" {
  name       = "operator-crds"
  repository = var.operator_repo
  chart      = var.operator_crd_chart
  namespace  = "operators"
}

# CRをYAMLから適用（汎用マニフェスト系リソース想定）
resource "kubernetes_manifest" "cr" {
  for_each = local.cr_map
  manifest = each.value
  depends_on = [helm_release.crds]
}

variable "operator_repo" { type = string }
variable "operator_crd_chart" { type = string }

試験と実務で押さえる要点と比較

Associate/Pro試験では、HCLでの型付き管理・YAML取り込み・Helmの使い分け、そしてドリフト抑制の判断が頻出です。実務でも、CRDや既存YAML資産との共存、Secretの取り扱い、順序制御が成功の鍵になります。

以下の比較表で、アプローチごとの特徴を整理します。

• yamldecode/yamlencode、file/fileset、for_each・depends_onの基本を確実に。
• SecretはTerraform状態に平文で残り得る。外部シークレット管理（例: Vault、External Secrets等）や暗号化されたリモートバックエンドを検討。
• 同一リソースを複数ツールで変更しない。変更責務を分離。

マルチドキュメントYAMLを分割してfor_each適用するスニペット

locals {
  # --- 区切りで分割（改行を含む区切りを考慮）。空要素は除外
  raw  = file("${path.module}/bundle.yaml")
  docs = [for d in split("\n---\n", local.raw) : d if trimspace(d) != ""]
  objs = [for d in local.docs : yamldecode(d)]
  mp   = { for m in local.objs : "${m["kind"]}/${coalesce(try(m["metadata"]["namespace"], null), "default")}/${m["metadata"]["name"]}" => m }
}

resource "kubernetes_manifest" "multi" {
  for_each = local.mp
  manifest = each.value
}

問題で確認

よくある質問