Kubernetes 환경에서 ConfigMap 변경 적용 문제 처리 과정
1. 문제 상황: ConfigMap을 수정해도 반영되지 않는 설정
서비스 운영 중 외부 API 주소 변경, 환경 변수 수정 등의 작업을 위해 ConfigMap을 업데이트했지만, 변경 사항이 반영되지 않아 장애가 발생한 일이 있었다.
초기 상황은 다음과 같았다.
- ConfigMap은 정상적으로 업데이트되었음
- Pod는 실행 중이며 재시작되지 않았음
- 애플리케이션은 여전히 이전 설정을 사용하고 있었음
문제는 ConfigMap의 변경이 기존 Pod에 자동으로 적용되지 않는다는 Kubernetes의 기본 동작 방식에 대한 이해 부족에서 비롯되었다.
2. 원인 분석: Kubernetes의 ConfigMap 동작 방식
2.1 ConfigMap은 Pod 실행 시점에만 참조됨
Kubernetes의 ConfigMap은 Pod가 시작될 때 해당 값을 읽어들이며, 실행 중인 Pod는 ConfigMap 변경 사항을 자동으로 반영하지 않는다. 따라서 ConfigMap을 수정하더라도 기존 Pod에는 아무런 변화가 없다.
예를 들어 다음과 같은 방식으로 설정이 되어 있었다.
volumeMounts:
- name: config
mountPath: /etc/config
volumes:
- name: config
configMap:
name: my-config
이 경우 Pod 재시작 없이 변경 사항이 적용되지 않는다.
2.2 롤링 업데이트가 자동으로 일어나지 않음
Deployment 리소스를 사용하고 있었지만, ConfigMap만 변경했을 경우 Pod Template이 변경되지 않기 때문에 Kubernetes는 새로운 롤링 업데이트를 트리거하지 않는다.
3. 해결 과정: ConfigMap 변경 적용 전략
3.1 주기적인 Pod 재시작 스크립트 작성
가장 단순한 해결책은 ConfigMap을 변경한 후 관련 Deployment를 재시작하는 것이다.
kubectl rollout restart deployment my-deployment
이 명령은 Deployment의 Pod Template에 영향을 주지 않지만, 강제로 새 Pod를 띄우게 되어 변경된 ConfigMap이 반영된다.
3.2 ConfigMap 해시값을 파드 템플릿에 주입
보다 자동화된 방식으로는 ConfigMap 내용을 해시(hash)로 계산한 값을 annotation으로 Deployment에 주입하여, 내용이 바뀔 때마다 Pod Template이 변경되도록 만들 수 있다.
예를 들어 GitOps 환경에서는 다음과 같은 방식으로 Helm 템플릿을 구성했다.
annotations:
configmap-hash: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
이 방법을 적용하면 ConfigMap 변경 시 새로운 해시값이 반영되어 Kubernetes가 자동으로 롤링 업데이트를 수행한다.
3.3 애플리케이션 레벨 핫 리로드 지원
ConfigMap을 마운트하면 파일로 제공되기 때문에, 애플리케이션이 이를 주기적으로 감지하여 설정을 동적으로 다시 로딩하는 기능을 갖추는 것도 방법이다.
예를 들어 Nginx는 SIGHUP 신호를 받아 설정을 다시 읽을 수 있고, Spring Boot는 actuator endpoint를 통해 설정 변경을 트리거할 수 있다. 이 방식은 재시작 없이 변경 사항을 반영할 수 있다는 점에서 운영 안정성 측면에서 유리하다.
4. 결과 및 정리
이슈 재발 방지를 위해 ConfigMap 변경 시 아래 프로세스를 표준화했다.
- Git 저장소에 ConfigMap 정의 수정
- Helm 또는 Kustomize를 통해 해시 기반 주입
- CD 파이프라인에서 자동 롤링 업데이트 수행
- 애플리케이션의 핫 리로드 기능 병행 적용
결과적으로 설정 변경이 실시간에 가깝게 반영되며, 배포 안정성도 높아졌다. 초기에는 단순하게 보였던 ConfigMap 문제도, 실제 운영 환경에서는 고려할 요소가 많았다.
핵심 정리
- ConfigMap 변경은 자동 반영되지 않음 → Pod 재시작 또는 해시 기반 자동화 필요
- Helm이나 Kustomize를 활용한 해시 주입 방식 권장
- 핫 리로드 기능을 활용하면 무중단 반영도 가능
- CD 파이프라인에 반영 프로세스를 내재화할 것
Kubernetes는 유연한 구조이지만, 반대로 명시적인 처리가 없으면 의도치 않은 상태가 발생할 수 있다. ConfigMap과 같은 설정 리소스도 코드와 동일하게 체계적으로 관리해야 한다.