동기화 파일 공유

동기화 파일 공유 (Synchronized file shares)

Synchronized file shares는 호스트에서 VM으로 빠르고 유연한 파일 공유를 제공하는 대체 파일 공유 메커니즘이에요. 동기화된 파일시스템 캐시를 사용해 바인드 마운트 성능을 향상시켜요.

출처: Synchronized file sharing

본문

이 기능은 Pro, Team, Business 구독에서 사용할 수 있어요.

대상 사용자

Synchronized file shares는 다음과 같은 개발자에게 이상적이에요.

100,000개 이상의 파일을 가진 큰 리포지토리나 모노레포(수백 MB에서 수 GB)를 가진 경우
VirtioFS, gRPC FUSE 같은 가상 파일시스템이 코드베이스 규모에서 더 이상 잘 확장되지 않는 경우
자주 성능 한계를 겪는 경우
파일 소유권에 신경 쓰고 싶지 않거나, 여러 컨테이너를 수정할 때 충돌하는 파일 소유권 정보를 해결하는 데 시간을 쓰고 싶지 않은 경우

동작 원리

Synchronized file share는 가상 파일 공유처럼 동작하지만, 고성능·저지연 코드 동기화 엔진을 활용해 Docker Desktop VM 안의 ext4 파일시스템에 호스트 파일의 동기화 캐시를 만들어요. 호스트나 VM 컨테이너에서 파일시스템을 변경하면 양방향 동기화로 전파돼요.

파일 공유 인스턴스를 만든 후, 지정된 동기화 파일 공유 위치(또는 그 하위 디렉터리)와 일치하는 호스트 파일시스템 위치를 가리키는 바인드 마운트를 쓰는 모든 컨테이너가 Synchronized File Shares 기능을 사용해요. 이 조건을 만족하지 않는 바인드 마운트는 VirtioFS나 gRPC-FUSE 같은 일반 가상 파일시스템 바인드 마운트 메커니즘으로 전달돼요.

참고: Synchronized file shares는 Docker Desktop의 Kubernetes hostPath 볼륨에서는 사용되지 않아요. 중요: Windows 컨테이너를 사용할 때는 Synchronized file shares를 쓸 수 없어요.

파일 공유 인스턴스 만들기

Docker Desktop에 로그인해요.
Settings의 Resources 섹션에서 File sharing 탭으로 이동해요.
Synchronized file shares 섹션에서 Create share 를 선택해요.
공유할 호스트 폴더를 선택해요. 동기화 파일 공유가 초기화되고 사용 가능해져요.

파일이 Docker Desktop VM에 복사되면서 파일 공유 초기화에 몇 초 걸려요. 이 동안 상태 표시기가 Preparing 을 표시해요. Docker Desktop Dashboard의 푸터에도 상태 아이콘이 있어서 계속 알려줘요.

상태 표시기가 Watching for filesystem changes 를 표시하면, 명령줄의 -v든 compose.yml 파일에 지정한 거든 모든 표준 바인드 마운트 메커니즘을 통해 파일이 VM에서 사용 가능해져요.

참고: 새 서비스를 만들 때 바인드 마운트 옵션 일관성을 :consistent로 설정하면 Synchronized file shares를 우회해요.

파일 공유 인스턴스 탐색하기

Synchronized file shares 섹션은 모든 파일 공유 인스턴스를 표시하고 각 인스턴스에 대한 정보를 제공해요.

파일 공유 콘텐츠의 출처
상태 업데이트
각 파일 공유가 사용하는 공간
파일시스템 항목 수
심볼릭 링크 수
파일 공유 인스턴스를 사용 중인 컨테이너

파일 공유 인스턴스를 선택하면 드롭다운이 펼쳐지며 이 정보를 보여줘요.

`.syncignore` 사용하기

각 파일 공유의 루트에 .syncignore 파일을 두어 로컬 파일을 파일 공유 인스턴스에서 제외할 수 있어요. .dockerignore 파일과 같은 문법을 지원하고, 동기화에서 경로를 제외/재포함해요. .syncignore 파일은 파일 공유 루트가 아닌 다른 위치에서는 무시돼요.

.syncignore 파일에 넣으면 좋은 것의 예는 다음과 같아요.

큰 의존성 디렉터리(예: node_modules, composer 디렉터리) (바인드 마운트로 접근하는 데 의존하지 않는 한)
.git 디렉터리 (마찬가지로 필요하지 않다면)

일반적으로 워크플로에 중요하지 않은 항목, 특히 동기화가 느리거나 저장 공간을 많이 쓰는 항목을 .syncignore로 제외하세요.

알려진 문제

.syncignore 변경은 파일 공유를 다시 만들지 않는 한 즉시 삭제로 이어지지 않아요. 즉, .syncignore 수정으로 새로 무시된 파일은 현재 위치에 남지만 동기화 중에는 더 이상 업데이트되지 않아요.
파일 공유 인스턴스는 공유당 대략 2백만 파일로 제한돼요. 최상의 성능을 위해 이 크기의 인스턴스가 있다면 개별 바인드 마운트 위치에 해당하는 여러 공유로 분해해 보세요.
Linux는 대소문자를 구분하고 macOS/Windows는 대소문자만 보존해서 생기는 대소문자 충돌은 GUI에서 File exists 문제로 표시돼요. 무시할 수 있어요. 그래도 지속되면 이슈를 보고하세요.
Synchronized file shares는 임시 문제를 적극적으로 보고해서 동기화 중 GUI에 Conflict, Problem 표시기가 나타날 수 있어요. 무시할 수 있지만 지속되면 보고하세요.
Windows에서 WSL2에서 Hyper-V로 전환하면 Docker Desktop을 완전히 재시작해야 해요.
POSIX 스타일 Windows 경로는 지원되지 않아요. Docker Compose에서 COMPOSE_CONVERT_WINDOWS_PATHS 환경 변수를 설정하지 마세요.
심볼릭 링크를 만들 권한이 없는데 컨테이너가 파일 공유 인스턴스에서 심볼릭 링크를 만들려 하면 unable to create symbolic link 오류가 표시돼요.

동기화 파일 공유