핵심 정리

docker run --memory=512m --cpus=1.5 my-app:latest

문법

어떤 자원 제한을 먼저 떠올리면 되나

제한 없이 실행하면 하나의 컨테이너가 호스트 전체 자원을 점유하는 위험

기본적으로 컨테이너는 명시한 제한이 없으면 호스트 자원을 넓게 사용할 수 있다. 메모리 누수가 있는 앱이나 갑자기 부하가 몰리는 서비스는 같은 호스트에서 실행 중인 다른 컨테이너까지 압박할 수 있다. 멀티 테넌트 환경이나 여러 서비스가 공존하는 서버에서는 자원 한도를 먼저 검토하는 편이 안전하다.

# 제한 없이 실행 → 호스트 메모리 전체 사용 가능
docker run -d my-app

# 제한 설정 → 512MB 초과 시 OOM killer 동작
docker run -d --memory=512m my-app

# 현재 자원 사용량 확인
docker stats

--memory로 메모리 상한을 설정하면 OOM killer가 동작하는 방식

--memory=512m은 커널 cgroup으로 컨테이너의 메모리 사용을 512MB로 제한한다. 제한을 초과하면 커널 OOM(Out of Memory) killer가 컨테이너 안의 프로세스를 강제 종료한다. 컨테이너가 죽으면 restart policy에 따라 재시작된다. --memory-swap을 설정하지 않으면 스왑도 같은 크기만큼 허용된다.

# 메모리 512MB, 스왑 포함 1GB 제한
docker run -d \
  --memory=512m \
  --memory-swap=1g \
  my-app

# OOM 발생 확인 (컨테이너 종료 상태 확인)
docker inspect --format='{{.State.OOMKilled}}' my-app

--cpus로 CPU 할당량을 제한하는 방식 (CFS 스케줄러 기반)

--cpus=1.5는 리눅스 CFS(Completely Fair Scheduler)의 CPU 쿼터로 구현된다. 컨테이너가 사용할 수 있는 CPU 코어 수를 소수점으로 표현한다. 4코어 호스트에서 --cpus=2는 컨테이너가 최대 2코어 분량의 CPU를 사용하도록 제한한다. 100ms 주기 기준으로 사용 시간을 쿼터로 나눠 제어한다.

docker run -d \
  --name worker \
  --cpus=2 \
  --memory=1g \
  my-worker:latest

# CPU 사용률 실시간 확인
docker stats worker

Compose의 resources.limits 설정 패턴

Compose에서는 deploy.resources.limits로 서비스별 자원 한도를 선언할 수 있다. 다만 이 설정은 배포 방식과 Compose 구현에 따라 실제 적용 범위가 다르게 읽힐 수 있으므로, 현재 사용하는 docker compose 버전과 런타임에서 정말 적용되는지 docker inspect나 실제 동작으로 확인하는 편이 안전하다.

services:
  api:
    image: my-api:latest
    deploy:
      resources:
        limits:
          memory: 512m
          cpus: "1.5"
        reservations:
          memory: 256m
          cpus: "0.5"

  worker:
    image: my-worker:latest
    deploy:
      resources:
        limits:
          memory: 2g
          cpus: "4"

메모리 제한과 CPU 제한은 막는 문제가 다르다

메모리 제한은 OOM과 호스트 메모리 압박을 막고, CPU 제한은 한 컨테이너가 코어를 독점하는 상황을 막습니다. 둘을 같이 보는 것이 일반적이지만, 장애 형태는 다릅니다. 메모리가 너무 낮으면 즉시 종료가 반복되고, CPU가 너무 낮으면 앱은 살아 있지만 응답 시간이 길어질 수 있습니다.

체크포인트

주의할 점

docker run --memory=128m --cpus=0.25 my-app

# 메모리는 부족해서 재시작 루프,
# CPU는 너무 낮아 응답이 밀리는 식으로
# 두 제한이 서로 다른 장애를 만들 수 있음