Docker: Container Exit Code

개요

---

Docker Container의 Exit Code를 정리하고 각 코드의 의미에 대해서 정리한다.

Docker Container Exit Code

---

Docker Container Exit Code란 컨테이너가 종료될 때 “컨테이너가 종료된 원인”을 전달하는데 사용된다.

Exit Code를 통해서 컨테이너 종료의 근본적인 원인을 파악할 수 있다.

Exit Code는 0 ~ 255까지의 범위를 가지며, 125 미만의 코드는 애플리케이션 사이드에서 종료 코드를 설정하고, 125 이상의 코드는 컨테이너나 시스템 레벨에서 발생한 문제이며 코드는 예약되어 있다.

List

Exit Code	Name	Description
Exit Code 0	Purposely stopped	컨테이너가 자동으로 종료됨 (정상 종료)
Exit Code 1	Application error or Invalid Reference	애플리케이션 에러 혹은 컨테이너 이미지에 존재하지 않는 파일 참조
Exit Code 125	Command Execution Issue	도커 명령어 문제로 인한 실행 실패
Exit Code 126	Command Invocation Issue	컨테이너 내에서 실행할 수 없는 명령어 호출한 경우
Exit Code 127	Command Not Found	명령어를 찾을 수 없을 때 발생
Exit Code 128	Invalid argument to exit	유효하지 않은 종료 코드가 호출된 경우
Exit Code 134	Abnormal termination (SIGABRT)	컨테이너가 비정상적으로 자체 종료된 경우 (abort() 호출)
Exit Code 137	Immediate termination (SIGKILL)	컨테이너가 SIGKILL로 인한 강제 종료
Exit Code 139	Segmentation fault (SIGSEGV)	컨테이너가 액세스 권한이 없는 메모리 위치 액세스 시 발생하는 오류
Exit Code 143	Graceful termination (SIGTERM)	운영체제에서 컨테이너를 정상적으로 종료하도록 요청을 받고 정상적으로 종료됨
Exit Code 255	Unknown Error	알 수 없는 종료 코드를 받아 오류 원인 파악 불가

Exit Code 1 (Application Error or Invalid Reference)

• Application Error: 애플리케이션 런타임 시 오류
• Invalid Reference: 이미지에 애플리케이션이 참조하는 라이브러리나 파일이 없는 경우 발생하는 오류
• 해결 방법
  • 컨테이너 로그를 확인해 애플리케이션이 참조하는 파일 경로가 올바른지 확인하거나, 애플리케션 오류를 확인해 문제가 생긴 라이브러리를 디버깅한다.

Exit Code 125 (Command Execution Issue)

컨테이너 실행 시에 도커 커맨드가 정상적으로 실행되지 않음을 의미한다.

• 도커 커맨드가 실패하는 대표적인 이유
  • 올바르지 않은 옵션(플래그) 사용
  • 커맨드 호출 권한이 없는 경우
• 해결 방법
  • 커맨드가정확한 문법으로 호출되는지 확인
  • 컨테이너를 실행하는 유저가 충분한 권한을 가지고 있는지 확인

Exit Code 126 (Command Invocation Issue)

컨테이너 실행 환경 내에서 지정된 커맨드를 호출할 수 없을 때 발생한다. (이미지 빌드 시 커맨드 호출 관련 Dependency 누락 혹은 런타임 환경 호환성 문제)

• 해결 방법
  • 컨테이너 로그 확인을 통해 어떤 커맨드가 호출에 실패하는 지 확인
  • 올바르게 커맨드가 호출되었는지 확인 및 커맨드 호출에 필요한 Dependency 존재하는지 확인

Exit Code 127 (Command Not Found)

컨테이너에서 호출되는 커맨드가 존재하지 않을 때 발생한다.

• 해결 방법
  • 올바르게 커맨드가 호출되었는지 확인 및 컨테이너의 파일 시스템 및 환경 구성 확인

Exit Code 128 (Invalid Argument to Exit)

컨테이너가 정상적으로 종료되었지만 유효하지 않은 종료 코드 (0 ~ 255 범위에 해당하지 않는 코드)를 반환한 경우에 발생한다.

• 해결 방법
  • 유효하지 않은 종료 코드가 호출된 부분을 찾아서 유효한 종료 코드로 변경

Exit Code 134 (Abnormal Termination, SIGABRT)

컨테이너가 SIGABRT 시그널을 수신해서 종료되는 것을 의미한다.

SIGABRT: 프로그램 내부에서 비정상적인 상태를 감지하거나 치명적인 오류가 발생했을 때, 프로그램이 스스로 비정상 종료할 수 있도록 OS가 보내는 신호

• 해결 방법
  • 프로그램 디버깅을 통해 발생 원인을 조사
  • 메모리 관리 문제 혹은 잘못된 메모리 액세스로 인해서 발생할 가능성도 존재하므로 메모리 할당/해제 부분 확인

Exit Code 137 (Immediate Termincation, SIGKILL)

컨테이너가 SIGKILL 시그널을 수신해서 강제 종료되는 것을 의미한다.

Graceful Termincation Period가 적용되지 않고 즉시 프로세스가 종료된다.

SIGKILL: 시스템에서 프로세스를 즉시 중단해야 할 필요가 있을 때 사용되는 신호로서 프로세스가 무시하거나 처리할 수 없다.

• 해결 방법
  • 일반적으로 OOMKilled 상황에서 발생하기 때문에 컨테이너의 메모리 및 CPU 사용량을 확인
  • 컨테이너의 리소스를 적절하게 할당 (OOMKilled → 메모리 용량 증가)

Exit Code 139 (Segmentation Fault, SIGSEGV)

컨테이너가 SIGSEGV 시그널을 수신해서 종료된 것을 의미한다.

SIGSEGV: 운영체제가 잘못된 메모리 접근을 감지했을 때 발생하는 신호로서 프로그램이 할당되지 않은 메모리 영역에 접근하거나 읽기/쓰기 권한이 없는 메모리 영역 접근 시 발생된다.

• 해결 방법
  • 일반적으로 해제된 메모리 재참조, 잘못된 초기화 등 메모리 관련 오류이기 때문에 프로그램 상에서 잘못된 메모리 접근이 일어나는 부분을 찾아 픽스

Exit Code 143 (Graceful Termination, SIGTERM)

컨테이너가 SIGTERM 시그널을 수신하고 정상 종료되는 것을 의미한다.

SIGTERM: 프로세스가 처리할 수 있는 시그널로 시그널을 수신한 프로세스는 핸들러를 통해 리소스 정리, 및 안정적인 종료 프로세스를 거칠 수 있다.

 

SIGTERM 시그널 수신 이후에 정상적으로 파일 및 리소스 정리를 하는지 로깅 등을 통해 확인할 수 있다.

 

쿠버네티스의 경우 terminationGracePeriodSeconds와 같은 옵션 지정을 통해 프로세스가 안정적으로 종료되도록 SIGKILL을 수신하는 시간을 유예할 수 있다.

마무리

---

 

컨테이너의 Exit Code에 대해서 정리해봤다.

 

쿠버네티스 환경에선 여러 가지 사유로 인해 컨테이너가 종료되는 케이스가 많은데 Exit Code를 정리함으로써 해당 이슈가 발생한 원인에 대한 방향성을 확인할 수 있다고 생각한다.

Reference

---

k8s for Data Engineer - Container Exit Codes: https://asrathore08.medium.com/k8s-for-data-engineer-container-exit-codes-59b28674996d

Exit Codes in Docker and Kubernetes: https://komodor.com/learn/exit-codes-in-containers-and-kubernetes-the-complete-guide/

Docker Documentation: https://docs.docker.com/engine/containers/run/#exit-status

Running containers

 

Exit Codes in Docker and Kubernetes: The Complete Guide

 

K8s for Data Engineer — Container exit codes