Docker 컨테이너와 호스트 파일 시스템 연결: docker cp 활용법

Docker 컨테이너는 격리된 환경을 제공하여 애플리케이션을 안정적으로 실행할 수 있게 해주는 강력한 기술입니다. 이러한 격리성은 보안과 재현성 측면에서 큰 장점을 가지지만, 때로는 호스트 머신과 컨테이너 간에 파일을 주고받아야 하는 상황이 발생합니다. 예를 들어, 컨테이너 내부에서 생성된 로그 파일을 호스트로 가져와 분석하거나, 호스트에 있는 설정 파일을 실행 중인 컨테이너에 긴급하게 적용해야 할 수 있습니다. 바로 이때 사용되는 명령어가 docker cp입니다.

docker cp는 호스트 파일 시스템과 컨테이너 파일 시스템 사이의 데이터 전송을 위한 다리 역할을 하는 유틸리티입니다. 이는 Docker 볼륨이나 바인드 마운트처럼 영구적인 데이터 공유를 위한 솔루션과는 성격이 다릅니다. 볼륨이나 마운트가 컨테이너의 생명주기와 독립적으로 데이터를 관리하거나 실시간으로 디렉터리를 동기화하는 데 중점을 둔다면, docker cp는 일회성, 임시적인 파일 복사 작업에 특화되어 있습니다. 이 글에서는 docker cp 명령어의 기본적인 사용법부터 고급 옵션, 내부 동작 원리, 그리고 실제 시나리오에서의 현명한 활용 전략까지 심도 있게 다룹니다.

docker cp 명령어의 핵심 구문 이해

docker cp 명령어의 구문은 직관적이며, Unix/Linux의 cp 명령어와 유사한 구조를 가집니다. 데이터의 흐름 방향에 따라 두 가지 형태로 사용할 수 있습니다.

1. 호스트에서 컨테이너로 복사:

docker cp [OPTIONS] SRC_PATH CONTAINER:DEST_PATH

2. 컨테이너에서 호스트로 복사:

docker cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH

각 구성 요소는 다음과 같은 의미를 가집니다.

• [OPTIONS]: 복사 동작을 제어하는 추가 옵션입니다. 잠시 후 자세히 살펴보겠습니다.
• SRC_PATH (소스 경로): 복사할 원본 파일 또는 디렉터리의 경로입니다. 호스트의 경로일 수도 있고, 컨테이너 내부의 경로일 수도 있습니다.
• DEST_PATH (대상 경로): 파일 또는 디렉터리가 복사될 목적지 경로입니다.
• CONTAINER: 파일을 주고받을 대상 컨테이너의 이름(name) 또는 ID입니다. 실행 중인 컨테이너는 물론, 중지된 컨테이너도 지정할 수 있다는 점이 매우 유용합니다.

경로를 지정할 때, 컨테이너 내부의 경로임을 명시하기 위해 <CONTAINER>:<PATH> 형식을 사용합니다. 콜론(:)이 호스트와 컨테이너 경로를 구분하는 중요한 구분자 역할을 합니다.

docker cp의 강력한 옵션들

docker cp는 단순한 파일 복사 기능을 넘어, 두 가지 유용한 옵션을 제공하여 복사 과정을 더 세밀하게 제어할 수 있도록 돕습니다.

-a 또는 --archive: 아카이브 모드

이 옵션은 단순히 디렉터리를 재귀적으로 복사하는 것 이상의 의미를 가집니다. -a 옵션을 사용하면 복사 과정에서 파일의 메타데이터, 특히 소유권(UID/GID) 정보가 그대로 보존됩니다. 이는 리눅스 시스템에서 파일 권한이 매우 중요한 경우에 필수적인 옵션입니다.

예를 들어, 특정 사용자(예: www-data) 권한으로 실행되어야 하는 웹 애플리케이션의 설정 파일을 컨테이너로 복사할 때, 이 옵션 없이 복사하면 파일이 컨테이너 내부에서 root 소유로 생성될 수 있습니다. 이로 인해 애플리케이션이 설정 파일을 읽지 못하는 권한 문제가 발생할 수 있습니다. -a 옵션은 이러한 문제를 방지하고 원본 파일의 소유권과 권한을 최대한 유지시켜 줍니다.

-L 또는 --follow-link: 심볼릭 링크 처리

소스 경로에 심볼릭 링크(Symbolic Link, 바로 가기)가 포함된 경우, 이 옵션은 복사 동작을 결정합니다.

• 기본 동작 (-L 옵션 미사용 시): docker cp는 심볼릭 링크 자체를 복사합니다. 즉, 목적지에도 원본과 동일한 심볼릭 링크가 생성됩니다. 만약 이 링크가 가리키는 실제 파일이 컨테이너 내부에 없다면, 이 링크는 깨진 링크(broken link)가 됩니다.
• -L 옵션 사용 시: docker cp는 심볼릭 링크를 따라가서 링크가 가리키는 원본 파일이나 디렉터리를 복사합니다. 이는 링크가 아닌 실제 콘텐츠를 컨테이너로 옮기고 싶을 때 유용합니다.

실전 시나리오별 docker cp 사용 예제

이론적인 설명만으로는 부족합니다. 실제 개발 및 운영 환경에서 마주할 수 있는 다양한 시나리오를 통해 docker cp 명령어의 활용법을 익혀보겠습니다. (예제에서 my-container는 컨테이너의 이름, /path/on/host/와 /path/in/container/는 각각 호스트와 컨테이너의 임의 경로를 의미합니다.)

1. 기본 파일 복사

호스트의 파일을 컨테이너로 복사

호스트의 config.json 파일을 실행 중인 my-container의 /app/config/ 디렉터리 안으로 복사합니다.

# 호스트의 config.json 파일을 컨테이너의 /app/config/ 디렉터리에 복사
docker cp /path/on/host/config.json my-container:/app/config/

만약 대상 경로 끝에 파일 이름을 지정하면, 복사하면서 파일 이름을 변경할 수도 있습니다.

# 복사하면서 파일 이름을 new-config.json으로 변경
docker cp /path/on/host/config.json my-container:/app/config/new-config.json

컨테이너의 파일을 호스트로 복사

my-container 내부의 /app/logs/access.log 파일을 호스트의 현재 작업 디렉터리(.)로 가져옵니다.

# 컨테이너의 로그 파일을 호스트의 현재 디렉터리로 복사
docker cp my-container:/app/logs/access.log .

마찬가지로, 호스트에 저장하면서 파일 이름을 바꿀 수 있습니다.

# 호스트에 access_log_backup.txt 라는 이름으로 저장
docker cp my-container:/app/logs/access.log /path/on/host/access_log_backup.txt

2. 디렉터리 복사

호스트의 디렉터리를 컨테이너로 복사

호스트의 assets 디렉터리 전체를 컨테이너의 /var/www/html/ 디렉터리 안에 복사합니다. docker cp는 디렉터리를 복사할 때 자동으로 재귀적으로 동작합니다.

# 호스트의 assets 폴더를 컨테이너의 /var/www/html/ 폴더 *안으로* 복사
docker cp /path/on/host/assets my-container:/var/www/html/

이 명령을 실행하면 컨테이너 내부에는 /var/www/html/assets 디렉터리가 생성됩니다. 경로 해석 방식에 대한 자세한 내용은 잠시 후 다루겠습니다.

컨테이너의 디렉터리를 호스트로 복사

데이터베이스 컨테이너의 데이터가 저장된 /var/lib/mysql 디렉터리 전체를 호스트의 /backup/mysql-data 디렉터리로 백업합니다.

# 컨테이너의 /var/lib/mysql 디렉터리 내용을 호스트의 /backup/mysql-data 로 복사
docker cp my-container:/var/lib/mysql /backup/mysql-data

3. 고급 활용법

중지된 컨테이너에서 파일 추출

docker cp의 가장 강력한 기능 중 하나는 중지된(stopped) 컨테이너에서도 파일을 가져올 수 있다는 점입니다. 애플리케이션이 예기치 않게 종료되었을 때, 컨테이너를 다시 시작하지 않고도 로그 파일이나 마지막 상태 데이터를 추출하여 원인을 분석할 수 있습니다.

# 'crashed-app' 이라는 중지된 컨테이너에서 에러 로그를 추출
docker cp crashed-app:/var/log/app/error.log ./

-a 옵션을 사용한 권한 보존 복사

호스트의 appuser(UID 1000) 소유인 파일을 컨테이너로 복사할 때, 컨테이너 내부에서도 동일한 UID/GID를 유지하고 싶을 때 사용합니다.

# 파일 소유권 정보를 보존하며 복사
docker cp -a /path/on/host/user-data.ini my-container:/etc/app/

이 옵션이 없다면, user-data.ini 파일은 컨테이너 내에서 기본적으로 root 사용자의 소유가 됩니다.

- (하이픈)을 이용한 스트림 복사

docker cp는 표준 입력(STDIN)과 표준 출력(STDOUT)을 통한 스트리밍 복사도 지원합니다. 이를 통해 중간에 파일을 생성하지 않고 데이터를 파이프로 연결하여 처리할 수 있습니다. 예를 들어, 컨테이너의 디렉터리를 압축하여 호스트에 바로 저장하고 싶을 때 유용합니다.

# 컨테이너의 /app/data 디렉터리를 tar.gz로 압축하여 호스트에 backup.tar.gz로 저장
docker cp my-container:/app/data - | gzip > backup.tar.gz

위 명령어에서 -는 docker cp의 출력을 파일이 아닌 STDOUT으로 보내라는 의미입니다. 이 STDOUT을 파이프(|)를 통해 gzip 명령어의 입력으로 전달하여 압축 파일을 생성합니다.

반대로, 호스트의 압축 파일을 풀어서 바로 컨테이너에 넣을 수도 있습니다.

# 호스트의 archive.tar.gz 파일을 컨테이너의 /opt/new-app 디렉터리에 압축 해제하며 복사
tar -czf - /path/on/host/source | docker cp - my-container:/opt/new-app/

이 방식은 복잡한 데이터 파이프라인을 구축할 때 매우 강력한 도구가 됩니다.

`docker cp` 작동 방식과 내부 메커니즘

docker cp는 어떻게 격리된 컨테이너의 파일 시스템에 접근할 수 있을까요? 그 비밀은 `tar` 유틸리티에 있습니다.

docker cp 명령을 실행하면, Docker 데몬은 내부적으로 다음과 같은 과정을 거칩니다.

1. 아카이빙(Archiving): 소스 경로가 컨테이너에 있다면, Docker 데몬은 해당 컨테이너 내부에서 tar 명령을 실행하여 지정된 파일이나 디렉터리를 .tar 아카이브로 묶습니다. 소스 경로가 호스트에 있다면, 호스트에서 직접 tar 작업을 수행합니다.
2. 데이터 스트리밍(Data Streaming): 생성된 .tar 아카이브 데이터는 Docker API를 통해 스트림 형태로 대상(호스트 또는 컨테이너)으로 전송됩니다.
3. 압축 해제(Extraction): 데이터 스트림을 받은 대상 측에서는 다시 tar 명령을 사용하여 아카이브를 목적지 경로에 풀어놓습니다.

이러한 tar 기반의 아카이빙-추출 방식은 docker cp의 여러 특징을 설명해 줍니다. 예를 들어, 매우 큰 파일이나 수많은 작은 파일을 복사할 때 성능이 저하될 수 있는 이유는 모든 데이터가 단일 .tar 스트림으로 처리되기 때문입니다. 또한, 심볼릭 링크나 파일 권한 같은 메타데이터를 보존할 수 있는 것도 tar 포맷의 능력 덕분입니다.

`docker cp`의 경로 처리 규칙과 주의사항

docker cp를 사용할 때 가장 흔히 겪는 혼란은 경로 처리 방식입니다. 몇 가지 중요한 규칙을 이해하면 실수를 줄일 수 있습니다.

• 규칙 1: 대상 경로가 /로 끝나는 경우
  대상 경로가 슬래시(/)로 끝나면, Docker는 이를 항상 디렉터리로 간주합니다. 소스 파일/디렉터리는 이 디렉터리 *안으로* 복사됩니다.
  docker cp file.txt my-container:/app/ → 컨테이너에 /app/file.txt가 생성됩니다.
• 규칙 2: 대상 경로가 존재하지 않는 경우
  대상 경로가 존재하지 않으면, Docker는 필요한 상위 디렉터리와 함께 해당 경로를 생성합니다. 소스가 디렉터리일 경우, 대상 경로 이름으로 새로운 디렉터리가 생성되고 그 안에 내용이 복사됩니다.
  docker cp my-app/ my-container:/opt/new-app (new-app이 없음) → 컨테이너에 /opt/new-app 디렉터리가 생성되고 그 안에 my-app의 내용이 복사됩니다.
• 규칙 3: 소스 경로에 /.를 사용하는 경우
  호스트의 디렉터리 '내용'만 복사하고 싶을 때 유용한 트릭입니다.
  • docker cp host-dir my-container:/container-dir → /container-dir/host-dir/ 생성
  • docker cp host-dir/. my-container:/container-dir → /container-dir/ 안에 host-dir의 내용물이 직접 복사됨

파일 소유권(Ownership) 및 권한(Permissions)

권한 문제는 디버깅하기 어려운 문제를 야기할 수 있으므로 명확히 이해해야 합니다.

• 컨테이너 → 호스트 복사 시: 호스트에 생성되는 파일의 소유자는 docker cp 명령을 실행한 호스트 사용자입니다. 컨테이너 내부의 파일 소유권은 무시됩니다.
• 호스트 → 컨테이너 복사 시: 컨테이너에 생성되는 파일의 소유자는 기본적으로 컨테이너의 루트 사용자(UID 0)입니다. 만약 Dockerfile에서 USER 지시어를 사용하여 기본 사용자가 변경된 경우, 해당 사용자가 소유권을 가질 수도 있습니다. 이 기본 동작을 변경하고 싶다면 앞서 설명한 -a 옵션을 사용해야 합니다.

`docker cp`의 한계와 대안: 언제 사용해야 할까?

docker cp는 매우 편리한 도구이지만, 만병통치약은 아닙니다. 이 명령어의 본질은 '명령형(Imperative)' 작업에 있습니다. 즉, 사용자가 직접 개입하여 특정 시점에 파일 상태를 변경하는 것입니다. 이는 재현 가능하고 자동화된 인프라를 지향하는 Docker의 '선언형(Declarative)' 철학과 상충될 수 있습니다. 따라서 docker cp는 적절한 상황에서 신중하게 사용해야 합니다.

`docker cp`의 적절한 사용 사례

• 디버깅: 실행 중인 컨테이너에 임시 스크립트나 도구를 주입하여 내부 상태를 점검할 때.
• 로그 및 데이터 추출: 컨테이너가 생성한 로그 파일, 데이터베이스 덤프, 애플리케이션 아티팩트 등을 호스트로 신속하게 가져올 때.
• 긴급 수정: 이미지를 재빌드하고 다시 배포하기에는 시간이 부족한 긴급 상황에서, 설정 파일의 오타 하나를 빠르게 수정하여 컨테이너에 적용할 때.

`docker cp`가 부적합한 경우와 대안

• 영구 데이터 관리: 데이터베이스 파일, 사용자 업로드 콘텐츠 등 컨테이너가 삭제되어도 유지되어야 하는 데이터는 반드시 Docker 볼륨(Volumes)을 사용해야 합니다. 볼륨은 Docker가 관리하는 호스트의 특정 영역에 데이터를 저장하여 컨테이너의 생명주기와 데이터를 분리합니다.
• 개발 환경에서의 코드 동기화: 개발 중인 소스 코드를 컨테이너에서 실시간으로 테스트하고 싶을 때는 바인드 마운트(Bind Mounts)가 정답입니다. 이는 호스트의 디렉터리를 컨테이너의 특정 경로에 직접 연결(마운트)하여, 호스트에서 코드를 수정하면 즉시 컨테이너에 반영됩니다.
• 이미지 빌드 시 파일 포함: 애플리케이션 코드, 기본 설정 파일, 라이브러리 등 이미지에 포함되어야 하는 모든 자원은 Dockerfile의 COPY 또는 ADD 지시어를 사용해야 합니다. 이는 이미지 빌드 과정을 문서화하고, 누가 빌드하든 항상 동일한 결과물이 나오도록 보장하는 선언적인 방식입니다.

구분	docker cp	볼륨 (Volumes)	바인드 마운트 (Bind Mounts)	Dockerfile `COPY`/`ADD`
주요 용도	일회성/임시 파일 전송, 디버깅, 로그 추출	영구 데이터 저장 (DB, 업로드 파일)	개발 환경의 실시간 코드 동기화	이미지에 애플리케이션 자원 포함
데이터 흐름	단방향 복사 (명령 시점)	양방향, 실시간 I/O	양방향, 실시간 I/O (호스트와 공유)	빌드 시점의 단방향 복사
생명주기	명령 실행 시에만 유효	컨테이너와 독립적 (영구적)	호스트 파일 시스템에 의존	이미지의 일부가 됨
패러다임	명령형 (Imperative)	선언형 (Declarative)	선언형 (Declarative)	선언형 (Declarative)

결론: `docker cp`를 현명하게 활용하기

docker cp는 Docker 생태계에서 없어서는 안 될 중요한 유틸리티입니다. 격리된 컨테이너의 경계를 넘어 호스트와 신속하게 파일을 교환할 수 있는 능력은 운영 및 디버깅 작업의 효율성을 크게 향상시킵니다. 하지만 그 편리함에만 의존하여 남용해서는 안 됩니다.

성공적인 컨테이너 아키텍처는 재현 가능하고, 예측 가능하며, 자동화되어야 합니다. 이러한 목표를 달성하기 위해서는 데이터의 성격과 용도에 맞는 올바른 도구를 선택하는 것이 중요합니다. docker cp는 긴급 상황이나 임시적인 필요를 해결하는 강력한 '수동' 도구로 활용하되, 애플리케이션의 영구 데이터와 소스 코드는 볼륨, 바인드 마운트, Dockerfile을 통해 '자동화된' 방식으로 관리하는 것이 현명한 전략입니다. 이 도구들의 차이점을 명확히 이해하고 각자의 역할에 맞게 사용할 때, 비로소 Docker의 진정한 잠재력을 최대한 활용할 수 있을 것입니다.