컨테이너가 예기치 않게 종료됐을 때 자동으로 다시 뜨게 할 것인지, 어떤 조건에서만 재시작할 것인지를 결정하는 것이 Restart Policy다. 설정 한 줄로 운영 안정성이 크게 달라지기 때문에 의도를 갖고 선택해야 한다. Docker Compose에서는 restart 키로 컨테이너별로 정책을 지정한다.
| 정책 | 재시작 조건 | 수동 docker stop 후 |
|---|---|---|
no | 재시작 안 함 | 재시작 안 함 |
always | 항상 재시작 | 데몬 재시작 시 다시 시작 |
on-failure | exit code가 0이 아닐 때만 | 재시작 안 함 |
unless-stopped | 항상 재시작 | 재시작 안 함 |
exit code: 프로세스가 종료될 때 OS에 반환하는 정수값. 0은 정상 종료, 1 이상은 오류를 의미한다.
컨테이너 종료
|
v
restart 정책 확인
|
+-- no --> 종료 상태 유지
|
+-- always --> 무조건 재시작
|
+-- on-failure --> exit code != 0 ?
| 예 --> 재시작
| 아니오 --> 종료 유지
|
+-- unless-stopped --> 수동 stop 이력 있음?
예 --> 종료 유지
아니오 --> 재시작
always vs unless-stopped두 정책의 차이는 수동으로 컨테이너를 멈췄을 때 나타난다. always는 Docker 데몬이 재시작되면 수동으로 멈춘 컨테이너도 다시 올라온다. unless-stopped는 사용자가 명시적으로 docker stop을 실행했다면 데몬이 재시작되어도 그 상태를 유지한다.
프로덕션에서 특정 서비스를 잠시 내려야 할 때 always이면 서버 재부팅 후 의도치 않게 컨테이너가 다시 뜰 수 있다. 이런 이유로 프로덕션 기본값은 unless-stopped가 권장된다.
on-failure 활용services:
worker:
image: my-worker:latest
restart: on-failure
배치 작업이나 마이그레이션 컨테이너처럼 정상 종료(exit 0)가 예상되는 경우에 적합하다. 작업이 성공하면 재시작하지 않고, 오류로 죽었을 때만 재시도한다. 재시도 횟수는 restart: on-failure:3처럼 제한할 수 없으며, Compose에서는 횟수 제한 없이 무한 재시도한다.
on-failure:N 형식은 docker run --restart on-failure:3 CLI 옵션에서는 지원하지만 Compose의 restart 키에서는 지원하지 않는다. 횟수 제한이 필요하면 deploy.restart_policy를 사용해야 한다.
services:
api:
image: my-api:latest
restart: unless-stopped
db:
image: postgres:16
restart: unless-stopped
migration:
image: my-api:latest
command: ["sh", "-c", "npm run migrate"]
restart: on-failure
개발 중에는 restart: no가 기본값이다. 컨테이너가 죽으면 로그를 확인하고 수동으로 원인을 파악해야 하는 경우가 많기 때문에 자동 재시작이 오히려 방해가 된다. docker compose up 후 컨테이너가 반복 재시작된다면 restart 설정을 확인하는 것이 첫 번째 디버깅 단계다.