# 실행 가능한 상한: memory 512 MiB, CPU 최대 1.5 core 분량
docker run -d --name api --memory=512m --cpus=1.5 my-app:1.2.3

# physical memory 512 MiB, memory+swap 합계도 512 MiB
docker run -d --name api --memory=512m --memory-swap=512m my-app:1.2.3

# 종료 뒤 OOM kill 여부와 실제 설정 확인
docker inspect --format '{{.State.OOMKilled}} {{.HostConfig.Memory}} {{.HostConfig.NanoCpus}}' api

메모리 제한

Docker Engine에서 제한 없이 실행한 container는 host kernel scheduler가 허용하는 만큼 memory와 CPU를 사용할 수 있습니다. Linux host에서는 memory가 부족해지면 kernel OOM killer가 container process를 포함한 process를 죽여 host 전체가 불안정해질 수 있습니다. --memory의 최소값은 6m이고, 값은 b, k, m, g 단위로 지정합니다.

# hard memory limit
docker run --memory=512m my-app

# soft reservation: host memory pressure가 있을 때만 기준으로 사용
docker run --memory=1g --memory-reservation=512m my-app

--memory-swap은 swap만의 양이 아니라 memory와 swap을 합쳐 허용할 총량입니다. --memory=512m만 주고 host에 swap이 있으면 기본적으로 최대 512 MiB의 swap을 추가로 쓸 수 있습니다. memory와 같은 --memory-swap=512m을 주면 swap을 막고, -1은 host에 있는 swap까지 제한 없이 허용합니다. container 안의 free 출력은 host의 swap을 보일 수 있으므로 이 옵션의 적용 근거로 쓰지 않습니다.

memory limit을 넘으면 반드시 container 전체가 즉시 끝난다고 단정할 수는 없습니다. 어떤 process가 kill되는지와 application이 이를 처리하는 방식에 따라 증상이 다릅니다. container가 종료됐다면 State.OOMKilled, exit code, application log를 함께 봅니다.

CPU 제한

--cpus=1.5는 container가 사용할 수 있는 CPU time의 상한을 1.5 CPU 분량으로 정합니다. Linux CFS scheduler에서는 --cpu-period=100000과 --cpu-quota=150000 조합과 같은 의미입니다. 일반적인 service는 period·quota를 직접 조정하기보다 --cpus를 사용합니다.

# 0.5 CPU 상한: 부하가 지속되면 throttling이 발생할 수 있음
docker run -d --cpus=0.5 my-worker:1.2.3

# 특정 core에만 실행을 제한하는 별도 설정
docker run -d --cpuset-cpus=0-1 my-worker:1.2.3

--cpu-shares는 CPU가 경쟁 중일 때의 상대적 weight일 뿐 사용 상한이나 예약이 아닙니다. 낮은 CPU quota는 process를 죽이지 않지만 request latency·queue 대기·timeout을 늘릴 수 있으므로, CPU 사용률뿐 아니라 응답 시간과 처리량을 함께 측정합니다.

platform과 Compose 검증

Linux Engine은 cgroup과 kernel 기능으로 resource constraint를 적용합니다. Docker Desktop에서는 container가 native macOS·Windows host가 아니라 Linux VM 안에서 실행되므로, docker run limit과 Desktop Settings의 VM CPU·memory allocation을 혼동하면 안 됩니다. VM에 4 GiB만 배정돼 있으면 개별 container limit의 합계가 host 전체 RAM보다 작아도 VM 안에서 먼저 압박이 생길 수 있습니다.

Compose에서는 deploy.resources.limits와 reservations로 원하는 constraint를 선언합니다. Compose Specification은 limits를 platform이 넘지 못하게 해야 한다고 정의하지만, deploy 지원은 implementation마다 선택 사항입니다. 실제 container가 받은 값을 docker inspect, docker stats, load test로 확인합니다.

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