TIL

ConfigMap

• 공식 문서 - ConfigMap
• 컨테이너 이미지와 설정 데이터를 분리해서 보관하는 API 객체 — 같은 이미지를 여러 환경(local·cloud)에서 다른 설정으로 돌릴 수 있게 함
• 기밀성·암호화 없음 — 비밀번호·토큰 같은 민감 데이터는 [[secret]] 사용
• 크기 제한 — 1 MiB 이하. 더 큰 설정은 volume·DB·파일 서비스로

사용 동기

• 같은 이미지를 다른 환경에서 다른 설정으로 실행 — 예: DATABASE_HOST를 로컬에선 localhost, 클라우드에선 K8s Service 이름으로
• 코드 변경 없이 환경별 설정을 분리 — 12-factor app의 “config” 원칙
• 대용량 데이터는 부적합 — 1 MiB 제한이 있어 대량 데이터엔 볼륨이나 별도 서비스를 써야 함

ConfigMap object

• 대부분의 K8s 객체와 달리 spec이 없고 — data와 binaryData 두 필드가 핵심
• 둘 다 optional, key-value pair 저장

필드	용도
data	UTF-8 문자열 key-value
binaryData	바이너리 데이터 — base64-encoded string
immutable	true로 설정 시 변경 불가 (v1.19+)

• 이름 규칙 — DNS subdomain name
• key 규칙 — 영숫자 + - _ . 만 허용. data와 binaryData의 key는 서로 겹치면 안 됨

apiVersion: v1
kind: ConfigMap
metadata:
  name: game-demo
data:
  # property 스타일 — 단일 값
  player_initial_lives: "3"
  ui_properties_file_name: "user-interface.properties"

  # file 스타일 — 멀티라인 내용
  game.properties: |
    enemy.types=aliens,monsters
    player.maximum-lives=5

• ConfigMap 자체는 단일 값 / 파일 스타일을 구분하지 않음 — 어떻게 소비할지(env vs file)는 Pod 쪽에서 결정

ConfigMap과 Pod

• Pod의 spec에서 ConfigMap을 참조해 컨테이너 설정에 주입
• 같은 namespace여야 함 — Pod과 ConfigMap이 서로 다른 ns이면 참조 불가
• static Pod의 spec은 ConfigMap을 비롯한 어떤 API 객체도 참조 불가
• Pod이 ConfigMap을 사용하는 4가지 방식

#	방식	처리 주체
1	컨테이너의 command / args 안에서 사용	kubelet (컨테이너 시작 시)
2	컨테이너의 환경 변수로 주입	kubelet
3	read-only volume으로 파일 마운트	kubelet
4	앱 코드가 Kubernetes API로 직접 조회	앱 자체

• 1–3은 kubelet이 Pod 시작 시점에 ConfigMap 값을 주입 — Pod이 재생성되지 않으면 1·2 값은 갱신되지 않음
• 4번 방식의 장점 — 앱이 ConfigMap 변경을 watch로 구독해 즉시 반응 가능, 다른 namespace의 ConfigMap도 접근 가능

Volume으로 마운트해 사용하기

• ConfigMap을 컨테이너 안에서 파일처럼 읽고 싶을 때 쓰는 방식
• 흐름 — Pod spec.volumes[]에 configMap.name으로 참조 + 컨테이너 volumeMounts[]로 마운트
• 각 key가 mountPath 아래 파일 이름으로, 값이 파일 내용으로 들어감
• volumeMounts[].readOnly = true 권장 (ConfigMap volume은 본래 read-only)
• items 배열을 지정하면 — 일부 key만 골라 마운트 가능. 생략하면 ConfigMap의 모든 key가 파일로 노출됨

spec:
  containers:
  - name: mypod
    image: redis
    volumeMounts:
    - name: foo
      mountPath: "/etc/foo"     # 여기에 ConfigMap key들이 파일로 생성됨
      readOnly: true
  volumes:
  - name: foo
    configMap:
      name: myconfigmap

• ConfigMap 1개는 .spec.volumes에 한 번만 선언하면 됨
• Pod에 컨테이너가 여러 개면 각 컨테이너마다 volumeMounts 블록을 따로 작성

Mounted ConfigMap 자동 갱신

• Volume으로 마운트된 ConfigMap의 key는 ConfigMap 변경 시 결국엔(eventually) 반영됨
• kubelet이 주기적 sync마다 마운트된 ConfigMap의 fresh 여부 확인 — 단, 로컬 캐시를 보고 판단
• 캐시 타입은 kubelet 설정의 configMapAndSecretChangeDetectionStrategy로 조절

캐시 타입	propagation delay
watch (default)	watch propagation delay
ttl-based	TTL 만큼
direct (매번 API server 조회)	0

• 총 전파 지연 = kubelet sync period + 캐시 전파 지연
• 예외 — subPath로 마운트한 컨테이너는 ConfigMap 업데이트를 받지 못함
• 환경 변수로 주입한 ConfigMap은 자동 갱신 안 됨 — Pod 재시작이 있어야 반영

환경 변수로 사용하기

• 두 가지 방식 — 개별 key 선택 vs 전체 key 일괄 주입

방식	필드	동작
개별 key	env[].valueFrom.configMapKeyRef	특정 key 1개를 골라 환경 변수에 매핑. 환경 변수 이름을 key와 다르게 줄 수 있음
전체 key	envFrom[].configMapRef	ConfigMap의 모든 key-value를 한 번에 환경 변수로 주입

# 개별 key 매핑 — CONFIGMAP_USERNAME 환경 변수에 username key 값 주입
env:
- name: CONFIGMAP_USERNAME
  valueFrom:
    configMapKeyRef:
      name: myconfigmap
      key: username

# 전체 key 일괄 주입
envFrom:
- configMapRef:
    name: myconfigmap

• 환경 변수 이름 규칙 제한 — Pod 환경 변수 이름에 허용되지 않는 문자가 key에 있으면 그 key는 컨테이너에 노출되지 않음. Pod 자체는 정상 시작됨 → 누락 가능성을 알아채기 어려우니 주의
• 환경 변수로 주입한 값은 Pod 재시작 없이는 갱신되지 않음

Immutable ConfigMap

• v1.21 stable. immutable: true를 설정하면 — data·binaryData 수정 불가, immutable 설정 자체도 되돌릴 수 없음
• 변경하려면 삭제 후 재생성해야 함. 기존 Pod은 삭제된 ConfigMap의 마운트 포인트를 유지하므로 Pod도 재생성 권장
• 도입 효과
  • 사고 방지 — 실수로 인한 변경으로 앱 outage가 나는 것을 막음
  • 성능 개선 — kube-apiserver가 immutable ConfigMap에 대한 watch를 닫아 부하 감소. ConfigMap–Pod 마운트가 수만 건 이상인 대규모 클러스터에서 의미 있는 효과

apiVersion: v1
kind: ConfigMap
metadata:
  name: myconfigmap
data:
  key: value
immutable: true