TIL - Docker restart 정책 비교 (no / on-failure / always / unless-stopped)

Docker restart 정책 4가지

Docker의 restart 정책은 컨테이너가 종료되었을 때 Docker가 어떻게 동작할지 결정하는 옵션입니다.

정책설명

no	자동 재시작하지 않음 (기본값)
on-failure	비정상 종료(exit code ≠ 0)일 때만 재시작
always	종료 원인과 관계없이 항상 재시작
unless-stopped	항상 재시작하지만 사용자가 수동으로 중지한 경우는 제외

참고

on-failure는 Docker 데몬이 재시작될 당시 비정상 종료 상태였던 컨테이너도 다시 시작합니다.

---

on-failure vs unless-stopped 차이

처음에는 always, on-failure, unless-stopped가 비슷해 보였지만 핵심 차이는 사용자가 docker stop으로 직접 중지한 경우입니다.

 

docker stop omc-keycloak

 

• on-failure → 수동 stop 시 재시작하지 않음 ✅
• unless-stopped → 수동 stop 시 재시작하지 않음 ✅
• always → 수동 stop 직후에는 재시작하지 않음 ✅

여기서 가장 많이 오해하는 부분이 있습니다.

always는 docker stop을 실행했다고 해서 즉시 컨테이너를 다시 실행하지 않습니다.

차이는 Docker 데몬(또는 서버)이 다시 시작될 때 나타납니다.

---

Docker 재시작 시나리오

1. docker stop으로 컨테이너 중지
2. Docker 데몬 재시작 (또는 서버 재부팅)

 

always

docker stop
↓

컨테이너 중지

↓

Docker 재시작

↓

자동으로 다시 시작

 

unless-stopped

docker stop
↓

컨테이너 중지

↓

Docker 재시작

↓

계속 중지 상태 유지

 

즉,

• always → Docker가 다시 시작되면 컨테이너도 다시 시작
• unless-stopped → 사용자가 중지한 상태를 기억하여 다시 시작하지 않음

---

언제 어떤 정책을 사용할까?

상황권장 정책이유

운영 환경 핵심 서비스	always	어떤 상황에서도 항상 서비스가 살아 있어야 함
개발 환경 인프라(DB, Kafka 등)	on-failure	장애 시 자동 복구, 수동 종료는 존중
개발 환경 핵심 서비스(Keycloak 등)	unless-stopped	재부팅 시 자동 시작되지만 수동으로 중지한 상태는 유지
일회성 작업	no	작업 완료 후 종료가 정상

---

on-failure 재시도 횟수 제한

on-failure는 재시도 횟수를 제한할 수 있습니다.

 

docker run --restart=on-failure:3 my-app

 

최대 3번까지 재시도하며, 이후에는 더 이상 자동 재시작하지 않습니다.

docker compose의 restart 옵션은 on-failure:3처럼 재시도 횟수를 지정할 수 없으며, on-failure 정책만 설정할 수 있습니다.

 

restart: on-failure

 

---

이 프로젝트의 적용

현재 프로젝트에서는 다음과 같이 적용했습니다.

• Keycloak → unless-stopped
  • 서버가 재부팅되면 자동 시작
  • 관리 목적으로 docker stop 한 경우에는 그대로 유지
• 그 외 인프라(Kafka, Redis 등) 및 서비스
  → on-failure
  • OOM, 프로세스 크래시 등 비정상 종료 시 자동 복구
  • 개발 중 수동으로 종료한 경우에는 다시 시작하지 않음

---

적용하게 된 이유

부하 테스트 중 Kafka 컨테이너가 OOM(Exit Code 137)으로 종료된 적이 있었습니다.

당시 자동 재시작 정책이 없어 서비스가 중단된 상태를 직접 확인하고 수동으로 다시 실행해야 했습니다.

이 경험을 계기로 비정상 종료는 자동으로 복구하고, 개발 중 의도적인 종료는 존중하는 방향으로 restart 정책을 적용하게 되었습니다.