Ver3.5 ⚙️ ConfigMap과 Secret으로 쿠버네티스 설정 관리 완전 정복

⚙️ ConfigMap과 Secret으로 쿠버네티스 설정 관리 완전 정복
자, 상상해봐. 네가 열심히 만든 웹 애플리케이션이 있어. 개발 환경에서는 DB 주소가 localhost:5432고, 스테이징 환경에서는 staging-db.internal:5432, 프로덕션에서는 prod-db.internal:5432야.
이걸 어떻게 관리하고 있어? 혹시 이런 코드 본 적 있지 않아?
// config.js
const DB_HOST = "prod-db.internal:5432"; // 하드코딩!
const DB_PASSWORD = "super_secret_1234"; // 비밀번호 하드코딩!!
const API_KEY = "sk-abcdef1234567890"; // API 키 하드코딩!!!
설정 하나 바꾸려면 전체 배포 파이프라인을 다시 돌려야 해. 완전 비효율!
이게 바로 "설정과 코드의 분리(Separation of Config from Code)"가 필요한 이유야. 이건 그냥 좋은 습관이 아니라, 12-Factor App 방법론에서도 핵심 원칙 중 하나로 꼽히는 중요한 개념이거든.
쿠버네티스(Kubernetes)는 이 문제를 해결하기 위해 두 가지 핵심 오브젝트를 제공해:
ConfigMap과 Secret이야. 이 둘을 제대로 이해하고 쓰면, 진짜 프로답게 설정을 관리할 수 있어. 지금부터 하나씩 파헤쳐보자! 🚀
ConfigMap은 이름 그대로 설정(Config)을 담는 맵(Map)이야. 키-값(key-value) 쌍으로 설정 데이터를 저장하는 쿠버네티스 오브젝트인데, 비밀이 아닌 일반적인 설정 정보를 담는 데 사용해.
- 키-값 쌍, 전체 설정 파일, 환경 변수 등 다양한 형태로 저장 가능
- 최대 1MiB 크기 제한 (더 큰 데이터는 별도 볼륨 사용 권장)
- 네임스페이스(Namespace) 범위 내에서 동작
- Pod와 독립적으로 존재 — Pod가 죽어도 ConfigMap은 살아있어!
- 데이터베이스 호스트 주소
- 애플리케이션 포트 번호
- 로그 레벨 설정
- 기능 플래그(Feature Flag)
- 외부 서비스 URL
- 설정 파일 전체 내용
- 환경 이름(dev/staging/prod)
- 비밀번호
- API 키
- OAuth 토큰
- TLS 인증서
- SSH 키
- 개인 식별 정보(PII)
→ 이건 Secret으로!
ConfigMap의 YAML 구조는 이렇게 생겼어:
📄 configmap-basic.yamlapiVersion: v1
kind: ConfigMap
metadata:
name: app-config # ConfigMap 이름
namespace: default # 네임스페이스
labels:
app: my-app
env: production
data:
# 단순 키-값 쌍
APP_ENV: "production"
APP_PORT: "8080"
LOG_LEVEL: "info"
DB_HOST: "prod-db.internal"
DB_PORT: "5432"
DB_NAME: "myapp_db"
# 설정 파일 전체를 값으로 저장
app.properties: |
server.port=8080
spring.datasource.url=jdbc:postgresql://prod-db.internal:5432/myapp_db
logging.level.root=INFO
cache.ttl=3600
nginx.conf: |
server {
listen 80;
server_name myapp.example.com;
location / {
proxy_pass http://localhost:8080;
}
}
data 섹션에는 UTF-8 문자열만 들어갈 수 있어. 바이너리 데이터가 필요하면 binaryData 섹션을 사용하고, base64로 인코딩해서 넣어야 해!
ConfigMap은 쿠버네티스 API 서버에 저장되고, etcd 데이터베이스에 보관돼. 평문(plain text)으로 저장되기 때문에 민감한 정보는 절대 넣으면 안 돼. 이건 진짜 중요한 포인트야! 🔑
Secret은 ConfigMap과 비슷하지만, 민감한 데이터를 저장하기 위한 오브젝트야. 비밀번호, API 키, 인증서 같은 것들을 안전하게 관리하는 데 사용해.
진짜 암호화를 원하면 etcd 암호화(Encryption at Rest)를 별도로 설정하거나, HashiCorp Vault 같은 외부 시크릿 관리 도구를 써야 해.
Secret은 여러 타입이 있어. 각 타입마다 용도가 달라:
| 타입 | 설명 | 사용 예시 |
|---|---|---|
Opaque |
기본 타입, 임의의 데이터 | 비밀번호, API 키 |
kubernetes.io/service-account-token |
서비스 계정 토큰 | Pod의 API 서버 인증 |
kubernetes.io/dockerconfigjson |
Docker 레지스트리 인증 | Private 이미지 풀 |
kubernetes.io/tls |
TLS 인증서와 키 | HTTPS 설정 |
kubernetes.io/ssh-auth |
SSH 인증 데이터 | SSH 키 관리 |
kubernetes.io/basic-auth |
기본 인증 자격증명 | username/password |
bootstrap.kubernetes.io/token |
부트스트랩 토큰 | 노드 부트스트랩 |
apiVersion: v1
kind: Secret
metadata:
name: app-secret
namespace: default
type: Opaque
data:
# base64로 인코딩된 값들
# echo -n "mypassword" | base64 → bXlwYXNzd29yZA==
DB_PASSWORD: bXlwYXNzd29yZA==
API_KEY: c2stYWJjZGVmMTIzNDU2Nzg5MA==
stringData:
# stringData는 평문으로 입력 가능 (쿠버네티스가 자동으로 base64 인코딩)
REDIS_PASSWORD: "my-redis-secret-password"
JWT_SECRET: "super-secret-jwt-key-2024"
data와 stringData를 같이 쓸 수 있어. stringData에 넣으면 쿠버네티스가 자동으로 base64 인코딩해줘서 편리해. 같은 키가 두 섹션에 있으면 stringData가 우선순위를 가져!
ConfigMap을 만드는 방법은 여러 가지야. 상황에 따라 가장 편한 방법을 골라 쓰면 돼!
가장 기본적이고 권장되는 방법이야. 버전 관리(Git)에 올릴 수 있어서 좋아:
📄 app-configmap.yamlapiVersion: v1
kind: ConfigMap
metadata:
name: webapp-config
namespace: production
data:
# 환경 변수 형태
DATABASE_HOST: "postgres.production.svc.cluster.local"
DATABASE_PORT: "5432"
DATABASE_NAME: "webapp_prod"
REDIS_HOST: "redis.production.svc.cluster.local"
REDIS_PORT: "6379"
APP_LOG_LEVEL: "warn"
APP_MAX_CONNECTIONS: "100"
FEATURE_NEW_UI: "true"
FEATURE_BETA_API: "false"
# 설정 파일 형태 (멀티라인)
application.yaml: |
server:
port: 8080
shutdown: graceful
spring:
datasource:
url: jdbc:postgresql://postgres.production.svc.cluster.local:5432/webapp_prod
hikari:
maximum-pool-size: 20
minimum-idle: 5
cache:
type: redis
logging:
level:
root: WARN
com.myapp: INFO
💻 터미널
# YAML 파일로 ConfigMap 생성
kubectl apply -f app-configmap.yaml
# 생성 확인
kubectl get configmap webapp-config -n production
# 상세 내용 확인
kubectl describe configmap webapp-config -n production
# YAML 형태로 출력
kubectl get configmap webapp-config -n production -o yaml
빠르게 테스트할 때 유용해:
💻 터미널# 리터럴 값으로 생성
kubectl create configmap app-config \
--from-literal=APP_ENV=production \
--from-literal=APP_PORT=8080 \
--from-literal=LOG_LEVEL=info
# 파일에서 생성 (파일명이 키가 됨)
kubectl create configmap nginx-config \
--from-file=nginx.conf
# 파일에서 생성 (키 이름 직접 지정)
kubectl create configmap nginx-config \
--from-file=my-nginx-config=./nginx.conf
# 디렉토리 전체에서 생성 (디렉토리 내 모든 파일)
kubectl create configmap app-configs \
--from-file=./config-directory/
# env 파일에서 생성
kubectl create configmap app-config \
--from-env-file=.env.production
기존에 .env 파일을 쓰고 있다면 이 방법이 편해:
📄 .env.productionDATABASE_HOST=postgres.production.svc.cluster.local
DATABASE_PORT=5432
DATABASE_NAME=webapp_prod
REDIS_HOST=redis.production.svc.cluster.local
APP_LOG_LEVEL=warn
FEATURE_NEW_UI=true
💻 터미널
# env 파일로 ConfigMap 생성
kubectl create configmap webapp-config \
--from-env-file=.env.production \
-n production
--from-env-file과 --from-file의 차이를 알아둬!--from-env-file: 각 줄의 KEY=VALUE를 개별 키-값으로 파싱--from-file: 파일 전체 내용을 하나의 값으로 저장 (파일명이 키)
# 방법 1: apply로 업데이트 (YAML 수정 후)
kubectl apply -f app-configmap.yaml
# 방법 2: edit으로 직접 수정
kubectl edit configmap webapp-config -n production
# 방법 3: patch로 특정 값만 수정
kubectl patch configmap webapp-config \
-p '{"data":{"LOG_LEVEL":"debug"}}'
# 방법 4: 삭제 후 재생성
kubectl delete configmap webapp-config
kubectl create configmap webapp-config --from-file=./config/
Secret도 ConfigMap과 비슷하게 여러 방법으로 만들 수 있어. 다만 보안에 더 신경 써야 해!
apiVersion: v1
kind: Secret
metadata:
name: webapp-secret
namespace: production
type: Opaque
stringData:
# stringData 사용 시 평문으로 입력 가능
# 쿠버네티스가 자동으로 base64 인코딩
DB_PASSWORD: "P@ssw0rd!2024"
REDIS_PASSWORD: "redis-secret-key"
JWT_SECRET: "my-super-secret-jwt-key-256bits"
API_KEY: "sk-prod-abcdefghijklmnop1234567890"
# macOS/Linux에서 base64 인코딩
echo -n "P@ssw0rd!2024" | base64
# 출력: UEBzc3cwcmQhMjAyNA==
echo -n "my-jwt-secret" | base64
# 출력: bXktand0LXNlY3JldA==
# base64 디코딩 확인
echo "UEBzc3cwcmQhMjAyNA==" | base64 -d
# 출력: P@ssw0rd!2024
📄 app-secret-base64.yaml
apiVersion: v1
kind: Secret
metadata:
name: webapp-secret
namespace: production
type: Opaque
data:
DB_PASSWORD: UEBzc3cwcmQhMjAyNA==
JWT_SECRET: bXktand0LXNlY3JldA==
# 리터럴 값으로 생성 (자동으로 base64 인코딩됨)
kubectl create secret generic webapp-secret \
--from-literal=DB_PASSWORD="P@ssw0rd!2024" \
--from-literal=JWT_SECRET="my-jwt-secret-key" \
-n production
# 파일에서 생성
kubectl create secret generic tls-secret \
--from-file=tls.crt=./server.crt \
--from-file=tls.key=./server.key
# TLS Secret 전용 명령어
kubectl create secret tls my-tls-secret \
--cert=./server.crt \
--key=./server.key
# Docker 레지스트리 Secret
kubectl create secret docker-registry regcred \
--docker-server=registry.example.com \
--docker-username=myuser \
--docker-password="mypassword" \
--docker-email=myemail@example.com
# 비밀번호를 파일에 저장 (줄바꿈 없이!)
echo -n "P@ssw0rd!2024" > ./db-password.txt
echo -n "my-api-key-value" > ./api-key.txt
# 파일에서 Secret 생성
kubectl create secret generic app-credentials \
--from-file=DB_PASSWORD=./db-password.txt \
--from-file=API_KEY=./api-key.txt \
-n production
# 사용 후 파일 삭제!
rm ./db-password.txt ./api-key.txt
# Secret 목록 조회 (값은 보이지 않음)
kubectl get secrets -n production
# Secret 상세 조회 (base64 인코딩된 값 확인)
kubectl get secret webapp-secret -n production -o yaml
# 특정 키 값 디코딩해서 확인
kubectl get secret webapp-secret -n production \
-o jsonpath='{.data.DB_PASSWORD}' | base64 -d
# 모든 키-값 한번에 디코딩
kubectl get secret webapp-secret -n production \
-o go-template='{{range $k,$v := .data}}{{$k}}={{$v | base64decode}}{{"\n"}}{{end}}'
history -c로 히스토리를 지우거나, 명령어 앞에 공백을 넣어서 히스토리 저장을 방지할 수 있어 (bash의 HISTCONTROL=ignorespace 설정 필요).
자, 이제 진짜 핵심이야! ConfigMap과 Secret을 만들었으면 Pod에서 어떻게 사용하는지 알아야지. 크게 두 가지 방법이 있어: 환경 변수로 주입하거나, 볼륨(파일)으로 마운트하는 거야.
1-1. 특정 키만 환경 변수로 주입 (valueFrom)
📄 pod-env-specific.yamlapiVersion: v1
kind: Pod
metadata:
name: webapp
namespace: production
spec:
containers:
- name: webapp
image: myapp:1.0.0
env:
# ConfigMap에서 특정 키 가져오기
- name: APP_ENV
valueFrom:
configMapKeyRef:
name: webapp-config # ConfigMap 이름
key: APP_ENV # ConfigMap의 키
- name: DATABASE_HOST
valueFrom:
configMapKeyRef:
name: webapp-config
key: DATABASE_HOST
optional: true # ConfigMap이 없어도 Pod 시작 가능
# Secret에서 특정 키 가져오기
- name: DB_PASSWORD
valueFrom:
secretKeyRef:
name: webapp-secret # Secret 이름
key: DB_PASSWORD # Secret의 키
- name: API_KEY
valueFrom:
secretKeyRef:
name: webapp-secret
key: API_KEY
1-2. ConfigMap/Secret 전체를 환경 변수로 주입 (envFrom)
📄 pod-env-all.yamlapiVersion: v1
kind: Pod
metadata:
name: webapp
namespace: production
spec:
containers:
- name: webapp
image: myapp:1.0.0
envFrom:
# ConfigMap 전체를 환경 변수로
- configMapRef:
name: webapp-config
optional: false # 필수 (없으면 Pod 시작 실패)
# Secret 전체를 환경 변수로
- secretRef:
name: webapp-secret
# 접두사 붙이기 (충돌 방지)
- configMapRef:
name: common-config
prefix: COMMON_ # 모든 키에 COMMON_ 접두사 추가
2-1. ConfigMap 전체를 볼륨으로 마운트
📄 pod-volume-configmap.yamlapiVersion: v1
kind: Pod
metadata:
name: webapp
namespace: production
spec:
containers:
- name: webapp
image: myapp:1.0.0
volumeMounts:
- name: config-volume
mountPath: /etc/config # 컨테이너 내 마운트 경로
readOnly: true # 읽기 전용 권장
- name: nginx-config
mountPath: /etc/nginx/conf.d
readOnly: true
volumes:
# ConfigMap 전체를 볼륨으로
- name: config-volume
configMap:
name: webapp-config # ConfigMap 이름
# 각 키가 파일명이 되어 마운트됨
# /etc/config/APP_ENV
# /etc/config/DATABASE_HOST
# /etc/config/application.yaml
# 특정 키만 선택해서 마운트
- name: nginx-config
configMap:
name: webapp-config
items:
- key: nginx.conf # ConfigMap의 키
path: default.conf # 마운트될 파일명
mode: 0644 # 파일 권한
2-2. Secret을 볼륨으로 마운트
📄 pod-volume-secret.yamlapiVersion: v1
kind: Pod
metadata:
name: webapp
namespace: production
spec:
containers:
- name: webapp
image: myapp:1.0.0
volumeMounts:
- name: secret-volume
mountPath: /etc/secrets
readOnly: true
- name: tls-certs
mountPath: /etc/ssl/certs
readOnly: true
volumes:
# Secret 전체를 볼륨으로
- name: secret-volume
secret:
secretName: webapp-secret
defaultMode: 0400 # 소유자만 읽기 가능 (보안!)
# /etc/secrets/DB_PASSWORD (파일 내용이 실제 비밀번호)
# /etc/secrets/API_KEY
# TLS Secret 마운트
- name: tls-certs
secret:
secretName: my-tls-secret
items:
- key: tls.crt
path: server.crt
- key: tls.key
path: server.key
mode: 0400 # 키 파일은 더 엄격하게
defaultMode: 0400으로 파일 권한을 제한하는 걸 잊지 마!
apiVersion: v1
kind: Pod
metadata:
name: webapp
spec:
containers:
- name: webapp
image: myapp:1.0.0
volumeMounts:
# subPath를 사용하면 특정 파일만 특정 경로에 마운트
- name: config-volume
mountPath: /app/config/application.yaml # 파일 경로
subPath: application.yaml # ConfigMap의 키
readOnly: true
- name: config-volume
mountPath: /etc/nginx/nginx.conf
subPath: nginx.conf
readOnly: true
volumes:
- name: config-volume
configMap:
name: webapp-config
이제 실제로 어떻게 쓰는지 완전한 예제로 보여줄게. Node.js 웹앱을 쿠버네티스에 배포하면서 ConfigMap과 Secret을 완벽하게 활용하는 시나리오야. 재능넷 같은 플랫폼을 운영한다고 가정해보자!
- PostgreSQL 데이터베이스 연결
- Redis 캐시 연결
- JWT 인증
- 외부 결제 API 연동
- Nginx 리버스 프록시
Step 1: ConfigMap 생성
📄 01-configmap.yamlapiVersion: v1
kind: ConfigMap
metadata:
name: talent-platform-config
namespace: production
labels:
app: talent-platform
version: "1.0"
data:
# 앱 기본 설정
NODE_ENV: "production"
APP_PORT: "3000"
APP_NAME: "TalentPlatform"
LOG_LEVEL: "warn"
# 데이터베이스 설정 (비밀번호 제외)
DB_HOST: "postgres.production.svc.cluster.local"
DB_PORT: "5432"
DB_NAME: "talent_platform_prod"
DB_POOL_MIN: "5"
DB_POOL_MAX: "20"
DB_IDLE_TIMEOUT: "30000"
# Redis 설정
REDIS_HOST: "redis.production.svc.cluster.local"
REDIS_PORT: "6379"
REDIS_DB: "0"
CACHE_TTL: "3600"
SESSION_TTL: "86400"
# 외부 서비스 URL
PAYMENT_API_URL: "https://api.payment-gateway.com/v2"
EMAIL_SERVICE_URL: "https://api.sendgrid.com/v3"
CDN_BASE_URL: "https://cdn.talent-platform.com"
# 기능 플래그
FEATURE_NEW_SEARCH: "true"
FEATURE_AI_MATCHING: "false"
FEATURE_LIVE_CHAT: "true"
MAX_FILE_UPLOAD_SIZE: "10485760" # 10MB
# Nginx 설정 파일
nginx.conf: |
upstream nodejs {
server localhost:3000;
keepalive 64;
}
server {
listen 80;
server_name talent-platform.com www.talent-platform.com;
client_max_body_size 10M;
location / {
proxy_pass http://nodejs;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_cache_bypass $http_upgrade;
}
location /health {
access_log off;
proxy_pass http://nodejs/health;
}
}
Step 2: Secret 생성
📄 02-secret.yamlapiVersion: v1
kind: Secret
metadata:
name: talent-platform-secret
namespace: production
labels:
app: talent-platform
type: Opaque
stringData:
# 데이터베이스 비밀번호
DB_PASSWORD: "Pr0d-DB-P@ssw0rd!2024"
# Redis 비밀번호
REDIS_PASSWORD: "redis-prod-secret-key-2024"
# JWT 시크릿 (256비트 이상 권장)
JWT_SECRET: "your-256-bit-secret-key-for-jwt-production-2024"
JWT_REFRESH_SECRET: "your-refresh-token-secret-key-production-2024"
# 결제 API 키
PAYMENT_API_KEY: "pk_live_abcdefghijklmnop1234567890"
PAYMENT_SECRET_KEY: "sk_live_abcdefghijklmnop1234567890"
# 이메일 서비스 API 키
SENDGRID_API_KEY: "SG.abcdefghijklmnop.1234567890abcdefghijklmnop"
# 암호화 키 (데이터 암호화용)
ENCRYPTION_KEY: "32-character-encryption-key-here"
# 관리자 초기 비밀번호
ADMIN_INITIAL_PASSWORD: "Admin@2024!ChangeMe"
Step 3: Deployment 생성
📄 03-deployment.yamlapiVersion: apps/v1
kind: Deployment
metadata:
name: talent-platform-api
namespace: production
labels:
app: talent-platform
component: api
spec:
replicas: 3
selector:
matchLabels:
app: talent-platform
component: api
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1
maxUnavailable: 0
template:
metadata:
labels:
app: talent-platform
component: api
spec:
# 서비스 계정 (RBAC)
serviceAccountName: talent-platform-sa
# 보안 컨텍스트 (컨테이너를 root로 실행하지 않음)
securityContext:
runAsNonRoot: true
runAsUser: 1000
fsGroup: 2000
containers:
- name: api
image: talent-platform/api:1.5.2
ports:
- containerPort: 3000
name: http
# 리소스 제한
resources:
requests:
memory: "256Mi"
cpu: "250m"
limits:
memory: "512Mi"
cpu: "500m"
# ConfigMap 전체를 환경 변수로 주입
envFrom:
- configMapRef:
name: talent-platform-config
# Secret 전체를 환경 변수로 주입
- secretRef:
name: talent-platform-secret
# 볼륨 마운트 (설정 파일)
volumeMounts:
- name: config-files
mountPath: /app/config
readOnly: true
- name: secret-files
mountPath: /app/secrets
readOnly: true
- name: tmp-dir
mountPath: /tmp
# 헬스체크
livenessProbe:
httpGet:
path: /health/live
port: 3000
initialDelaySeconds: 30
periodSeconds: 10
failureThreshold: 3
readinessProbe:
httpGet:
path: /health/ready
port: 3000
initialDelaySeconds: 10
periodSeconds: 5
failureThreshold: 3
# 컨테이너 보안 설정
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities:
drop:
- ALL
# Nginx 사이드카
- name: nginx
image: nginx:1.25-alpine
ports:
- containerPort: 80
name: http-nginx
volumeMounts:
- name: nginx-config
mountPath: /etc/nginx/conf.d
readOnly: true
resources:
requests:
memory: "64Mi"
cpu: "50m"
limits:
memory: "128Mi"
cpu: "100m"
volumes:
# ConfigMap 파일들
- name: config-files
configMap:
name: talent-platform-config
items:
- key: nginx.conf
path: nginx.conf
# Nginx 설정
- name: nginx-config
configMap:
name: talent-platform-config
items:
- key: nginx.conf
path: default.conf
# Secret 파일들 (tmpfs에 저장됨)
- name: secret-files
secret:
secretName: talent-platform-secret
defaultMode: 0400
# 임시 디렉토리 (readOnlyRootFilesystem 때문에 필요)
- name: tmp-dir
emptyDir: {}
Step 4: Node.js 코드에서 설정 읽기
📄 config.js (Node.js)// 환경 변수에서 설정 읽기 (ConfigMap + Secret에서 주입됨)
const config = {
app: {
name: process.env.APP_NAME || 'TalentPlatform',
port: parseInt(process.env.APP_PORT) || 3000,
env: process.env.NODE_ENV || 'development',
logLevel: process.env.LOG_LEVEL || 'info',
},
database: {
host: process.env.DB_HOST,
port: parseInt(process.env.DB_PORT) || 5432,
name: process.env.DB_NAME,
password: process.env.DB_PASSWORD, // Secret에서 주입
pool: {
min: parseInt(process.env.DB_POOL_MIN) || 2,
max: parseInt(process.env.DB_POOL_MAX) || 10,
}
},
redis: {
host: process.env.REDIS_HOST,
port: parseInt(process.env.REDIS_PORT) || 6379,
password: process.env.REDIS_PASSWORD, // Secret에서 주입
db: parseInt(process.env.REDIS_DB) || 0,
},
jwt: {
secret: process.env.JWT_SECRET, // Secret에서 주입
refreshSecret: process.env.JWT_REFRESH_SECRET,
expiresIn: '1h',
refreshExpiresIn: '7d',
},
payment: {
apiUrl: process.env.PAYMENT_API_URL,
apiKey: process.env.PAYMENT_API_KEY, // Secret에서 주입
secretKey: process.env.PAYMENT_SECRET_KEY,
},
features: {
newSearch: process.env.FEATURE_NEW_SEARCH === 'true',
aiMatching: process.env.FEATURE_AI_MATCHING === 'true',
liveChat: process.env.FEATURE_LIVE_CHAT === 'true',
}
};
// 필수 설정 검증
const requiredEnvVars = [
'DB_HOST', 'DB_NAME', 'DB_PASSWORD',
'REDIS_HOST', 'REDIS_PASSWORD',
'JWT_SECRET', 'JWT_REFRESH_SECRET',
];
requiredEnvVars.forEach(varName => {
if (!process.env[varName]) {
throw new Error(`필수 환경 변수 누락: ${varName}`);
}
});
module.exports = config;
이렇게 하면 코드는 완전히 깨끗하게 유지되고, 설정은 쿠버네티스가 관리해줘. 환경이 바뀌어도 코드 한 줄 수정 없이 ConfigMap과 Secret만 바꾸면 돼!
쿠버네티스 1.21부터 ConfigMap과 Secret을 불변(immutable)으로 설정할 수 있어. 이렇게 하면 실수로 수정하는 걸 방지하고, 성능도 향상돼:
📄 immutable-configmap.yamlapiVersion: v1
kind: ConfigMap
metadata:
name: app-config-v1-2-0
namespace: production
immutable: true # 이 ConfigMap은 수정 불가!
data:
APP_VERSION: "1.2.0"
DB_HOST: "prod-db.internal"
LOG_LEVEL: "warn"
- kubelet이 변경 감시를 하지 않아 API 서버 부하 감소
- 버전 관리 전략과 잘 맞음 (이름에 버전 포함)
- 변경이 필요하면 새 ConfigMap 생성 후 Pod 업데이트
# 개발 환경 ConfigMap
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
namespace: development # 개발 네임스페이스
data:
DB_HOST: "dev-db.development.svc.cluster.local"
LOG_LEVEL: "debug"
FEATURE_DEBUG_MODE: "true"
---
# 스테이징 환경 ConfigMap
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
namespace: staging # 스테이징 네임스페이스
data:
DB_HOST: "staging-db.staging.svc.cluster.local"
LOG_LEVEL: "info"
FEATURE_DEBUG_MODE: "false"
---
# 프로덕션 환경 ConfigMap
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
namespace: production # 프로덕션 네임스페이스
data:
DB_HOST: "prod-db.production.svc.cluster.local"
LOG_LEVEL: "warn"
FEATURE_DEBUG_MODE: "false"
이렇게 하면 Deployment YAML은 동일하게 유지하면서 네임스페이스만 바꿔서 배포할 수 있어. 진짜 깔끔하지? 😎
Kustomize는 쿠버네티스 내장 도구로, 환경별 설정 오버레이를 쉽게 관리할 수 있어:
📁 디렉토리 구조k8s/
├── base/
│ ├── kustomization.yaml
│ ├── deployment.yaml
│ └── configmap.yaml
├── overlays/
│ ├── development/
│ │ ├── kustomization.yaml
│ │ └── configmap-patch.yaml
│ ├── staging/
│ │ ├── kustomization.yaml
│ │ └── configmap-patch.yaml
│ └── production/
│ ├── kustomization.yaml
│ └── configmap-patch.yaml
📄 base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deployment.yaml
- configmap.yaml
📄 overlays/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
bases:
- ../../base
namespace: production
patches:
- path: configmap-patch.yaml
configMapGenerator:
- name: app-config
behavior: merge
literals:
- LOG_LEVEL=warn
- DB_HOST=prod-db.production.svc.cluster.local
💻 터미널
# 프로덕션 환경으로 배포
kubectl apply -k k8s/overlays/production/
# 개발 환경으로 배포
kubectl apply -k k8s/overlays/development/
Helm을 사용하면 values.yaml로 환경별 설정을 더 유연하게 관리할 수 있어:
📄 values.production.yamlconfig:
logLevel: warn
dbHost: prod-db.production.svc.cluster.local
dbPort: 5432
redisHost: redis.production.svc.cluster.local
features:
newSearch: true
aiMatching: false
replicaCount: 3
resources:
requests:
memory: "256Mi"
cpu: "250m"
limits:
memory: "512Mi"
cpu: "500m"
📄 templates/configmap.yaml (Helm 템플릿)
apiVersion: v1
kind: ConfigMap
metadata:
name: {{ include "myapp.fullname" . }}-config
namespace: {{ .Release.Namespace }}
data:
LOG_LEVEL: {{ .Values.config.logLevel | quote }}
DB_HOST: {{ .Values.config.dbHost | quote }}
DB_PORT: {{ .Values.config.dbPort | quote }}
REDIS_HOST: {{ .Values.config.redisHost | quote }}
FEATURE_NEW_SEARCH: {{ .Values.config.features.newSearch | quote }}
FEATURE_AI_MATCHING: {{ .Values.config.features.aiMatching | quote }}
💻 터미널
# Helm으로 프로덕션 배포
helm upgrade --install myapp ./chart \
-f values.production.yaml \
-n production \
--create-namespace
프로덕션 환경에서는 AWS Secrets Manager, HashiCorp Vault 같은 외부 시크릿 관리 도구와 연동하는 게 베스트야. External Secrets Operator를 사용하면 이게 쉬워져:
📄 external-secret.yamlapiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
name: webapp-external-secret
namespace: production
spec:
refreshInterval: 1h # 1시간마다 동기화
secretStoreRef:
name: aws-secrets-manager # SecretStore 이름
kind: ClusterSecretStore
target:
name: webapp-secret # 생성될 쿠버네티스 Secret 이름
creationPolicy: Owner
data:
- secretKey: DB_PASSWORD # 쿠버네티스 Secret의 키
remoteRef:
key: production/webapp/db # AWS Secrets Manager 경로
property: password # JSON 내 필드명
- secretKey: JWT_SECRET
remoteRef:
key: production/webapp/jwt
property: secret
- secretKey: API_KEY
remoteRef:
key: production/webapp/api
property: key
- 외부 시크릿 관리 도구의 감사 로그, 버전 관리 활용 가능
- 시크릿 자동 로테이션 지원
- AWS, GCP, Azure, Vault 등 다양한 백엔드 지원
ConfigMap이 업데이트될 때 Pod를 자동으로 재시작하고 싶다면 Reloader 같은 도구를 사용해:
📄 deployment-with-reloader.yamlapiVersion: apps/v1
kind: Deployment
metadata:
name: webapp
annotations:
# Stakater Reloader 어노테이션
reloader.stakater.com/auto: "true"
# 특정 ConfigMap/Secret 변경 시만 재시작
configmap.reloader.stakater.com/reload: "webapp-config"
secret.reloader.stakater.com/reload: "webapp-secret"
spec:
# ... 나머지 설정
| 항목 | 권장 사항 |
|---|---|
| 네이밍 | 앱명-환경-config 형태로 명확하게 (예: webapp-prod-config) |
| 버전 관리 | ConfigMap 이름에 버전 포함 또는 Helm/Kustomize 사용 |
| Secret 보안 | RBAC + etcd 암호화 + External Secrets 조합 사용 |
| Git 관리 | ConfigMap은 Git에 OK, Secret은 절대 평문으로 Git에 올리지 말 것 |
| 크기 제한 | 1MiB 이하로 유지, 큰 파일은 PVC 사용 |
| 읽기 전용 | volumeMount에 readOnly: true 항상 설정 |
| 파일 권한 | Secret 볼륨은 defaultMode: 0400 설정 |
| 검증 | 앱 시작 시 필수 환경 변수 존재 여부 검증 로직 추가 |
| 모니터링 | Secret 접근 감사 로그 활성화 |
| 로테이션 | Secret 주기적 교체 정책 수립 (90일 권장) |
-n 옵션을 빠뜨리면 줄바꿈 문자(\n)가 포함돼서 값이 달라져!
# ❌ 잘못된 방법 (줄바꿈 포함됨)
echo "mypassword" | base64
# 출력: bXlwYXNzd29yZAo= ← 마지막 'o='가 줄바꿈 때문에 추가됨
# ✅ 올바른 방법 (-n 옵션으로 줄바꿈 제거)
echo -n "mypassword" | base64
# 출력: bXlwYXNzd29yZA== ← 올바른 인코딩
# 디코딩해서 확인
echo "bXlwYXNzd29yZAo=" | base64 -d | xxd | head
# 00000000: 6d79 7061 7373 776f 7264 0a mypassword. ← 0a가 줄바꿈!
echo "bXlwYXNzd29yZA==" | base64 -d | xxd | head
# 00000000: 6d79 7061 7373 776f 7264 mypassword ← 깔끔!
# ConfigMap 업데이트 후 Deployment 재시작 방법
# 방법 1: rollout restart (가장 권장)
kubectl rollout restart deployment/webapp -n production
# 방법 2: 어노테이션으로 강제 업데이트
kubectl patch deployment webapp \
-p "{\"spec\":{\"template\":{\"metadata\":{\"annotations\":{\"kubectl.kubernetes.io/restartedAt\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}}}}}" \
-n production
# 방법 3: 환경 변수 추가 (임시 방편)
kubectl set env deployment/webapp RESTART_TRIGGER="$(date)" -n production
# 롤아웃 상태 확인
kubectl rollout status deployment/webapp -n production
# Pod가 시작 안 될 때 확인 방법
kubectl describe pod webapp-xxx -n production
# 이런 에러가 나올 수 있어:
# Error: secret "webapp-secret" not found
# Error: configmap "webapp-config" not found
# 해결: Secret/ConfigMap 존재 여부 확인
kubectl get secret webapp-secret -n production
kubectl get configmap webapp-config -n production
# 없으면 생성
kubectl create secret generic webapp-secret \
--from-literal=DB_PASSWORD="password" \
-n production
# Pod 이벤트 확인
kubectl get events -n production --sort-by='.lastTimestamp'
# ConfigMap의 실제 키 목록 확인
kubectl get configmap webapp-config -n production \
-o jsonpath='{.data}' | python3 -m json.tool
# 또는
kubectl describe configmap webapp-config -n production
# Pod의 환경 변수 확인 (실행 중인 Pod)
kubectl exec -it webapp-xxx -n production -- env | grep -E "DB_|REDIS_|APP_"
# 특정 환경 변수 확인
kubectl exec -it webapp-xxx -n production -- printenv DB_HOST
# ❌ 잘못된 예시 - 기존 디렉토리를 덮어씀
volumeMounts:
- name: config-volume
mountPath: /etc # /etc 전체를 덮어버림! 시스템 파일 사라짐!
# ✅ 올바른 예시 - 전용 하위 디렉토리 사용
volumeMounts:
- name: config-volume
mountPath: /etc/myapp/config # 전용 경로 사용
// ❌ 절대 하지 말 것!
console.log('Config loaded:', JSON.stringify(config));
// → DB_PASSWORD, JWT_SECRET 등이 로그에 노출됨!
// ✅ 올바른 방법 - 민감 정보 마스킹
const safeConfig = {
...config,
database: { ...config.database, password: '***' },
jwt: { ...config.jwt, secret: '***', refreshSecret: '***' },
payment: { ...config.payment, secretKey: '***' },
};
console.log('Config loaded:', JSON.stringify(safeConfig));
# ConfigMap과 Pod는 같은 네임스페이스에 있어야 해!
# 다른 네임스페이스의 ConfigMap은 직접 참조 불가
# 확인 방법
kubectl get configmap -A | grep webapp-config
kubectl get pods -A | grep webapp
# 네임스페이스 지정 필수
kubectl get configmap webapp-config -n production # ✅
kubectl get configmap webapp-config # ❌ (default 네임스페이스 조회)
kubectl describe pod [pod명] → Events 섹션 확인2. ConfigMap/Secret 존재 여부 확인 (
kubectl get cm,secret -n [ns])3. 키 이름 오타 확인 (
kubectl describe cm [cm명])4. 네임스페이스 일치 여부 확인
5. RBAC 권한 확인 (
kubectl auth can-i get secret -n [ns])6. base64 인코딩 올바른지 확인
7. Pod 로그 확인 (
kubectl logs [pod명] -n [ns])
자, 이제 ConfigMap과 Secret에 대해 꽤 깊이 파고들었어! 마지막으로 핵심을 정리해볼게.
코드는 어떤 환경에서도 동일해야 해. 환경별 차이는 ConfigMap과 Secret이 담당해야 해.
2. 민감도에 따라 분리하라
공개 설정은 ConfigMap, 비밀 정보는 Secret. 이 경계를 절대 흐리지 마.
3. 보안은 레이어로 쌓아라
RBAC + etcd 암호화 + 외부 Vault + 감사 로그. 하나만으로는 부족해.
DevOps 세계에서 설정 관리는 단순한 기술 문제가 아니야. 팀의 협업 방식, 보안 문화, 운영 철학이 모두 담겨있어. ConfigMap과 Secret을 제대로 쓰는 것만으로도 팀의 개발 생산성과 보안 수준이 확 올라가거든.
재능넷에서 다양한 DevOps 전문가들이 쿠버네티스 설정 관리 컨설팅을 제공하고 있으니, 더 깊은 도움이 필요하다면 활용해봐도 좋아! 🙌
- Sealed Secrets: Secret을 Git에 안전하게 저장하는 방법
- SOPS (Secrets OPerationS): 파일 암호화 도구
- HashiCorp Vault: 엔터프라이즈급 시크릿 관리
- External Secrets Operator: 외부 시크릿 동기화
- cert-manager: TLS 인증서 자동 관리
- OPA/Gatekeeper: 정책 기반 설정 검증
- 쿠버네티스 공식 문서:
kubernetes.io/docs/concepts/configuration/configmap/- 쿠버네티스 공식 문서:
kubernetes.io/docs/concepts/configuration/secret/- 12-Factor App:
12factor.net/config- External Secrets Operator:
external-secrets.io- Sealed Secrets:
github.com/bitnami-labs/sealed-secrets
자, 이제 진짜 끝이야! ConfigMap과 Secret으로 설정 관리를 제대로 해서, 더 안전하고 유지보수하기 쉬운 쿠버네티스 앱을 만들어봐. 화이팅! 🚀🎉
댓글 작성
이 글에 대한 여러분의 생각을 들려주세요
로그인이 필요합니다
댓글을 작성하려면 먼저 로그인해주세요.
댓글 0
지식인의 숲 - 지적 재산권 보호 고지
지적 재산권 보호 고지
- 저작권 및 소유권: 본 컨텐츠는 재능넷의 독점 AI 기술로 생성되었으며, 대한민국 저작권법 및 국제 저작권 협약에 의해 보호됩니다.
- AI 생성 컨텐츠의 법적 지위: 본 AI 생성 컨텐츠는 재능넷의 지적 창작물로 인정되며, 관련 법규에 따라 저작권 보호를 받습니다.
- 사용 제한: 재능넷의 명시적 서면 동의 없이 본 컨텐츠를 복제, 수정, 배포, 또는 상업적으로 활용하는 행위는 엄격히 금지됩니다.
- 데이터 수집 금지: 본 컨텐츠에 대한 무단 스크래핑, 크롤링, 및 자동화된 데이터 수집은 법적 제재의 대상이 됩니다.
- AI 학습 제한: 재능넷의 AI 생성 컨텐츠를 타 AI 모델 학습에 무단 사용하는 행위는 금지되며, 이는 지적 재산권 침해로 간주됩니다.
아직 댓글이 없습니다.