Terraform + Kubernetes 운영

Terraform + Kubernetes 운영 심화: ConfigMap/Secret 변경 반영을 “예측 가능하게” 만드는 체크섬(Annotation) 패턴

운영에서 자주 터지는 유형이 있습니다. ConfigMap/Secret은 바뀌었는데 서비스 동작(특히 기능 플래그, 엔드포인트, 타임아웃 등)은 그대로인 상황입니다. 원인은 단순합니다. Kubernetes는 ConfigMap/Secret의 변경을 자동으로 Pod 재시작으로 연결하지 않기 때문입니다.

이 글은 Kubernetes 공식 문서의 동작 설명을 기준으로, Terraform로 관리하는 환경에서 ConfigMap/Secret 변경 → Deployment 롤링 업데이트를 자동화하는 실무 패턴을 정리합니다. (추정/허구 없이, 공식 문서에 있는 사실만 확정합니다.)

0) TL;DR (요약)

• ConfigMap을 env로 주입(env/envFrom)하면 자동 업데이트가 되지 않으며 Pod 재시작이 필요합니다. (Kubernetes 공식 문서 명시)
• ConfigMap을 volume으로 마운트하면 kubelet의 주기 sync/캐시 정책에 따라 eventually 파일이 갱신될 수 있습니다. (Kubernetes 공식 문서 명시)
• 운영에서 “항상 동일하게” 반영되게 하려면, ConfigMap/Secret 내용의 해시(checksum)를 Deployment Pod template annotation에 연결해 변경 시점에 롤링 업데이트가 일어나게 만드세요.

1) 문제 정의: “ConfigMap은 바뀌었는데 왜 서비스가 안 바뀌나?”

Kubernetes 공식 문서는 ConfigMap을 Pod에서 사용하는 방법을 4가지로 분류합니다(컨테이너 args, env, volume, API 직접 조회). 이 중 가장 많이 쓰는 방식이 env 및 volume인데, 둘의 업데이트 특성이 다릅니다.

1-1. env로 주입했을 때: 자동 업데이트되지 않음

Kubernetes ConfigMap 문서에는 다음이 명시되어 있습니다:

• “ConfigMaps consumed as environment variables are not updated automatically and require a pod restart.”

즉, env/envFrom로 넣은 값은 컨테이너(프로세스) 시작 시점에 확정됩니다. ConfigMap이 갱신되어도 기존 Pod는 그대로이며, 환경변수는 바뀌지 않습니다.

1-2. volume으로 마운트했을 때: eventually 업데이트(지연 가능)

같은 문서에는 volume으로 소비할 때의 갱신 특성도 설명합니다. 요지는 다음입니다:

• volume으로 소비 중인 ConfigMap이 업데이트되면 projected keys는 eventually 업데이트될 수 있음
• kubelet은 periodic sync 때 마운트된 ConfigMap이 최신인지 확인
• kubelet은 캐시를 사용하며, configMapAndSecretChangeDetectionStrategy에 따라 watch/ttl/direct 등 전략이 달라짐
• 결과적으로 지연은 kubelet sync period + cache propagation delay까지 커질 수 있음

운영 관점에서 중요한 포인트는 “언젠가 업데이트될 수 있다”이지 “즉시/항상 업데이트된다”가 아닙니다. 특히 애플리케이션이 파일을 읽는 타이밍/캐시 방식에 따라 체감은 더 달라집니다.

2) 실무 해법: ConfigMap/Secret 변경을 Deployment 롤링 업데이트로 “승격”시키기

Deployment는 PodTemplateSpec이 변경되면 새로운 ReplicaSet을 만들고, 롤링 업데이트로 Pod를 교체합니다(Deployment 컨트롤러 동작). 따라서 ConfigMap/Secret 변경을 Pod template 변경으로 연결하면, “설정 변경이 곧 롤링 업데이트”라는 예측 가능한 운영 루틴이 됩니다.

2-1. 체크섬(annotation) 패턴이 작동하는 이유

• ConfigMap/Secret의 data가 바뀐다
• Terraform이 sha256(jsonencode(...)) 등으로 내용을 해시한다
• 해시 값을 Deployment .spec.template.metadata.annotations에 넣는다
• annotation이 바뀌면 Pod template이 바뀌고, Deployment 컨트롤러가 새 ReplicaSet을 만든다
• 롤링 업데이트로 Pod가 교체되며, 새 Pod는 시작 시 최신 env/volume을 읽는다

Terraform의 sha256 함수는 문자열을 UTF-8로 인코딩 후 SHA-256을 적용하고 hex로 반환한다고 문서화되어 있습니다. 또한 jsonencode는 값을 JSON 문법으로 인코딩한다고 문서화되어 있습니다. (HashiCorp 공식 문서)

2-2. Terraform 예시: ConfigMap 데이터 해시를 Deployment annotation으로 연결

resource "kubernetes_config_map_v1" "app_config" {
  metadata {
    name      = "app-config"
    namespace = "prod"
  }

  data = {
    FEATURE_X_ENABLED = "true"
    API_BASE_URL      = "https://api.example.com"
  }
}

resource "kubernetes_deployment_v1" "app" {
  metadata {
    name      = "app"
    namespace = "prod"
  }

  spec {
    replicas = 3

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

    template {
      metadata {
        labels = {
          app = "app"
        }

        annotations = {
          config_checksum = sha256(jsonencode(kubernetes_config_map_v1.app_config.data))
        }
      }

      spec {
        container {
          name  = "app"
          image = "ghcr.io/example/app:1.0.0"

          env_from {
            config_map_ref {
              name = kubernetes_config_map_v1.app_config.metadata[0].name
            }
          }
        }
      }
    }
  }
}

3) 운영 의사결정 표 (env/volume/체크섬)

4) 장애 재현 및 복구 Runbook

4-1. 재현(예: envFrom 사용 중)

# 1) 현재 Pod가 보는 값 확인
kubectl -n prod exec deploy/app -- printenv FEATURE_X_ENABLED

# 2) ConfigMap 변경
kubectl -n prod patch configmap app-config 
  --type merge 
  -p '{"data":{"FEATURE_X_ENABLED":"false"}}'

# 3) 동일 Pod에서 재확인(값이 그대로면 “문제”가 재현된 것)
kubectl -n prod exec deploy/app -- printenv FEATURE_X_ENABLED

4-2. 즉시 복구(응급): 롤아웃 재시작

kubectl -n prod rollout restart deploy/app
kubectl -n prod rollout status deploy/app

4-3. 근본 대책: 체크섬 패턴 적용

• Terraform에서 ConfigMap/Secret 내용 해시를 Deployment annotation으로 연결
• 설정 변경은 Terraform 단일 경로로만 수행(드리프트 방지)
• 배포 후 kubectl rollout status로 완료 자동 확인

5) 체크리스트 (운영 표준화)

• ConfigMap/Secret 변경이 반드시 Terraform PR/Apply로만 일어나도록 통제
• Deployment .spec.template.metadata.annotations에 checksum이 실제로 들어가는지 확인
• 설정 변경이 잦은 서비스는 “사소한 변경도 롤링”이 허용되는지(릴리즈 정책) 합의
• 긴급 대응 절차에 rollout restart + rollout status 포함

6) 공식 원문 링크(근거)

• Kubernetes ConfigMap (Mounted ConfigMaps are updated automatically / env는 자동 업데이트 안 됨)
• Configure a Pod to Use a ConfigMap
• Kubernetes Deployment (Pod template 변경과 롤아웃)
• Terraform sha256 function
• Terraform jsonencode function

결론: 운영에서 설정 변경이 항상 반영되게 하려면, “ConfigMap이 바뀌면 Pod가 바뀐다”를 시스템적으로 보장해야 합니다. 체크섬(annotation) 패턴은 Kubernetes/Deployment의 선언적 업데이트 모델과 가장 잘 맞는 기본 해법입니다.