Docker 종료 신호가 서버에 닿지 않을 때: ENTRYPOINT와 exec로 SIGTERM 전달하기
시작 스크립트의 exec 유무에 따른 PID와 SIGTERM 수신 차이를 재현한다. JSON ENTRYPOINT와 인자 보존, 실제 컨테이너 종료 검증 범위를 구분한다.
Docker 컨테이너의 서버가 종료 신호를 받지 못한다면 Dockerfile의 JSON 형식뿐 아니라 시작 스크립트의 마지막 exec "$@"도 확인해야 한다. 초기화 뒤 서버 하나를 계속 실행하는 Linux 컨테이너라면 셸을 서버 프로세스로 교체해 신호가 서버에 직접 도달하게 만들 수 있다. 이 글은 Bash에서 PID와 SIGTERM 수신을 재현하고, 실제 컨테이너에서 따로 확인할 종료 조건을 정리한다.
서버를 감싼 반투명 셸이 벗겨지고 신호가 서버에 직접 도달하는 모습을 표현한 개념 일러스트다. 정확한 프로세스 흐름도는 아니다.
작성·문서 확인일은 2026-11-21이다. 재현 환경은 Linux x86_64, GNU Bash 5.2.37, Python 3.12.14다. Docker 데몬에서의 빌드·중지와 PID 1 동작은 이 검증에 포함하지 않았다.
종료 핸들러보다 먼저 신호의 수신 대상을 확인한다
서버에 SIGTERM 핸들러가 있는데도 종료 로그가 남지 않는다면 서버까지 신호가 도착했는지부터 구분해야 한다. Docker stop 문서에 따르면 중지 시 컨테이너의 주 프로세스에 지정된 신호를 보내고, 제한 시간 안에 종료되지 않으면 SIGKILL로 강제 종료한다. 별도 설정이 없을 때 첫 신호는 SIGTERM이다.
ENTRYPOINT ["/app/entrypoint.sh"]라고 썼더라도 스크립트 안에서 서버를 일반 명령으로 실행하면 셸이 부모로 남을 수 있다. Docker의 JSONArgsRecommended 설명은 shell form의 신호 전달 문제와 exec form을 권장하는 이유를 다룬다. Dockerfile의 형식과 스크립트 내부의 실행 방식은 각각 확인해야 한다.
| 실행 방식 | 확인할 프로세스 관계 | 확인 지점 |
| shell form으로 서버 실행 | 셸이 서버의 부모로 남을 수 있다 | 암묵적인 셸이 있는가 |
| JSON 형식으로 스크립트 실행, 내부에서 일반 명령 실행 | 스크립트를 해석하는 셸 아래에 서버가 놓일 수 있다 | 스크립트 마지막 명령은 무엇인가 |
| JSON 형식으로 스크립트 실행, 마지막에 exec 사용 | 성공한 exec가 셸을 서버로 교체한다 | 교체된 프로그램이 종료 신호를 처리하는가 |
exec는 신호를 전달하는 프록시가 아니다. Bash exec 문서의 동작대로 새 프로세스를 만들지 않고 현재 셸을 지정한 프로그램으로 교체한다. 따라서 PID는 유지되고 실행 중인 프로그램이 바뀐다.
마지막 서버 실행을 exec로 바꾼다
다음은 기존 이미지에 통합할 시작 스크립트 예다. 필요한 초기화는 마지막 줄 앞에서 수행한다. 이 스크립트 자체에 실행할 명령이 하나 이상 전달되어야 한다.
Dockerfile에는 다음과 같은 설정을 넣는다. /app/server와 옵션은 해당 이미지에 실제로 존재하는 서버 명령으로 바꿔야 하며, 스크립트는 실행 권한이 있어야 한다. 이 두 줄은 완성된 이미지 빌드 예제가 아닌 통합용 설정 조각이다.
"$@"는 전달받은 각 인자를 유지한다. $*나 따옴표 없는 $@로 바꾸지 않는다. 실제로 위 스크립트의 구문 검사, 명령 누락 시 종료 코드 64, 공백이 있는 인자 a b와 리터럴 * 보존을 로컬 /bin/sh에서 확인했다.
exec 뒤에 셸의 후처리를 붙여도 성공한 교체 뒤에는 실행되지 않는다. 셸의 EXIT trap으로 서버 종료 후 정리를 하던 구조라면 정리 책임을 애플리케이션이나 명시적인 supervisor로 옮길지 먼저 결정해야 한다.
Docker 없이 PID와 SIGTERM 차이를 재현한다
아래 코드를 exec_signal_demo.py로 저장해 python3 exec_signal_demo.py로 실행한다. Linux, Bash, Python 표준 라이브러리만 사용한다. 작업 프로세스는 핸들러 등록을 마친 다음 자신의 PID를 출력한다. 드라이버는 그 준비 신호를 받은 뒤 Popen이 시작한 PID 하나에 SIGTERM을 보낸다. 프로세스 그룹 전체에 보내면 이 차이를 구분할 수 없다.
exec 없는 경로에는 종료 상태를 처리하는 명령을 뒤에 둬서 셸이 남도록 했다. 셸과 명령 형태에 따라 마지막 명령을 최적화할 수 있으므로, 모든 셸이 언제나 같은 트리를 만든다고 가정하지 않는다.
실제로 얻은 출력은 다음과 같다. 비교에 PID 숫자 대신 동일 여부를 사용해 실행마다 바뀌는 값을 제거했다.
첫 경로의 worker received SIGTERM은 래퍼에 보낸 신호가 전달된 결과가 아니다. 드라이버가 살아 있는 작업 프로세스를 확인한 뒤에 작업 PID로 직접 보낸 정리 신호의 결과다. 래퍼의 -15는 Python Popen이 보고하는 SIGTERM 종료 값이며 셸의 $? 표기와 혼동하지 않는다. 두 번째 경로에서는 처음부터 동일한 PID의 작업 프로세스가 신호를 받고 0으로 종료한다.
이 재현은 일반 호스트 프로세스를 사용한다. 컨테이너 PID 1의 기본 신호 처리 규칙이나 컨테이너 전체 정리를 재현한 것이 아니다. 출력이 아주 큰 프로세스의 별도 문제는 기존 글 Python subprocess 파이프 교착과 communicate에서 다룬다.
실제 배포에서는 무엇을 추가로 확인해야 하나
다음은 위 실험 결과가 아니라 실제 이미지에 적용할 검증 순서다.
- 최종 이미지의 ENTRYPOINT와 CMD, 실행 중인 프로세스 트리를 확인한다. 호스트 PID와 컨테이너 내부 PID는 다르므로 같은 숫자라고 가정하지 않는다.
- 서버가 SIGTERM을 명시적으로 처리하는지 확인하고 종료 로그를 남긴다.
exec만 추가했다고 요청 배출이나 저장 완료가 구현되지는 않는다.
- 해당 환경의 stop signal과 제한 시간을 확인한 뒤 중지한다. 신호 수신 로그뿐 아니라 진행 중 요청·큐 작업·파일 저장이 의도한 정책대로 끝나는지도 확인한다.
- 강제 종료 여부와 애플리케이션 종료 코드를 함께 기록한다. 정지에 오래 걸리는 원인은 신호 미도달 외에도 처리 중 작업이나 막힌 I/O일 수 있다.
한 번 초기화한 뒤 서버 하나만 실행하는 구조에는 마지막 exec가 맞다. 여러 장기 실행 프로세스를 백그라운드로 띄우는 구조라면 종료 신호 전달, 자식 회수, 실패 전파를 함께 설계해야 한다. Dockerfile ENTRYPOINT 문서의 프로세스 관리 예도 참고할 수 있다. PID 1은 자식 회수 같은 책임을 갖는다는 점도 고려해야 한다.
이번에 확인한 범위는 두 Bash 실행 경로의 PID 관계와 SIGTERM 수신·종료 코드, 시작 스크립트의 인자 보존이다. Docker·Kubernetes·실제 HTTP 서버의 무중단 종료나 성능 수치는 검증하지 않았다.
English version:
Fix Docker SIGTERM Delivery with an Exec-Form ENTRYPOINT and Shell exec