쿠버네티스 ConfigMap·Secret 설정 주입과 흔한 실수

설정값을 이미지에 박아 넣으면 환경마다 이미지를 다시 빌드해야 합니다. 쿠버네티스는 **ConfigMap(평문 설정)**과 **Secret(민감 정보)**으로 설정을 코드에서 분리해 파드에 주입합니다. 그런데 "분명히 넣었는데 앱이 값을 못 본다"는 문제가 자주 생깁니다. 주입하는 두 방식과 안 들어가는 이유를 짚어봅니다.

두 가지 주입 방식

Kubernetes

kubectl create configmap app-config --from-literal=LOG_LEVEL=debug
kubectl create secret generic db-secret --from-literal=DB_PASS=p@ss

환경변수로 주입 — 앱이 process.env나 os.environ로 읽을 때:

YAML

envFrom:
  - configMapRef:
      name: app-config
  - secretRef:
      name: db-secret

파일로 마운트 — 앱이 설정 파일을 읽을 때:

YAML

volumes:
  - name: config
    configMap:
      name: app-config
containers:
  - volumeMounts:
      - name: config
        mountPath: /etc/config

확인은 컨테이너 안에서 직접 합니다.

Kubernetes

kubectl exec -it <pod> -- env | grep LOG_LEVEL
kubectl exec -it <pod> -- ls /etc/config

흔한 실수 5가지

값을 바꿔도 파드가 옛 값을 본다 — 환경변수(envFrom)는 파드 시작 시점에만 주입됩니다. ConfigMap을 수정해도 롤아웃을 안 하면 반영 안 됨. kubectl rollout restart deployment/<name> 필요.
Secret을 평문으로 넣음 — Secret의 data:는 base64 인코딩일 뿐 암호화가 아닙니다. 헷갈리면 stringData:에 평문을 넣으면 쿠버네티스가 인코딩해 줍니다.
이름·네임스페이스 불일치 — ConfigMap/Secret은 같은 네임스페이스에 있어야 참조됩니다. 다른 네임스페이스 것은 못 봅니다. 파드는 보통 CreateContainerConfigError로 안 뜹니다.
마운트가 디렉터리를 덮어씀 — mountPath에 볼륨을 걸면 그 경로의 기존 파일이 가려집니다. 한 파일만 넣으려면 subPath를 씁니다.
키 이름과 환경변수 이름 혼동 — valueFrom.configMapKeyRef로 개별 키를 가져올 때 key:는 ConfigMap 안의 키, name:(상위 env)은 컨테이너가 받을 변수명입니다.

증상	원인	해결
`CreateContainerConfigError`	이름·키·네임스페이스 오타	`kubectl describe pod`의 Events
옛 값 그대로	롤아웃 안 함	`kubectl rollout restart`
파일이 사라짐	mountPath가 디렉터리 덮음	`subPath` 사용

체크리스트

Kubernetes

kubectl get configmap,secret -n <ns>          # 존재·네임스페이스 확인
kubectl describe pod <pod>                     # ConfigError 이벤트
kubectl exec -it <pod> -- env | grep <KEY>     # 실제 주입값
kubectl rollout restart deployment/<name>      # 변경 반영

값이 안 보이면 거의 항상 위 5가지 중 하나입니다.

ConfigMap·Secret을 직접 만들어 주입하고 변경을 반영해 보는 실습은 쿠버네티스 트랙에서 회원가입 없이 무료로 해볼 수 있습니다.