문제 해결(Troubleshoot)

Docker Hardened Images(DHI)를 마이그레이션하거나 사용할 때 만날 수 있는 디버깅 기법과 일반적인 문제들을 다루는 페이지예요.

출처: 문서

본문

이 페이지는 Docker Hardened Images(DHI)로 마이그레이션하거나 사용할 때 만날 수 있는 디버깅 기법과 일반적인 문제를 다뤄요.

일반 디버깅(General debugging)

Docker Hardened Images는 최소화와 보안을 우선시하므로, 흔한 디버깅 도구(셸이나 패키지 매니저 등)를 의도적으로 제외해요. 따라서 위험을 도입하지 않고 직접 문제를 해결하기는 어려워요. 이를 해결하려면 Docker Debug를 사용할 수 있어요. 원본 이미지를 수정하지 않고 실행 중인 서비스나 이미지에 임시 디버그 컨테이너를 일시적으로 연결하는 안전한 워크플로예요.

이 섹션은 개발 중 Docker Hardened Images를 로컬에서 디버깅하는 방법을 보여줘요. Docker Debug를 사용하면 --host 옵션으로 컨테이너를 원격으로 디버깅할 수도 있어요.

Docker Debug 사용하기

1단계: Hardened Image에서 컨테이너 실행

문제를 시뮬레이션하는 DHI 기반 컨테이너로 시작해요.

$ docker run -d --name myapp dhi.io/python:3.13 python -c "import time; time.sleep(300)"

이 컨테이너에는 셸이나 ps, top, cat 같은 도구가 포함되지 않아요.

다음을 시도하면:

$ docker exec -it myapp sh

다음과 같은 결과를 볼 수 있어요.

exec: "sh": executable file not found in $PATH

2단계: Docker Debug로 컨테이너 검사

docker debug 명령을 사용해 실행 중인 인스턴스에 임시적이고 도구가 풍부한 디버그 컨테이너를 연결해요.

$ docker debug myapp

여기서 실행 중인 프로세스, 네트워크 상태, 마운트된 파일을 검사할 수 있어요.

예를 들어 실행 중인 프로세스를 확인하려면:

$ ps aux

완료되면 exit를 입력해 컨테이너를 나가요.

대안적인 디버깅 접근법

Docker Debug 외에도 DHI 컨테이너 디버깅을 위해 다음 접근법을 사용할 수 있어요.

`-dev` 변형 사용하기

Docker Hardened Images는 셸과 디버깅 도구 설치용 패키지 매니저를 포함한 -dev 변형을 제공해요. 이미지 태그를 -dev로 바꾸기만 하면 돼요.

$ docker run -it --rm dhi.io/python:3.13-dev sh

완료되면 exit를 입력해 컨테이너를 나가요. -dev 변형은 공격 표면을 증가시키므로 프로덕션 환경의 런타임으로는 권장되지 않아요.

이미지 마운트로 디버깅 도구 마운트하기

이미지 마운트(image mount) 기능을 사용해 베이스 이미지를 수정하지 않고 디버깅 도구를 컨테이너에 마운트할 수 있어요.

1단계: 강화 이미지에서 컨테이너 실행

문제를 시뮬레이션하는 DHI 기반 컨테이너로 시작해요.

$ docker run -d --name myapp dhi.io/python:3.13 python -c "import time; time.sleep(300)"

2단계: 컨테이너에 디버깅 도구 마운트

도구가 풍부한 이미지(예: busybox)를 실행 중인 컨테이너의 네임스페이스에 마운트하는 새 컨테이너를 실행해요.

$ docker run --rm -it --pid container:myapp \
  --mount type=image,source=busybox,destination=/dbg,ro \
  dhi.io/python:3.13 /dbg/bin/sh

이 명령은 BusyBox 이미지를 /dbg에 마운트해, 원본 컨테이너 이미지를 변경하지 않으면서 해당 도구에 접근할 수 있게 해줘요. 강화된 Python 이미지에는 표준 유틸리티가 없으므로, 마운트된 도구의 전체 경로를 사용해야 해요.

$ /dbg/bin/ls /
$ /dbg/bin/ps aux
$ /dbg/bin/cat /etc/os-release

완료되면 exit를 입력해 컨테이너를 나가요.

일반적인 문제들(Common issues)

다음은 Docker Hardened Images를 사용할 때 만날 수 있는 특정 문제들과 권장 해결책이에요.

권한(Permissions)

DHI는 보안 강화를 위해 기본적으로 nonroot 사용자로 실행돼요. 이로 인해 파일이나 디렉터리에 접근할 때 권한 문제가 발생할 수 있어요. 애플리케이션 파일과 런타임 디렉터리가 예상된 UID/GID 소유이거나 적절한 권한을 갖도록 보장해요.

DHI가 어떤 사용자로 실행되는지 확인하려면 Docker Hub에서 이미지의 저장소 페이지를 확인해요. 자세한 내용은 View image variant details를 봐요.

권한 있는 포트(Privileged ports)

Nonroot 컨테이너는 기본적으로 1024 미만의 포트에 바인딩할 수 없어요. 이는 컨테이너 런타임과 커널 모두가 강제해요(특히 Kubernetes와 Docker Engine < 20.10).

컨테이너 내부에서 애플리케이션이 권한이 없는 포트(1025 이상)에서 수신하도록 구성해요. 예를 들어 docker run -p 80:8080 my-image는 컨테이너의 포트 8080을 호스트의 포트 80에 매핑해, 루트 권한 없이도 접근할 수 있게 해줘요.

셸 없음(No shell)

런타임 DHI는 sh나 bash 같은 대화형 셸을 생략해요. 빌드나 도구가 셸이 있다고 가정한다면(예: RUN 지시문), 이전 빌드 단계에서 이미지의 dev 변형을 사용하고 최종 아티팩트를 런타임 이미지로 복사해요.

DHI에 어떤 셸이 있는지(있다면) 확인하려면 Docker Hub에서 이미지의 저장소 페이지를 확인해요. 자세한 내용은 View image variant details를 봐요.

또한 실행 중인 컨테이너에 셸 접근이 필요하면 Docker Debug를 사용해요. 자세한 내용은 General debugging을 봐요.

엔트리포인트 차이(Entry point differences)

DHI는 Docker Official Images(DOI)나 다른 커뮤니티 이미지와 다른 엔트리포인트를 정의할 수 있어요.

DHI의 ENTRYPOINT나 CMD를 확인하려면 Docker Hub에서 이미지의 저장소 페이지를 확인해요. 자세한 내용은 View image variant details를 봐요.

패키지 매니저 없음(No package manager)

런타임 Docker Hardened Images는 보안과 최소 공격 표면을 위해 축소되어 있어요. 결과적으로 apk나 apt 같은 패키지 매니저가 포함되지 않아요. 즉, 런타임 이미지에서 추가 소프트웨어를 직접 설치할 수 없어요.

빌드나 애플리케이션 설정이 패키지 설치를 요구한다면(예: 코드 컴파일, 런타임 의존성 설치, 진단 도구 추가), 빌드 단계에서 이미지의 dev 변형을 사용해요. 그런 다음 필요한 아티팩트만 최종 런타임 이미지로 복사해요.

문제 해결(Troubleshoot)