docker run으로 컨테이너를 실행하면 기본적으로 호스트 CPU와 메모리를 무제한으로 사용합니다. 같은 서버에 여러 컨테이너가 있고 하나에 메모리 누수가 있다면, 그 컨테이너가 점점 메모리를 잠식하다 결국 다른 서비스까지 OOM Kill됩니다. Docker가 컨테이너마다 자원 제한을 강제할 수 있는 이유는 Linux 커널의 cgroups 기능을 사용하기 때문입니다. --cpus 0.5나 -m 256m을 입력하면 Docker는 해당 컨테이너 ID로 cgroup을 만들고 커널에 한도값을 기록합니다. 커널이 직접 이 한도를 강제하기 때문에 컨테이너 안의 프로세스는 제한을 우회할 수 없습니다. 이 ConceptBlock에서는 cgroups가 CPU와 메모리를 격리하는 원리와 Docker 자원 제한 옵션의 동작 방식을 다룹니다.

확대

cgroups(Control Groups)란?

cgroups는 2008년 리눅스 커널 2.6.24에 통합된 기능으로, 프로세스 그룹의 시스템 자원 사용량을 제한, 측정, 격리하는 역할을 합니다. Docker는 컨테이너마다 cgroup을 생성해 자원을 격리합니다.

리눅스 커널의 cgroups가 컨테이너별 자원을 제한합니다.

• /sys/fs/cgroup/cpu/docker/[container_id]/ → cpu.shares, cpu.cfs_quota_us
• /sys/fs/cgroup/memory/docker/[container_id]/ → memory.limit_in_bytes
• /sys/fs/cgroup/blkio/ → 디스크 I/O

컨테이너를 실행하면 Docker는 해당 컨테이너 ID를 이름으로 하는 cgroup을 생성하고, 거기에 자원 제한값을 기록합니다. 커널이 직접 이 값을 읽어서 제한을 강제합니다.

cgroups v1 vs v2

Docker는 두 버전 모두 지원하며, 현대 리눅스 배포판은 대부분 v2를 사용합니다.

Docker 자원 격리의 세 가지 핵심 축

1. CPU 제한 (--cpus, --cpu-shares)

• --cpus: 사용 가능한 CPU 코어 수 (실수 지정 가능)
• --cpu-shares: 상대적 CPU 가중치 (기본값 1024)

2. 메모리 제한 (-m, --memory-swap)

• -m 또는 --memory: 최대 메모리 사용량
• --memory-swap: 스왑 포함 최대 메모리 (기본값: memory의 2배)

3. 블록 I/O 제한 (--blkio-weight)

• 디스크 읽기/쓰기 속도 제어

# 실습 디렉토리 준비
mkdir -p /tmp/docker/part4/exam_13 && cd /tmp/docker/part4/exam_13

# 종합 자원 제한 예시
docker run \
  --cpus 0.5 \          # CPU: 0.5코어 분량
  -m 256m \             # 메모리: 최대 256MB
  --memory-swap 512m \  # 스왑 포함 최대 512MB
  --blkio-weight 300 \  # I/O 가중치 (기본 500)
  nginx

docker run --cpus 0.5 -m 256m nginx 한 줄을 치면 어디선가 이 한도가 실제로 강제됩니다. 그런데 "제한을 걸었다"는 플래그 한 줄이, 컨테이너 안 프로세스가 우회할 수 없는 실제 강제력으로 바뀌기까지는 몇 단계를 거칩니다 — 플래그가 숫자로 변환되고, cgroup에 기록되고, 커널이 매 순간 감시하다가, 초과하면 CPU는 throttle로·메모리는 OOM Killer로 대응합니다. 이 흐름을 알면 "제한을 안 걸었더니 호스트가 잠식됐다", "137로 죽었다(OOMKilled)", "요청이 느닷없이 느려졌다(throttle)", "예약을 걸었는데 왜 안 지켜지지"를 어느 단계 문제인지로 구분할 수 있습니다.

docker run --cpus 0.5 -m 256m nginx
   │
   ① 플래그 파싱 → NanoCpus·Memory 값으로 변환
   │      0.5 → 500000000 nanocpus,   256m → 268435456 bytes
   │
   ② cgroup 생성 + 커널에 한도 기록 (컨테이너 ID 이름의 cgroup)
   │      · cpu.max     ← --cpus (quota/period)
   │      · memory.max  ← -m / --memory
   │
   ③ 커널이 실행 내내 한도를 강제 (컨테이너 안에서는 우회 불가)
   │      · CPU:    quota를 다 쓰면 다음 주기까지 throttle(강제 대기)
   │      · 메모리: 한도 초과 시 먼저 페이지 캐시 회수 시도
   │
   ④ docker stats에 관측: CPU% · MEM USAGE/LIMIT · MEM%
   │
   ⑤ 메모리 회수 실패 → OOM Killer가 SIGKILL → ExitCode 137     → Exited (OOMKilled=true)

각 단계에서 무슨 일이 일어나고, 막히면 어떤 증상인가:

즉 한도는 docker run 플래그에서 시작하지만 실제로 강제하는 것은 커널의 cgroup이라, 컨테이너 안에서는 우회할 수 없습니다. 네 가지 상황이 여기서 갈립니다. 플래그를 아예 안 주면 ②에서 한도가 기록되지 않아 컨테이너가 호스트 전체 자원을 잠식할 수 있고(Noisy Neighbor), 그래서 멀티 테넌트 호스트에서는 모든 컨테이너에 상한을 주는 것이 원칙입니다. --cpus를 너무 낮게 주면 ③의 CPU throttle이 정상 요청까지 지연시켜 타임아웃이 납니다 — cgroup의 cpu.stat에서 nr_throttled가 증가하는지로 확인합니다. 메모리가 한도를 넘어 회수도 실패하면 ⑤에서 OOM Killer가 137로 죽이며, docker inspect의 State.OOMKilled가 true이고 호스트 dmesg에 oom-killer 로그가 함께 남습니다. 마지막으로 Compose의 reservations(예약)를 상한으로 착각하지 마세요 — 예약은 스케줄링 시 최소 보장 힌트일 뿐이고, 실제 상한은 limits(=--cpus·-m)만 강제합니다.

같은 서버에 API 서버, 배치 작업, 모니터링 에이전트가 모두 올라가 있습니다. 어느 날 배치 작업이 대용량 파일 처리를 시작하면서 CPU를 거의 다 점유합니다. API 응답 시간이 갑자기 치솟고 알람이 옵니다. 서버가 죽은 게 아닌데 API가 느려진 이유를 처음엔 찾기 어렵습니다. 자원 제한 없이 컨테이너를 운영하면 이런 Noisy Neighbor 상황이 언제든 발생할 수 있습니다. 각 서비스에 CPU와 메모리 상한을 설정하면 한 컨테이너가 폭주해도 다른 서비스는 보호됩니다. 이 ConceptBlock에서는 자원 제한이 없을 때 실제로 어떤 장애 시나리오가 펼쳐지는지, 그리고 제한값을 얼마로 설정해야 하는지 다룹니다.

확대

Noisy Neighbor: 조용한 재앙

Noisy Neighbor(시끄러운 이웃) 문제는 클라우드와 컨테이너 환경에서 가장 흔한 장애 원인 중 하나입니다. 자원 제한이 없는 환경에서 한 컨테이너가 자원을 독점하면 같은 호스트의 모든 서비스가 영향을 받습니다.

자원 제한 없는 서버 — 재앙 시나리오 (서버 스펙: 4 CPU, 8GB RAM)

• web-service — 정상, 예상 사용: 0.2 CPU, 200MB
• api-service — 정상, 예상 사용: 0.3 CPU, 300MB
• batch-job — 메모리 누수 버그 존재
  • 처음: 100MB → 1시간 후: 2GB → 3시간 후: 7GB ← 서버 전체 RAM 잠식!
  • → web-service 응답 불가, api-service OOM Kill → 서비스 전체 다운!

메모리 누수 컨테이너의 실제 영향

# 자원 제한 없는 컨테이너가 메모리를 계속 점유하는 상황
docker stats --no-stream
# CONTAINER   CPU %   MEM USAGE / LIMIT   MEM %
# batch-job   5.2%    6.8GiB / 7.5GiB     90%  ← 위험!
# web-srv     45.3%   OOM Kill             --   ← 피해자
# api-srv     0.0%    EXIT                 --   ← 피해자

자원 제한으로 격리 보장

# 자원 제한 적용 후
docker run -m 512m --cpus 0.5 batch-job

# 결과: batch-job이 512MB를 초과하면 OOMKilled로 자기 자신만 종료
# web-service와 api-service는 영향 없음

자원 제한 설계 원칙

1. 측정 먼저: docker stats로 정상 부하 시 사용량 파악
2. 여유 있게: 평균 사용량의 1.5~2배로 제한 설정
3. 단계적 적용: 개발 → 스테이징 → 운영 순서로 적용
4. 알림 연동: 자원 사용률 80% 도달 시 경보 발송

앞서 '메모리 제한을 넘으면 OOM'이라고 배웠습니다. 하지만 cgroup이 '사용량'을 무엇으로 세는지를 모르면, docker stats의 MEM%를 잘못 읽고 멀쩡한 컨테이너를 누수로 오진하기 쉽습니다.

• 메모리 사용량 = RSS(익명) + 페이지 캐시(파일): cgroup은 앱이 직접 할당한 익명 메모리(RSS)뿐 아니라, 파일을 읽을 때 커널이 채우는 페이지 캐시까지 한도에 포함해 셉니다. 그래서 파일 I/O가 많은 컨테이너는 힙이 작아도 사용량이 한도 근처까지 올라갑니다.
• 페이지 캐시는 회수 가능(reclaimable)합니다: 메모리 압박이 오면 커널은 OOM으로 죽이기 전에 깨끗한 페이지 캐시를 먼저 비웁니다. 그래서 MEM%가 95%여도 대부분이 캐시라면 OOM은 안 나고 앱도 정상입니다. 반면 RSS(익명)는 스왑이 없으면 회수가 안 돼, 한도까지 차오르면 OOM으로 이어집니다.
• docker stats의 숫자는 오해를 부릅니다: Docker 버전·cgroup 세대에 따라 MEM USAGE에 회수 가능한 캐시가 섞여 부풀려 보일 수 있습니다. 정확한 구분은 docker stats가 아니라 cgroup의 memory.stat(v2의 anon/file, v1의 rss/cache)에서 나옵니다.
• 런타임이 한도를 못 볼 때: 오래된 JVM·Node는 컨테이너의 -m 한도가 아니라 호스트 전체 RAM을 기준으로 힙을 잡습니다. 그래서 -m 512m인데 힙을 그보다 크게 잡아 OOM이 납니다 — -Xmx·--max-old-space-size로 명시하거나 컨테이너 인식이 되는 최신 런타임을 씁니다.

정리하면 '메모리 제한'은 하나의 숫자지만, 그 안은 회수 가능한 캐시와 회수 불가능한 워킹셋으로 나뉩니다. 이 둘을 나눠 봐야 '진짜 누수'와 '정상적인 캐시'를 가릅니다.

Node.js 서비스가 매일 새벽에 갑자기 내려갑니다. 로그는 정상 요청을 처리하다가 중간에 끊깁니다. 에러 메시지도 없습니다. docker ps -a를 보면 Exited (137)입니다. 137은 SIGKILL 시그널로 종료됐다는 의미입니다. docker inspect로 OOMKilled: true를 확인하면 원인이 명확해집니다. 메모리 제한을 초과하자 Linux 커널의 OOM Killer가 프로세스를 강제 종료한 것입니다. 메모리 누수 버그일 수도 있고, 제한값이 너무 낮게 설정된 것일 수도 있습니다. 이 ConceptBlock에서는 OOMKilled 상태를 진단하는 방법과 메모리 swap 옵션 활용 패턴을 다룹니다.

확대

OOMKilled란?

컨테이너가 메모리 제한을 초과하면 Linux 커널의 OOM Killer가 컨테이너 프로세스를 강제 종료합니다. 종료 코드는 137(SIGKILL)입니다.

# OOMKilled 발생 확인
docker inspect my-container --format '{{.State.OOMKilled}}'
# true ← 메모리 부족으로 강제 종료됨

docker inspect my-container --format '{{.State.ExitCode}}'
# 137 ← SIGKILL

# 실시간 메모리 사용량 모니터링
docker stats my-container --no-stream
# CONTAINER      MEM USAGE / LIMIT     MEM %
# my-container   498MiB / 512MiB       97.3%  ← 한계치 근접!

# 모든 컨테이너 실시간 통계
docker stats

메모리 swap 옵션

# -m / --memory: 메모리 제한
docker run -m 512m myapp

# --memory-swap: 메모리 + swap 합산 제한
# 주의: --memory-swap은 메모리+swap 합산값이지, swap 크기가 아님!

docker run -m 512m --memory-swap 512m myapp  # swap 비활성화 (메모리만 512MB)
docker run -m 512m --memory-swap 1g myapp    # 메모리 512MB + swap 512MB
docker run -m 512m --memory-swap -1 myapp    # swap 무제한
# --memory-swap 미지정                        # swap = 메모리 × 2 (기본)

--memory-swap 값 계산:
  메모리 512m + swap 512m = --memory-swap 1g
  (swap 크기 = --memory-swap - --memory)

OOMKilled 대응 방법

# 1. 메모리 제한 증가 (실행 중에도 적용 가능)
docker update --memory 1g my-container

# 2. 메모리 + swap 모두 증가
docker update --memory 1g --memory-swap 2g my-container

# 3. JVM 기반 앱: JVM 힙 크기 제한
docker run -m 1g \
  -e JAVA_OPTS="-Xmx800m -Xms400m" \
  java-app

# 4. Node.js: max-old-space-size 설정
docker run -m 512m \
  -e NODE_OPTIONS="--max-old-space-size=400" \
  node-app

OOM 발생 전 경보 설정

# 간단한 셸 스크립트로 모니터링
watch -n 5 'docker stats --no-stream --format "table {{.Name}}\t{{.MemPerc}}"'

같은 서버에 API 서버와 데이터 집계 배치 작업이 올라가 있습니다. 배치가 실행될 때마다 API 응답이 느려집니다. --cpus로 배치의 CPU 한도를 고정하면 배치가 빨리 끝나지 않더라도 API가 느려지지 않습니다. 반면 낮 시간에는 배치 실행 빈도가 낮아 CPU 여유가 있는데도 --cpus로 묶어두면 낭비가 됩니다. 이런 상황에서는 --cpu-shares로 경합 시 우선순위만 설정하고 평소에는 자유롭게 쓰게 하는 것이 더 효율적입니다. --cpuset-cpus는 특정 코어에 컨테이너를 고정해야 하는 저지연 서비스에 씁니다. 세 옵션은 각자 다른 문제를 해결합니다. 이 ConceptBlock에서는 세 가지 CPU 제한 방식의 동작 원리와 선택 기준을 다룹니다.

확대

세 가지 CPU 제한 방식

CPU를 제한하는 옵션이 세 가지 있으며 각자 역할이 다릅니다.

--cpus: 절대적 사용량 제한

컨테이너가 사용할 수 있는 CPU 코어의 최대량을 고정합니다.

# 최대 1.5개 코어 분량 사용
docker run --cpus 1.5 myapp

# 4코어 서버에서:
# --cpus 1.0 → 전체 CPU의 25% 사용 가능
# --cpus 2.0 → 전체 CPU의 50% 사용 가능
# --cpus 4.0 → 제한 없음 (전체 사용)

--cpu-shares: 경합 시 상대적 우선순위

CPU가 여유 있을 때는 제한이 없고, 경합이 생겼을 때 비율대로 분배합니다.

# 기본값: 1024
# high-priority: 2048 (기본의 2배)
# low-priority: 512 (기본의 절반)

docker run --cpu-shares 2048 --name critical-service myapp   # 고우선순위
docker run --cpu-shares 512  --name batch-worker myapp       # 저우선순위

# 경합 없을 때: 두 컨테이너 모두 필요한 만큼 CPU 사용
# 경합 있을 때: critical-service가 batch-worker의 4배 CPU 받음

--cpuset-cpus: 특정 코어에 고정

컨테이너를 지정한 CPU 코어에만 실행되도록 고정합니다.

# CPU 0번, 1번만 사용 (나머지 코어는 다른 컨테이너용)
docker run --cpuset-cpus "0,1" nginx

# CPU 2번부터 3번 (범위 표기)
docker run --cpuset-cpus "2-3" worker

# CPU 0번 하나만 (단일 코어 격리)
docker run --cpuset-cpus "0" realtime-app

세 옵션 비교표

실전 조합 예시

Docker Compose 버전에 따른 컨테이너 자원 제한 설정 필드 계보

여러 서비스를 유기적으로 연결하고 자원을 안정적으로 통제하기 위해, SRE는 Docker Compose YAML 파일 상에 리소스 상한선(Limits)과 예약 수준(Reservations)을 명세해야 합니다. 이때 Docker Compose 버전에 따라 사용하는 스펙 명세법이 상이하므로 아래의 계보 정리 표를 참조하여 혼란을 방지해야 합니다.

Docker Compose 자원 제한 설정 계보:

version: '3.8'

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    deploy:
      resources:
        limits:
          cpus: '0.5'           # 컨테이너가 사용할 수 있는 최대 CPU 코어 수 (0.5개)
          memory: 512M          # 컨테이너가 쓸 수 있는 최대 메모리 임계치 (mem_limit)
        reservations:
          memory: 256M          # 컨테이너가 보장받을 수 있는 최소 물리 메모리

• 리소스 적용 및 가동: 상위 명세서가 담긴 디렉토리에서 docker-compose up 명령어를 통해 환경을 기동하면, Docker Engine은 cgroups API를 자동으로 호출하여 각 컨테이너 데몬에 물리적 메모리 상한과 CPU 할당 주기를 강제 제어합니다.

# 중요한 API 서버: 최소 2코어 보장 + CPU 0,1에 고정
docker run -d \
  --name api-server \
  --cpus 2.0 \
  --cpuset-cpus "0,1" \
  api:latest

# 배치 작업: CPU 2,3 사용 + 낮은 우선순위
docker run -d \
  --name batch-job \
  --cpus 2.0 \
  --cpuset-cpus "2,3" \
  --cpu-shares 512 \
  batch:latest