"Docker" 태그로 연결된 2개 게시물개의 게시물이 있습니다.

docker run --memory=512m을 실행할 때, Kubernetes 매니페스트에 resources.limits.memory를 적을 때, systemd 유닛에 MemoryMax=를 넣을 때. 이 셋이 결국 같은 커널 기능 하나로 내려간다는 걸 알고 계셨나요. 컨테이너 시대의 자원 통제는 전부 cgroup 위에 서 있어요.

systemd 유닛 11종을 돌아본 글에서 cgroup을 여러 번 스쳐 지나갔는데, 정작 cgroup 자체를 정면으로 다룬 적이 없었습니다. 이번에 채웁니다.

cgroup은 무엇인가​

cgroup(control group)은 프로세스들을 무리(group)로 묶고, 그 무리 단위로 자원을 통제하고 계량하는 커널 기능입니다. 하는 일은 세 가지로 요약됩니다.

핵심은 대상이 프로세스 하나가 아니라 무리라는 점입니다. ulimit 같은 전통 도구는 프로세스 단위라서, 프로세스가 fork하면 통제를 벗어납니다. cgroup은 자식 프로세스가 부모의 cgroup을 물려받으므로 fork로 도망칠 수 없습니다. 컨테이너가 "안에서 뭘 몇 개 띄우든 전체 512MB"라는 약속을 지킬 수 있는 이유입니다.

구현 형태는 파일시스템입니다. /sys/fs/cgroup 아래 디렉터리 하나가 cgroup 하나이고, 디렉터리를 만들면 cgroup이 생기고, 그 안의 파일에 값을 쓰면 제한이 걸립니다. 시스템 콜 API가 아니라 mkdir와 echo로 조작하는 커널 기능이라는 점이 cgroup의 성격을 잘 보여줍니다.

계보를 짧게 짚으면, 2006년 Google 엔지니어들이 "process containers"라는 이름으로 시작해 2008년 커널 2.6.24에 cgroup이라는 이름으로 병합됐습니다. 이후 LXC와 Docker가 이 위에 컨테이너를 지었고, systemd는 서비스 관리의 뼈대로 삼았습니다.

v1의 혼돈, v2의 단일 트리​

cgroup을 검색하면 v1과 v2 이야기가 반드시 나옵니다. 이 구분을 모르면 검색 결과의 절반이 내 시스템과 안 맞는 이유를 알 수 없습니다.

v1의 설계는 유연함이 지나쳤습니다. 컨트롤러(memory, cpu, blkio 등)마다 각자 독립된 트리를 가질 수 있었습니다. 한 프로세스가 memory 트리에서는 A 그룹, cpu 트리에서는 B 그룹에 속하는 것이 가능했다는 뜻입니다. 표현력은 높지만 대가가 컸습니다. 트리끼리 조합이 어긋나면 동작을 예측하기 어렵고, 컨트롤러마다 인터페이스 관례가 제각각이었으며, 권한 위임 규칙도 정리되어 있지 않았습니다.

v2는 2016년 커널 4.5에서 이 혼돈을 정리했습니다. 원칙은 하나입니다. 트리는 하나, 모든 컨트롤러는 그 트리 위에서 동작한다(unified hierarchy).

인터페이스도 통일됐습니다. 어느 cgroup 디렉터리든 같은 규칙의 파일들이 있습니다.

• cgroup.procs: 이 무리에 속한 PID 목록. 여기에 PID를 쓰면 편입
• cgroup.controllers: 이 지점에서 쓸 수 있는 컨트롤러
• memory.max, cpu.max, io.max, pids.max: 컨트롤러별 상한
• memory.events: OOM 발생 횟수 같은 사건 카운터

v2에만 있는 물건도 생겼습니다. PSI(Pressure Stall Information)입니다. memory.pressure, cpu.pressure, io.pressure 파일이 "이 무리의 프로세스들이 자원을 못 받아 지연된 시간의 비율"을 보여줍니다. 사용량이 아니라 부족으로 인한 고통을 직접 재는 지표라서, 사용률 그래프보다 정직할 때가 많습니다.

전환은 배포판 기본값으로 이미 끝난 이야기입니다. Fedora 31(2019)을 시작으로 Ubuntu 21.10, Debian 11, RHEL 9가 v2를 기본으로 켰고, Docker는 20.10부터, Kubernetes는 1.25에서 v2 지원을 GA로 올렸습니다. 지금 새로 만나는 시스템은 거의 v2라고 봐도 됩니다. 내 시스템 확인은 한 줄입니다.

stat -fc %T /sys/fs/cgroup/
# cgroup2fs 면 v2, tmpfs 면 v1

실험: 64MB 국경에 100MB를 밀어 넣으면​

개념은 여기까지 하고, 직접 확인해 보겠습니다. macOS라서 Docker 컨테이너(Linux VM) 안에서 실험했습니다. 컨테이너 자체가 cgroup으로 만들어지니 오히려 좋은 교보재입니다.

먼저 --memory=64m이 정말 cgroup 파일로 내려가는지 확인합니다.

$ docker run --rm --memory=64m alpine cat /sys/fs/cgroup/memory.max
67108864

67108864 바이트, 정확히 64MiB입니다. Docker 플래그는 커널에 도달하면 memory.max 파일의 숫자 하나가 됩니다. 이제 이 국경 안에서 100MB를 할당해 봅니다.

$ docker run --rm --memory=64m alpine sh -c 'head -c 100m /dev/zero | tail'
Killed
# 종료 코드 137 (128 + SIGKILL 9)

tail은 입력을 메모리에 쌓는 성질이 있어 간단한 메모리 포식자로 쓸 수 있습니다. 64MiB 상한을 넘는 순간 커널 OOM killer가 그 cgroup 안에서 희생자를 골라 SIGKILL을 보냅니다. 시그널 글에서 다룬 137이라는 종료 코드가 여기서 나옵니다.

죽인 흔적은 사건 카운터에 남습니다. 같은 컨테이너에서 OOM을 겪은 직후 memory.events를 읽으면 이렇습니다.

$ cat /sys/fs/cgroup/memory.events
low 0
high 0
max 72
oom 3
oom_kill 1
oom_group_kill 0

$ cat /sys/fs/cgroup/memory.peak
67108864

읽는 법이 흥미롭습니다. max 72는 사용량이 상한선에 부딪힌 횟수입니다. 부딪힐 때마다 커널은 먼저 page 회수(reclaim)로 버텨 봅니다. 그래도 안 되면 oom(3회)으로 넘어가고, 최종적으로 프로세스 하나를 죽였습니다(oom_kill 1). memory.peak가 정확히 67108864, 즉 상한과 같다는 것은 국경까지 꽉 채우고 넘지 못했다는 증거입니다. 상한 초과가 아니라 상한 도달 후 처형이라는 순서가 파일에 그대로 남습니다.

컨테이너 없이 맨 리눅스에서 같은 실험을 하려면 systemd가 지름길입니다.

# 임시 scope 유닛으로 감싸서 실행, 상한 64M
systemd-run --scope -p MemoryMax=64M some-command

# 서비스라면 유닛 파일에
[Service]
MemoryMax=64M

systemd 유닛은 각자 cgroup 하나씩을 차지하므로, MemoryMax=는 결국 그 cgroup의 memory.max에 값을 쓰는 것입니다. 트리 전체는 systemd-cgls로, 무리별 실시간 사용량은 systemd-cgtop으로 봅니다.

운영자가 기억할 세 가지​

첫째, 모든 상위 도구의 제한은 cgroup 파일로 환원됩니다. Docker 플래그든, Kubernetes limits든, systemd 지시자든, 디버깅의 종착지는 /sys/fs/cgroup 아래 파일입니다. 제한이 이상하게 동작하면 도구의 문서보다 그 파일의 실제 값을 먼저 확인하는 쪽이 빠릅니다.

둘째, cgroup의 메모리 계정에는 page cache가 포함됩니다. memory.max는 프로세스의 anonymous 메모리만 세는 것이 아니라, 그 무리가 일으킨 파일 캐시까지 셉니다. 파일을 많이 읽는 워크로드(백업, 대량 스캔, 그리고 데이터베이스)가 "실제 사용량은 얼마 안 되는데" OOM에 몰리는 전형적인 이유입니다. 캐시는 압박이 오면 회수되므로 보통은 문제가 없지만, 회수 속도가 할당 속도를 못 따라가는 순간이 있습니다. 컨테이너 위 PostgreSQL의 메모리 제한 설정은 이 지점이 본론이라, 각도를 잡아 후속 글에서 따로 다루겠습니다.

셋째, v2의 사건 카운터와 PSI를 감시 지표로 쓸 수 있습니다. memory.events의 max와 oom_kill, 그리고 memory.pressure는 "제한에 얼마나 자주 부딪히고 있는가"를 알려주는 조기 경보입니다. OOM으로 죽고 나서 아는 것과, max 카운터가 오르는 걸 보고 미리 아는 것의 차이입니다.

여담 하나로 마무리할게요. 이 글을 쓰게 된 계기는 Claude Code가 Bash 명령에 cgroup 메모리 제한을 거는 옵션을 넣었다는 소식이었어요. AI 에이전트가 실행하는 명령의 폭주를 막는 안전장치로 2008년의 커널 기능이 다시 불려 나오는 것, cgroup이 여전히 현역 국경 수비대라는 좋은 증거 아닐까요.

참고 자료​

• 커널 문서: Control Group v2
• systemd.resource-control 매뉴얼
• PSI - Pressure Stall Information

오래된 주제와 새로운 무대​

유닉스 시그널은 운영체제 수업 첫 단원에서 가볍게 훑고 지나가는 주제예요. 그런데 Docker, Kubernetes, systemd, PM2 같은 프로세스 오케스트레이터들이 일상이 된 지금, 이 네 개의 시그널은 오히려 운영 사고의 주요 원인이 되고 있어요.

• "Docker stop을 했는데 왜 10초 뒤에야 죽나요?"
• "K8s rolling update 중 request가 잘립니다"
• "Ctrl+C가 안 먹히는데 뭐가 잘못됐죠?"
• "nohup으로 돌렸는데 SSH 끊기니까 죽었어요"

전부 시그널 이해와 직결된 질문입니다. 한 번 제대로 정리해두면 두고두고 도움이 됩니다.

네 시그널 개요​

핵심 차이는 마지막 칼럼인 핸들 가능 여부입니다. SIGKILL만 프로세스가 가로챌 수 없습니다. 이것이 왜 중요한지는 뒤에서 자세히 살펴봅니다.

SIGINT​

SIGINT는 우리가 가장 자주 만나는 시그널입니다.

터미널에서 Ctrl+C를 누르면 현재 포그라운드 프로세스 그룹에 SIGINT가 날아갑니다. "사용자 인터럽트"의 약자로 interrupt에서 왔습니다.

프로세스는 이 시그널을 받으면 다음과 같이 동작합니다.

• 기본적으로는 즉시 종료
• 핸들러를 등록하면 정리 후 종료 가능 (열린 파일, DB 트랜잭션 롤백 등)
• 완전히 무시할 수도 있음 (일부 REPL이 이렇게 동작)

Ctrl+C가 안 먹는 경우들​

• 자식 프로세스가 별도 세션으로 분리돼 있을 때 (setsid)
• 프로세스가 I/O 블록 상태(디스크, 네트워크)라 인터럽트 후에도 시스템 콜 복귀가 늦을 때
• 핸들러가 SIGINT를 잡아놓고 일부러 안 끝낼 때
• TUI 앱(vim, tmux 등)이 터미널 raw 모드로 Ctrl+C를 키 입력으로 받아먹을 때

Ctrl+C가 안 먹히면 보통 SIGTERM을 쏴보는 게 다음 수순입니다. kill PID (기본값이 SIGTERM).

SIGTERM​

SIGTERM은 정중한 종료 요청이며, 가장 중요한 시그널이자 현대 운영 환경의 기본 종료 경로입니다.

kill PID를 인자 없이 쓰면 기본이 SIGTERM입니다. docker stop CONTAINER는 컨테이너 PID 1에 SIGTERM을 전송하고, Kubernetes의 Pod 종료가 시작될 때도 각 컨테이너에 SIGTERM을 보냅니다. systemd가 unit을 멈출 때와 PM2, foreman, supervisor 등 프로세스 매니저가 stop할 때도 기본 시그널은 SIGTERM입니다.

SIGTERM은 "그만 종료해 주세요" 라는 의사 표현입니다. 프로세스가 이 시그널을 캐치할 수 있고, 원하는 시간 동안 정리할 수 있습니다.

Graceful shutdown 패턴 (Go 예제)​

프로덕션 서버가 SIGTERM을 받았을 때 해야 할 일은 대체로 다음과 같습니다.

1. 신규 요청 수신을 중단
2. 진행 중인 요청을 완료할 때까지 기다림
3. DB 커넥션, 파일, 임시 자원 정리
4. 종료

Go 1.16+에서 signal.NotifyContext를 쓰면 깔끔합니다.

package main

import (
    "context"
    "log"
    "net/http"
    "os/signal"
    "syscall"
    "time"
)

func main() {
    ctx, stop := signal.NotifyContext(context.Background(),
        syscall.SIGINT, syscall.SIGTERM)
    defer stop()

    srv := &http.Server{Addr: ":8080"}

    go func() {
        if err := srv.ListenAndServe(); err != http.ErrServerClosed {
            log.Fatal(err)
        }
    }()

    <-ctx.Done() // SIGINT/SIGTERM 대기

    shutdownCtx, cancel := context.WithTimeout(context.Background(), 25*time.Second)
    defer cancel()

    if err := srv.Shutdown(shutdownCtx); err != nil {
        log.Printf("shutdown error: %v", err)
    }
    log.Println("bye")
}

25초 타임아웃은 K8s 기본 grace period(30초)보다 살짝 짧게 잡는 것이 관행입니다. grace period 안에 정리를 끝내고 자진 종료하기 위해서입니다.

Node.js 예제​

const server = app.listen(3000)

const shutdown = (signal) => async () => {
  console.log(`${signal} 수신, 정리 중...`)
  server.close(() => process.exit(0))
  // 25초 지나도 종료 안 되면 강제
  setTimeout(() => process.exit(1), 25_000).unref()
}

process.on('SIGTERM', shutdown('SIGTERM'))
process.on('SIGINT',  shutdown('SIGINT'))

Python 예제​

import signal, sys, time

def shutdown(signum, frame):
    print(f"signal {signum} 수신, 정리 중...")
    # cleanup code here
    sys.exit(0)

signal.signal(signal.SIGTERM, shutdown)
signal.signal(signal.SIGINT,  shutdown)

while True:
    time.sleep(1)

SIGKILL​

SIGKILL을 아껴 써야 하는 이유가 있습니다. kill -9 PID는 개발자들의 오랜 습관입니다 — 하지만 프로세스에게 정리할 기회를 주지 않습니다.

• 커널이 프로세스를 즉시 종료
• 프로세스는 시그널을 캐치하거나 무시하거나 핸들러를 등록할 수 없다 (불가능)
• DB 커넥션이 절반만 닫힌 상태로 방치, 파일이 잠금 해제되지 않은 채 남을 수 있음
• 쓰기 중이던 데이터가 flush 안 된 상태로 증발

쓸 만한 때​

• SIGTERM을 보냈는데 충분히 기다린 뒤에도 안 죽음 (핸들러 무한 루프 등)
• Docker grace period 초과 → Docker가 자동으로 SIGKILL 전송
• K8s grace period 초과 → kubelet이 SIGKILL
• OOM killer가 메모리 확보 위해 희생자로 선정

즉 순서는 항상 SIGTERM → 대기 → (안 되면) SIGKILL입니다. 처음부터 kill -9로 가는 것은 게으름이거나 데이터 손상 리스크를 감수하는 행위입니다.

SIGHUP​

SIGHUP은 의미가 뒤집힌 시그널입니다. 이름 그대로 "HangUp"에서 왔습니다. 1970년대 전화 연결이 끊기면 모뎀이 보내주던 신호입니다. 지금은 그 용도가 거의 사라졌지만 두 가지로 남아 있습니다.

의미 1: 터미널 세션 종료​

SSH로 원격 서버에 접속해서 명령을 실행하고 접속을 끊으면, 그 자식 프로세스들에 SIGHUP이 갑니다. 기본 동작은 종료입니다.

그래서 이를 피하는 도구들이 생겼습니다. nohup은 SIGHUP 무시 플래그를 설정하고 실행하는 "no hup"이고, disown은 셸의 job 테이블에서 프로세스를 제거해 SIGHUP 전파를 끊습니다. setsid는 새 세션을 만들어 터미널과의 연결 자체를 분리합니다. tmux나 screen은 결이 조금 다른데, 세션을 원격 호스트의 상주 데몬이 잡고 있어 클라이언트 연결이 끊겨도 프로세스가 유지됩니다.

주의: nohup은 SIGHUP만 막습니다. SIGTERM, SIGKILL은 그대로 받습니다. 시스템 재부팅/종료 때도 보호하지 못합니다.

의미 2: 설정 리로드 관용​

현대 데몬들은 SIGHUP을 "설정 다시 읽어라"라는 신호로 재해석해서 씁니다. 공식 표준은 아니지만 사실상 관례입니다. 대표적인 예가 nginx입니다. kill -HUP이나 nginx -s reload를 받으면 마스터가 새 설정으로 워커를 띄우고 기존 워커는 현재 연결이 끝나면 종료합니다. rsyslog/syslog-ng도 같은 방식으로 설정을 리로드하고, haproxy도 리로드용으로 씁니다(최근 버전은 seamless-reload를 따로 둡니다). postgres 역시 pg_reload_conf()나 kill -HUP postmaster로 설정을 다시 읽습니다.

HUP의 원래 의미와는 전혀 상관없는 용도인데, 이제는 이쪽이 더 유명합니다.

쿠버네티스의 Termination 시퀀스​

K8s에서 Pod를 지우면 내부적으로 다음 순서로 돕니다.

1. Pod의 status가 Terminating으로 변경
2. 서비스의 endpoint에서 해당 Pod 제거 (신규 트래픽 차단)
3. preStop hook 실행 (정의돼 있다면)
4. 각 컨테이너의 PID 1에 SIGTERM 전송
5. Termination grace period (기본 30초) 대기
6. 그래도 살아 있으면 SIGKILL

여기서 3번 preStop과 4번 SIGTERM 사이의 순서가 중요합니다. 많은 이가 preStop이 먼저 실행되고 그 끝에 SIGTERM이 간다고 오해하는데, 실제로는 둘이 사실상 동시에 시작됩니다(preStop은 먼저 호출되지만 SIGTERM 전송을 막지 않는다는 것이 정확한 표현입니다). preStop은 주로 "LB에서 빠질 시간을 벌기" 같은 용도로 사용합니다.

grace period 설정​

spec:
  terminationGracePeriodSeconds: 60
  containers:
  - name: app
    # ...
    lifecycle:
      preStop:
        exec:
          command: ["sleep", "10"]  # LB가 endpoint 제거를 반영할 시간

앱 내부의 graceful shutdown 타임아웃은 이 값보다 짧게 잡습니다.

흔한 함정들​

Dockerfile의 shell form ENTRYPOINT​

# 나쁜 예 — /bin/sh가 PID 1이 되어 SIGTERM을 흡수
CMD node server.js

# 좋은 예 — node가 직접 PID 1
CMD ["node", "server.js"]

shell form(문자열)은 sh -c로 감싸져 실행되는데, sh는 기본적으로 시그널을 자식에게 전파하지 않습니다. docker stop이 SIGTERM을 PID 1(sh)에 보내지만 실제 앱은 그것을 받지 못합니다. 결국 10초를 기다렸다가 SIGKILL로 박살납니다.

긴 preStop을 graceful shutdown 대체용으로 쓰지 말 것​

preStop: sleep 60 같은 것으로 "종료 시간을 버는" 것은 꼼수에 가깝습니다. 앱이 실제로 정리하는 것이 아니라 단지 종료를 늦출 뿐입니다. 제대로 된 해법은 앱에 SIGTERM 핸들러를 두는 것입니다.

Python의 KeyboardInterrupt는 SIGINT만​

try/except KeyboardInterrupt는 SIGINT만 잡습니다. SIGTERM은 안 잡힙니다. 컨테이너에서 돌리는 Python이면 반드시 signal.signal(signal.SIGTERM, ...)을 등록해야 합니다.

Node.js에서 동기 블로킹 작업​

이벤트 루프를 오래 점유하는 동기 작업(큰 파일 sync read, 무거운 crypto 연산 등)은 process.on('SIGTERM', ...) 핸들러조차 실행하지 못합니다. Node 프로세스가 시그널을 처리할 기회를 얻지 못하기 때문입니다. graceful shutdown이 의미 있으려면 이벤트 루프를 풀어주는 코드여야 합니다.

nohup 과신​

nohup long_task.sh &로 돌려놓았다고 "이제 안전하다"라고 여기기 쉽지만, SIGHUP만 막습니다. reboot나 SIGTERM 앞에서는 무력합니다. 장기 작업은 systemd 유닛이나 tmux 세션 쪽이 더 안전합니다.

한 줄로​

"SIGTERM을 잡을 줄 아는 코드"와 "SIGTERM을 쏠 줄 아는 운영자"가 만나면 SIGKILL이 필요 없는 날이 많아져요. 컨테이너 오케스트레이션 시대에 이 오래된 주제가 다시 중요해진 이유는 결국 이것이에요.

참고​

• SIGKILL vs SIGTERM: Master Process Termination in Linux and Kubernetes, SUSE
• Kubernetes best practices: terminating with grace, Google Cloud
• Graceful Shutdown in Go: Practical Patterns, VictoriaMetrics
• Kubernetes: containers, and the "lost" SIGTERM signals, ITNEXT
• SIGHUP for Configuration Reload, linuxvox
• How to Use the nohup Command in Linux, DigitalOcean