Apr 2, 2026

Kubernetes ConfigMap 가이드: 설정을 이미지 밖으로 빼는 이유

쿠버네티스를 처음 배울 때 애플리케이션 이미지는 잘 만들었는데, 설정값을 어디에 둬야 할지에서 자주 막힙니다. DB 주소, API endpoint, feature flag 같은 값을 이미지 안에 같이 넣어 두면 처음에는 편해 보여도 운영이 금방 불편해집니다.

이때 자주 등장하는 리소스가 ConfigMap입니다. ConfigMap은 애플리케이션 설정을 컨테이너 이미지와 분리해서 관리하게 도와줍니다.

이 글에서는 아래 내용을 정리합니다.

ConfigMap이 무엇인지
환경 변수와 파일 마운트로 어떻게 쓰는지
Secret과는 무엇이 다른지

핵심은 ConfigMap은 애플리케이션 코드나 이미지가 아니라 “환경별 설정”을 분리하는 도구라는 점입니다.

Kubernetes ConfigMap이란 무엇인가

ConfigMap은 문자열 기반 설정 데이터를 key-value 형태로 저장하는 리소스입니다. 이 데이터는 Pod 안에서 환경 변수로 주입하거나, 파일처럼 마운트해서 사용할 수 있습니다.

예를 들면 아래 같은 값을 넣을 수 있습니다.

APP_ENV=production
API_BASE_URL=https://api.example.com
FEATURE_X_ENABLED=true

즉, ConfigMap은 앱이 동작하는 데 필요한 설정을 코드 밖에서 관리하도록 해 줍니다.

왜 설정을 이미지 안에 넣지 않을까

처음에는 Docker 이미지 안에 설정 파일을 같이 넣고 싶어질 수 있습니다. 하지만 그러면 환경이 바뀔 때마다 이미지를 다시 빌드해야 하고, 같은 애플리케이션을 개발/스테이징/운영 환경에 다르게 배포하기도 어려워집니다.

ConfigMap을 쓰면 이런 점이 좋아집니다.

이미지 재빌드 없이 설정을 바꿀 수 있다
같은 이미지를 여러 환경에서 재사용하기 쉽다
애플리케이션 코드와 운영 설정을 분리할 수 있다

즉, ConfigMap은 운영 유연성을 높여 줍니다.

가장 기본적인 ConfigMap 예시

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  APP_ENV: production
  API_BASE_URL: https://api.example.com
  FEATURE_X_ENABLED: "true"

이 ConfigMap은 세 개의 설정값을 저장합니다.

중요한 점은 data 값이 문자열로 저장된다는 점입니다. 숫자나 불리언처럼 보여도, 다루는 쪽에서는 문자열이라는 점을 고려하는 편이 안전합니다.

환경 변수로 주입하는 방법

가장 흔한 사용 방식입니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 1
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: my-web:1.0.0
          envFrom:
            - configMapRef:
                name: app-config

이렇게 하면 ConfigMap의 key들이 컨테이너 환경 변수로 들어갑니다.

설정값이 몇 개 안 된다면 env로 하나씩 명시해도 되지만, 묶어서 넣고 싶을 때는 envFrom이 편합니다.

파일처럼 마운트하는 방법

설정 파일 형태가 필요한 앱이라면 ConfigMap을 볼륨으로 마운트할 수도 있습니다.

예를 들어 앱이 config.yaml 파일을 읽는 구조라면 ConfigMap을 파일처럼 전달할 수 있습니다.

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config-file
data:
  config.yaml: |
    appEnv: production
    featureXEnabled: true

이 방식은 Spring, Nginx, 일부 Node.js 앱처럼 설정 파일을 직접 읽는 경우에 특히 유용합니다.

ConfigMap 과 Secret 은 무엇이 다를까

입문 단계에서 가장 많이 나오는 질문입니다.

ConfigMap: 일반 설정값
Secret: 민감한 값

예를 들어 아래처럼 나눠 생각하면 편합니다.

ConfigMap: API base URL, 로그 레벨, feature flag
Secret: DB 비밀번호, API 토큰, 인증서 키

즉, ConfigMap은 공개되어도 상대적으로 위험이 낮은 설정을, Secret은 민감한 값을 다루는 데 더 적합합니다. Secret 쪽은 Kubernetes Secret 가이드에서 이어서 보면 좋습니다.

자주 하는 실수

1. 비밀번호를 ConfigMap에 넣기

기술적으로는 가능해 보여도 보안적으로는 좋지 않습니다. 민감한 값은 Secret으로 분리하는 편이 맞습니다.

2. 값이 바뀌면 Pod도 자동으로 다 반영된다고 생각하기

반영 방식은 주입 방법과 애플리케이션 구현에 따라 달라집니다. 어떤 앱은 재시작이 필요할 수 있습니다.

3. 환경별 설정을 하나의 ConfigMap에 과하게 섞기

개발, 스테이징, 운영 값을 뒤섞으면 운영 중 실수가 생기기 쉽습니다. 환경별로 분리하는 편이 좋습니다.

처음 공부할 때 추천하는 실습

ConfigMap으로 APP_ENV와 API_BASE_URL 만들기
Deployment에서 환경 변수로 주입하기
값을 바꾸고 앱이 어떻게 반응하는지 보기
파일 마운트 방식도 한 번 비교해 보기

이 실습을 해 보면 ConfigMap이 단순 텍스트 저장소가 아니라, 이미지와 환경 설정을 분리하는 운영 도구라는 점이 더 분명해집니다.

FAQ

Q. `.env` 파일을 그대로 ConfigMap으로 써도 되나요?

가능한 경우도 있지만, 키 이름과 환경 분리 전략을 먼저 정리한 뒤 쓰는 편이 더 안전합니다.

Q. ConfigMap 값이 바뀌면 앱이 자동 반영되나요?

항상 그렇지는 않습니다. 앱이 환경 변수를 언제 읽는지, 파일 변경을 감지하는지에 따라 다릅니다.

Q. 작은 프로젝트도 ConfigMap이 필요한가요?

처음에는 과해 보일 수 있지만, 환경이 둘 이상만 되어도 금방 가치가 커집니다.

먼저 읽어볼 가이드

검색 유입이 많은 핵심 글부터 이어서 보세요.