---
title: "효율적인 애플리케이션 설정 관리를 위한 Kubernetes ConfigMap 활용 가이드"
description: "Kubernetes ConfigMap을 사용하면 애플리케이션 설정을 코드와 분리하여 이미지 재빌드 없이도 쉽게 변경할 수 있다. ConfigMap은 명령어("
date: "2025-10-15"
last_modified: "2026-05-15T08:36:00.000Z"
type: "Post"
tags:
  - "kubernetes"
categories:
  - "🤖 Computer Science"
series:
  - "k8s"
canonical_url: "https://blog.pieroot.xyz/k8s-configmap-guide"
markdown_url: "https://blog.pieroot.xyz/k8s-configmap-guide.md"
---

# 효율적인 애플리케이션 설정 관리를 위한 Kubernetes ConfigMap 활용 가이드

Kubernetes ConfigMap을 사용하면 애플리케이션 설정을 코드와 분리하여 이미지 재빌드 없이도 쉽게 변경할 수 있다. ConfigMap은 명령어(

### ConfigMap이란?

애플리케이션의 설정을 코드와 분리하여 관리하는 Kubernetes 객체입니다. 이미지를 다시 빌드하지 않고도 설정을 변경할 수 있습니다.

![image](https://blog.pieroot.xyz/api/image-proxy?id=8d3a79e9-2a27-4b6c-b2f3-bd5d67b77a69&kind=s3&pageId=2e4067c0-15d0-8078-9458-dfdad6d11607&source=block&blockId=2e4067c0-15d0-8083-8861-e79e98dab6c0)

### 1. ConfigMap 생성

#### 방법 1: 명령어로 생성

```bash
# 포트, 로그, 업로드 디렉터리 설정
kubectl create configmap simple-file-server-config \
  --from-literal=PORT=3001 \
  --from-literal=LOG_PATH=/var/log/app.log \
  --from-literal=UPLOAD_DIR=/var/uploads \
  --namespace volume

# 확인
kubectl get configmap simple-file-server-config -n volume -o yaml
```

#### 방법 2: YAML 파일로 생성

**configmap.yaml:**

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: simple-file-server-config
  namespace: volume
data:
  PORT: "3001"
  LOG_PATH: "/var/log/app.log"
  UPLOAD_DIR: "/var/uploads"
```

```bash
kubectl apply -f configmap.yaml
```

### 2. Deployment에서 ConfigMap 사용

**deployment-configmap.yaml:**

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: simple-file-server
  namespace: volume
spec:
  replicas: 2
  selector:
    matchLabels:
      app: simple-file-server
  template:
    metadata:
      labels:
        app: simple-file-server
    spec:
      nodeSelector:
        kubernetes.io/hostname: "worker"
      containers:
      - name: simple-file-server
        image: ghcr.io/jung-geun/simple-file-server:1.0
        imagePullPolicy: IfNotPresent
        ports:
        - containerPort: 3001
        env:
        - name: PORT
          valueFrom:
            configMapKeyRef:
              name: simple-file-server-config
              key: PORT
        - name: LOG_PATH
          valueFrom:
            configMapKeyRef:
              name: simple-file-server-config
              key: LOG_PATH
        - name: UPLOAD_DIR
          valueFrom:
            configMapKeyRef:
              name: simple-file-server-config
              key: UPLOAD_DIR
---
apiVersion: v1
kind: Service
metadata:
  name: simple-file-server
  namespace: volume
spec:
  type: NodePort
  selector:
    app: simple-file-server
  ports:
  - port: 3001
    targetPort: 3001
    nodePort: 30001
```

### 3. 실습: 이미지 빌드 및 배포

```bash
# 1. ConfigMap 생성 (포트 3001)
kubectl apply -f configmap.yaml

# 2. Deployment 및 Service 배포
kubectl apply -f deployment-configmap.yaml

# 3. Pod 상태 확인 (worker 노드 스케줄)
kubectl get pods -n volume -l app=simple-file-server -o wide

# 4. Service 확인
kubectl get svc -n volume simple-file-server

# 5. 접속 테스트
curl http://localhost:30001
```

### 4. 포트 변경 실습

#### 포트를 3001에서 3002로 변경

```bash
# ConfigMap 수정
kubectl edit configmap simple-file-server-config -n volume
# PORT: "3001" → PORT: "3002" 로 변경

# 또는 파일을 수정하고 재적용
# configmap.yaml 파일에서 PORT: "3002"로 변경
kubectl apply -f configmap.yaml

# Pod 재시작 (새로운 설정 적용)
kubectl rollout restart deployment -n volume simple-file-server

# 롤아웃 상태 확인
kubectl rollout status deployment -n volume simple-file-server

# 새로운 Pod에서 환경 변수 확인
POD_NAME=$(kubectl get pod -n volume -l app=simple-file-server -o jsonpath='{.items[0].metadata.name}')
kubectl exec -n volume $POD_NAME -- env | grep PORT
```

**주의**: Service의 포트도 함께 변경해야 합니다! `02-deployment-configmap.yaml`의 포트 섹션을 아래처럼 조정합니다.

```yaml
spec:
  ports:
  - port: 3002
    targetPort: 3002
    nodePort: 30002
```

```bash
# Service 포트 변경 후 재배포
kubectl apply -f deployment-configmap.yaml
curl http://localhost:30002
```

### 5. 여러 환경 설정 관리

#### 개발 환경 (3001번 포트)

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: simple-file-server-config-dev
data:
  PORT: "3001"
  LOG_PATH: "/var/log/app-dev.log"
  ENVIRONMENT: "development"
```

#### 스테이징 환경 (3002번 포트)

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: simple-file-server-config-staging
data:
  PORT: "3002"
  LOG_PATH: "/var/log/app-staging.log"
  ENVIRONMENT: "staging"
```

#### 프로덕션 환경 (3003번 포트)

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: simple-file-server-config-prod
data:
  PORT: "3003"
  LOG_PATH: "/var/log/app-prod.log"
  ENVIRONMENT: "production"
```

Deployment에서 원하는 ConfigMap을 선택:

```yaml
env:
- name: PORT
  valueFrom:
    configMapKeyRef:
      name: simple-file-server-config-dev  # 또는 staging, prod
      key: PORT
```

### 6. ConfigMap 확인 및 디버깅

```bash
# ConfigMap 목록
kubectl get configmap -n volume

# ConfigMap 상세 정보
kubectl describe configmap simple-file-server-config -n volume

# ConfigMap 데이터 확인
kubectl get configmap simple-file-server-config -n volume -o yaml

# Pod에서 환경 변수 확인
kubectl exec -n volume $POD_NAME -- env

# 특정 환경 변수만 확인
kubectl exec -n volume $POD_NAME -- printenv PORT
```

### 7. 정리

```bash
kubectl delete deployment -n volume simple-file-server
kubectl delete service -n volume simple-file-server
kubectl delete configmap -n volume simple-file-server-config
```

### 핵심 정리

✅ **ConfigMap**: 애플리케이션 설정을 코드와 분리

✅ **환경 변수 주입**: `valueFrom.configMapKeyRef` 사용

✅ **이미지 재빌드 불필요**: 설정만 변경하고 Pod 재시작

✅ **다중 환경**: dev, staging, prod 별로 다른 ConfigMap 사용