docker exec 사용법 (컨테이너 접속, bash, attach 비교)
솔직히 처음 도커를 쓸 때 저는 컨테이너에 접속하는 방법이 하나인 줄 알았습니다. docker attach만 쓰다가 어느 날 서비스가 통째로 꺼진 뒤에야 “이게 아니구나” 깨달았습니다. docker exec는 실행 중인 컨테이너 안에서 새로운 명령어를 실행하는 명령어로, attach와 비슷해 보이지만 실제 운영 환경에서는 전혀 다른 결과를 만들어냅니다. 어떤 차이가 있는지, 그리고 어떻게 써야 안전한지 제 경험을 바탕으로 정리해봤습니다.
docker attach를 쓰다가 서비스가 꺼진 날
Synology NAS 서버에서 여러 개의 컨테이너를 운영하다 보면, 컨테이너 내부를 직접 들여다봐야 할 순간이 생깁니다. 로그를 보거나, 설정 파일을 수정하거나, 프로세스 상태를 확인해야 할 때입니다. 처음에는 docker attach 명령어를 사용했습니다. docker attach란 이미 실행 중인 컨테이너의 표준 입출력(STDIN/STDOUT)에 그대로 붙어서 들어가는 방식입니다. 쉽게 말해, 컨테이너가 현재 보고 있는 화면에 그대로 접속하는 것입니다.
문제는 빠져나올 때였습니다. attach로 들어간 상태에서 습관적으로 Ctrl+C를 눌렀더니 컨테이너 자체가 꺼져버렸습니다. 웹 서비스가 돌고 있던 컨테이너였는데, 그 순간 운영 중이던 사이트도 같이 내려갔습니다. 제가 직접 겪어보니 이게 단순한 실수가 아니라 attach 명령어의 구조적 특성이라는 걸 알게 됐습니다. attach는 컨테이너의 메인 프로세스(PID 1)에 직접 연결되기 때문에, 그 세션에서 종료 신호를 보내면 컨테이너 자체가 영향을 받습니다.
올바른 빠져나오기 방법이 있긴 합니다. Ctrl+P 다음 Ctrl+Q를 순서대로 누르면 컨테이너를 종료하지 않고 분리(detach)할 수 있습니다. 하지만 솔직히 급할 때 이 키 조합을 매번 기억하기가 쉽지 않았고, 로그를 출력하는 화면에 attach로 들어갔다가 다음에 다시 접속하면 그 로그 화면이 그대로 이어져서 무슨 상황인지 파악이 어려웠습니다. 그래서 결국 docker exec로 완전히 넘어가게 됐습니다.
docker exec로 컨테이너에 안전하게 접속하는 법
docker exec의 기본 구조는 간단합니다. 실행 중인 컨테이너 ID나 이름을 지정하고, 그 뒤에 실행할 명령어를 붙이면 됩니다. 중요한 건 exec로 실행한 프로세스는 컨테이너의 메인 프로세스(PID 1)와는 완전히 별개로 동작한다는 점입니다. 메인 프로세스(Main Process)란 컨테이너가 시작될 때 가장 먼저 실행되고, 이 프로세스가 종료되면 컨테이너 자체도 종료되는 핵심 프로세스를 말합니다.
bash 셸에 접속하려면 -it 옵션을 함께 사용해야 합니다. -i는 인터랙티브 모드(interactive mode)로, 표준 입력을 계속 열어두는 옵션입니다. -t는 TTY(teletypewriter) 할당 옵션으로, 쉽게 말해 일반 터미널처럼 화면 출력을 보기 좋게 만들어주는 역할입니다. 이 둘을 함께 써야 키보드 입력도 되고, 프롬프트도 제대로 표시됩니다.
- 컨테이너 이름 확인: docker ps 또는 docker ps -a 로 실행 중인 컨테이너 목록과 이름을 확인합니다.
- bash 접속: docker exec -it 컨테이너명 bash 를 입력합니다. bash가 없는 이미지라면 sh 로 대체합니다.
- 안전하게 종료: exit 를 입력하면 exec로 실행한 bash만 종료됩니다. 컨테이너 자체는 그대로 살아있습니다.
- 비터미널 환경에서 사용 시: 스크립트나 파이프를 통해 실행할 때는 -t 옵션을 빼고 -i만 사용합니다. -t를 붙이면 cannot attach stdin to a TTY-enabled container because stdin is not a terminal 오류가 발생합니다.
제가 직접 써봤는데, exec로 bash에 들어간 뒤 exit를 쳐도 컨테이너가 꺼지지 않는다는 게 처음에는 신기했습니다. attach를 쓸 때와 달리 마음 편하게 이것저것 확인하고 나올 수 있었습니다. 명령어가 조금 더 길어진다는 단점은 있지만, 운영 중인 서비스가 갑자기 내려가는 것에 비하면 아무것도 아닙니다.
docker exec와 docker run, 어떻게 다를까요
처음 도커를 배울 때 docker run과 docker exec가 헷갈리는 분들이 많습니다. 저도 그랬습니다. docker run이란 이미지를 기반으로 완전히 새로운 컨테이너를 생성하고 실행하는 명령어입니다. 즉, 컨테이너라는 독립된 환경을 처음부터 만드는 역할입니다. 반면 docker exec는 이미 실행 중인 컨테이너 안에서 추가적인 명령어를 실행하는 것입니다. 새로운 컨테이너를 만들지 않고, 기존 환경 안에 잠깐 들어가는 개념입니다.
또 한 가지 중요한 차이가 있습니다. docker run으로 실행한 컨테이너는 표준 출력(STDOUT)과 표준 에러(STDERR)가 도커 로그 시스템으로 기록되어, docker logs 명령어로 확인할 수 있습니다. 하지만 docker exec로 실행한 프로세스는 컨테이너로 취급되지 않기 때문에 로그 추적이나 완료 여부 확인이 상대적으로 어렵습니다. 운영 환경에서 자동화 스크립트를 짤 때 이 차이를 모르면 나중에 디버깅이 상당히 까다로워질 수 있습니다.
공식 문서인 Docker 공식 문서 (docker container exec)에서도 exec는 실행 중인 컨테이너에서만 동작하며, 컨테이너가 정지(stopped) 상태이면 사용할 수 없다고 명시하고 있습니다. 이 점은 운영 중에 실수하기 쉬운 부분이라 특히 기억해두는 게 좋습니다. 실제로 docker stop으로 컨테이너를 멈춘 뒤 exec를 시도하면 Error response from daemon: container is not running 오류가 바로 납니다.
알아두면 쓸모 있는 docker exec 옵션들
기본 접속 외에도 몇 가지 옵션을 알아두면 실무에서 꽤 유용합니다. 먼저 –workdir(-w) 옵션입니다. 워킹 디렉토리(working directory)란 명령어가 실행되는 기준 위치를 말합니다. –workdir /tmp처럼 지정하면, 컨테이너 안에서 해당 경로를 기준으로 명령이 실행됩니다. 특정 디렉토리 안의 파일을 바로 확인해야 할 때 편리합니다.
-e 옵션으로는 환경변수(environment variable)를 추가로 주입할 수 있습니다. 환경변수란 프로세스가 실행될 때 참조하는 설정값으로, 데이터베이스 접속 정보나 API 키처럼 코드 밖에서 값을 전달할 때 씁니다. –env-file 옵션을 사용하면 파일로 여러 환경변수를 한 번에 넘길 수도 있어서, 테스트 환경에서 특히 편합니다.
–user(-u) 옵션도 알아두면 좋습니다. 기본적으로 exec는 컨테이너 이미지에 설정된 사용자 권한으로 실행됩니다. –user node처럼 지정하면 해당 사용자 권한으로 명령어가 실행됩니다. 보안이 중요한 환경에서 root 권한을 최소화할 때 유용합니다. 제 경험상 이 옵션을 모르고 root로만 작업하다가 파일 권한이 꼬이는 경우가 있었는데, 미리 알았더라면 상당한 시간을 아꼈을 것 같습니다.
마지막으로 여러 컨테이너를 운영하다 보면 이름이 기억나지 않는 경우가 생깁니다. 이럴 때는 docker ps -a 명령어가 정답입니다. docker ps -a란 실행 중인 컨테이너뿐 아니라 정지된 컨테이너까지 모두 목록으로 보여주는 명령어입니다. 이름을 확인하고 docker exec -it 컨테이너명 bash를 치면 되는데, 이 두 명령어의 조합이 저에게는 사실상 도커 운영의 기본 루틴이 됐습니다. 참고로 컨테이너 환경에서의 프로세스 격리 원리는 Linux 커널 공식 문서 (namespaces)에서 더 깊이 확인할 수 있습니다.
자주 묻는 질문
Q. docker exec와 docker attach는 어떤 상황에서 각각 써야 하나요?
A. 컨테이너 내부를 탐색하거나 디버깅할 때는 docker exec -it 컨테이너명 bash를 쓰는 것이 안전합니다. docker attach는 컨테이너의 메인 프로세스에 직접 연결되기 때문에, Ctrl+C 같은 실수로 컨테이너 자체가 종료될 위험이 있습니다. 운영 중인 서비스가 있다면 exec를 쓰는 것을 강력히 권장합니다.
Q. docker exec -it로 bash에 접속했는데 “bash: not found” 오류가 납니다. 어떻게 해야 하나요?
A. Alpine Linux 기반 이미지처럼 경량 이미지에는 bash가 기본으로 포함되어 있지 않을 수 있습니다. 이 경우에는 bash 대신 sh를 사용하면 됩니다. docker exec -it 컨테이너명 sh를 입력해보세요. 대부분의 이미지에는 sh는 포함되어 있습니다.
Q. 정지된 컨테이너에도 exec를 쓸 수 있나요?
A. 아닙니다. docker exec는 실행 중인 컨테이너에서만 사용할 수 있습니다. 정지된 컨테이너에 exec를 시도하면 “container is not running” 오류가 발생합니다. 먼저 docker start 컨테이너명으로 컨테이너를 다시 실행한 뒤 exec를 사용하면 됩니다.
Q. 스크립트 안에서 docker exec를 쓸 때 오류가 나는 이유가 뭔가요?
A. 스크립트나 파이프 환경에서는 -t 옵션을 붙이면 “cannot attach stdin to a TTY-enabled container because stdin is not a terminal” 오류가 납니다. 이 경우에는 -t를 빼고 -i만 사용하거나, docker exec 컨테이너명 bash -c “실행할명령어” 형식으로 명령을 직접 넘기는 방식을 쓰면 됩니다.
Q. docker exec로 실행한 프로세스도 docker logs로 볼 수 있나요?
A. 볼 수 없습니다. docker logs는 컨테이너의 메인 프로세스가 출력하는 표준 출력과 표준 에러를 기록합니다. docker exec로 실행한 프로세스는 컨테이너로 취급되지 않기 때문에 로그가 별도로 남지 않습니다. 이 점 때문에 자동화 스크립트를 짤 때는 출력을 별도로 캡처하는 방법을 고려해야 합니다.
docker exec는 명령어 하나 더 타이핑하는 수고를 감수하는 대신, 운영 중인 서비스를 실수로 내리는 최악의 상황을 막아줍니다. attach에서 exec로 습관을 바꾸는 데 저는 일주일도 걸리지 않았고, 그 이후로 컨테이너 때문에 서비스가 갑자기 내려간 적이 없습니다. docker ps -a로 컨테이너 목록을 확인하고, docker exec -it 컨테이너명 bash로 접속하는 두 줄의 흐름을 익혀두면 도커 운영이 훨씬 편안해집니다.
—
참고: https://www.lainyzine.com/ko/article/docker-exec-executing-command-to-running-container/
https://docs.docker.com/reference/cli/docker/container/exec/
https://www.kernel.org/doc/html/latest/admin-guide/namespaces/index.html