ConfigMap을 수정했는데 설정이 그대로라면 먼저 Pod가 값을 받는 방식을 확인해야 합니다. 환경변수는 자동 갱신되지 않아 Pod 재시작이 필요하고, 일반 ConfigMap 볼륨은 지연 후 갱신됩니다. 반면 subPath로 마운트한 파일은 ConfigMap 변경을 전달받지 않습니다.
같은 ConfigMap도 사용 방식에 따라 반영 시점이 다릅니다
ConfigMap 객체의 값이 바뀌었다는 사실과 실행 중인 컨테이너가 새 값을 사용한다는 사실은 별개입니다. 다음 표로 기다릴 상황과 Pod를 다시 시작해야 할 상황을 먼저 나눌 수 있습니다.
| 사용 방식 | 기존 Pod의 자동 갱신 | 확인할 사항 |
|---|---|---|
| env 또는 envFrom 환경변수 | 갱신되지 않음 | 참조 이름·키와 Pod 재시작 여부 |
| subPath 없는 ConfigMap 볼륨 | 지연 후 파일 갱신 | 파일 내용, kubelet 동기화와 캐시 전파 지연 |
| subPath를 지정한 ConfigMap 마운트 | 변경을 전달받지 않음 | volumeMounts의 subPath와 Pod 재생성 여부 |
일반 볼륨도 즉시 바뀌는 것은 아닙니다. kubelet은 주기적으로 동기화하면서 ConfigMap의 최신 상태를 확인하며, 캐시를 통해 값을 얻습니다. 반영 지연은 kubelet 동기화 주기와 캐시 전파 지연의 영향을 받으므로 모든 클러스터에 동일한 대기 시간을 적용할 수 없습니다.
ConfigMap 값부터 실제 Pod의 참조 경로까지 확인하기
kubectl로 대상 클러스터에 접근할 수 있고, 해당 네임스페이스의 ConfigMap과 Pod를 조회할 권한이 있어야 합니다. 아래 이름은 예시이므로 실제 네임스페이스, Pod, ConfigMap 이름으로 바꿉니다.
kubectl get configmap app-settings -n demo -o yaml
kubectl get pod settings-demo -n demo -o yaml
kubectl describe pod settings-demo -n demo- ConfigMap의 data에 원하는 값이 저장되어 있는지 확인합니다. 조회한 객체 자체가 이전 값이면 컨테이너 반영 문제를 조사하기 전에 수정 대상부터 확인합니다.
- 실제 Pod의 env[].valueFrom.configMapKeyRef 또는 envFrom[].configMapRef가 같은 ConfigMap을 참조하는지 확인합니다. 개별 키를 선택했다면 key도 대조합니다.
- 파일로 사용한다면 volumes[].configMap.name과 컨테이너의 volumeMounts[].name을 연결해 봅니다. items가 있으면 key와 path 매핑도 확인합니다.
- 해당 volumeMounts에 subPath가 있는지 확인합니다. 파일 하나만 마운트했다는 외형보다 이 필드의 존재가 판단 기준입니다.
일반적인 Pod 참조에서는 ConfigMap과 Pod가 같은 네임스페이스에 있어야 합니다. 여러 컨테이너가 있는 Pod라면 설정을 사용하는 컨테이너의 env와 volumeMounts를 확인해야 합니다. describe 출력은 마운트와 시작 상태를 살피는 데 유용하지만, 그것만으로 컨테이너 내부 파일이 새 값인지 확인할 수는 없습니다.
예시: 같은 키를 세 방식으로 읽었을 때의 차이
다음은 참조 구조를 비교하기 위한 Pod 명세 일부이며, 단독으로 적용하는 완전한 매니페스트는 아닙니다. demo 네임스페이스에 변경 가능한 app-settings ConfigMap이 있고, MODE 키가 처음에는 blue라고 가정합니다. 컨테이너 app은 실행 중이며 printenv와 cat 명령을 포함해야 합니다.
env:
- name: APP_MODE
valueFrom:
configMapKeyRef:
name: app-settings
key: MODE
volumeMounts:
- name: settings
mountPath: /config
readOnly: true
- name: settings
mountPath: /single-mode
subPath: MODE
readOnly: true
# 아래 volumes는 컨테이너 내부가 아닌 Pod spec 아래에 배치
volumes:
- name: settings
configMap:
name: app-settingsitems를 생략했으므로 MODE 키는 일반 볼륨에서 /config/MODE 파일이 됩니다. 같은 볼륨의 MODE 파일을 subPath로 선택한 경로는 /single-mode입니다. 이 Pod가 시작된 뒤 ConfigMap의 MODE를 green으로 수정했다면, 다음처럼 각 경로를 따로 조회합니다. 컨테이너 명령 실행 권한도 필요합니다.
kubectl get configmap app-settings -n demo -o yaml
kubectl exec settings-demo -n demo -c app -- printenv APP_MODE
kubectl exec settings-demo -n demo -c app -- cat /config/MODE
kubectl exec settings-demo -n demo -c app -- cat /single-mode아래는 실제 실행 결과가 아니라, 변경 후 기존 Pod에서 기대할 수 있는 해석입니다.
| 관찰 대상 | 예상 값 | 해석 |
|---|---|---|
| ConfigMap의 data.MODE | green | 수정한 값이 API 객체에 저장됨 |
| APP_MODE | blue | 환경변수는 기존 Pod에서 자동으로 바뀌지 않음 |
| /config/MODE | 처음에는 blue일 수 있으며, 갱신 후 green | 일반 볼륨에는 전파 지연이 있음 |
| /single-mode | blue | subPath 마운트는 변경을 전달받지 않음 |
환경변수와 subPath에 새 값을 반영하려면 업데이트된 ConfigMap을 참조하도록 Pod를 다시 생성하는 방식으로 재시작합니다. 운영 환경에서는 해당 Pod를 관리하는 워크로드의 배포 절차에 맞춰 진행하고, 새 Pod에서도 참조 설정과 값을 다시 확인합니다.
파일 갱신과 애플리케이션 설정 적용을 구분하기
/config/MODE가 green으로 바뀌었는데 서비스 동작이 그대로라면, 다음 확인 대상은 애플리케이션이 파일을 읽는 방식입니다. Kubernetes가 볼륨 파일을 갱신하는 것만으로 애플리케이션의 재읽기까지 보장되지는 않습니다. 시작할 때만 설정을 읽는 프로그램이라면 그 프로그램에 맞는 재로딩 또는 재시작 절차가 필요합니다.
- 일반 볼륨의 이전 값을 한 번 확인한 것만으로 갱신 실패라고 단정하지 않습니다. 지연을 고려해 동일한 파일을 다시 읽고, 계속 그대로라면 참조 이름·키·경로를 재확인합니다.
- subPath는 오래 기다려도 일반 볼륨처럼 갱신되지 않습니다. 자동 파일 갱신이 필요하다면 디렉터리 마운트로 바꾸는 방안을 검토하되, 애플리케이션의 설정 경로도 맞춰야 합니다.
- 컨테이너에 cat이나 printenv가 없다면 exec 실패를 설정 미반영의 증거로 해석하지 않습니다. 위 예시의 조회 방식은 해당 도구가 있는 이미지에 한정됩니다.
- immutable ConfigMap은 데이터를 수정할 수 없습니다. 삭제 후 같은 이름으로 재생성한 경우도 단순 값 수정과 구분해야 하며, 기존 Pod도 다시 생성하는 것이 권장됩니다.
진단 기록에는 사용 방식, ConfigMap에 저장된 값, 컨테이너에서 읽은 값, 애플리케이션의 적용 상태를 따로 남기세요. 이 네 가지를 분리하면 재시작이 필요한 경우와 볼륨 전파를 기다려야 하는 경우를 판단하기 쉬워집니다.