Cloud Storage FUSE CLI 참조

이 문서에서는 Cloud Storage FUSE와 상호작용하는 데 사용되는 gcsfuse 명령 옵션에 대해 설명합니다. Cloud Storage FUSE CSI 드라이버를 사용하여 Google Kubernetes Engine의 로컬 파일 시스템에 버킷을 마운트하는 경우 Cloud Storage FUSE CSI 드라이버의 마운트 옵션을 참고하세요.

Cloud Storage FUSE 명령줄 인터페이스 (CLI) 또는 gcsfuse CLI는 로컬 머신에서 Cloud Storage 버킷을 파일 시스템으로 마운트하는 데 사용됩니다.

gcsfuse CLI 명령어 구조

다음 예에서는 필수 명령어와 선택적 gcsfuse 옵션을 포함한 gcsfuse 명령어의 구조를 보여줍니다.

gcsfuse GLOBAL_OPTIONS BUCKET_NAME MOUNT_POINT

다음을 바꿉니다.

  • GLOBAL_OPTIONS는 마운트 설정 방법과 Cloud Storage FUSE의 작동 방법을 제어하는 gcsfuse 옵션입니다.

  • BUCKET_NAME은 마운트할 버킷의 이름입니다. 예를 들면 my-mount-bucket입니다. (선택사항) 동적 마운트를 수행하려면 이 명령어에서 버킷 이름을 제외합니다.

  • MOUNT_POINT는 버킷이 마운트되는 로컬 디렉터리입니다. 예를 들면 /path/to/mount/point입니다.

gcsfuse CLI 옵션

gcsfuse 옵션 설명 유효한 값 기본값
요청에 대한 인증을 사용 중지합니다. 인증을 지원하지 않는 커스텀 엔드포인트를 사용하는 경우 이 옵션을 설정해야 합니다. 공개 버킷에서 Cloud Storage FUSE를 사용하는 경우에도 이 옵션을 설정해야 합니다. 불리언 값: true, false. false
마운트의 애플리케이션 이름입니다. 문자열 값입니다(예: my-bucket-mount). ""
마운트된 버킷에 액세스할 때 청구에 사용할 프로젝트를 지정합니다. 요청자 지불을 사용 설정해서 버킷을 마운트할 때 종종 필수로 요구되는 옵션입니다. 프로젝트 ID를 나타내는 문자열 값입니다. ""

파일 캐시를 사용 설정하고 파일 캐시 데이터를 저장할 디렉터리를 지정합니다.

 경로입니다(예: /tmp/gcsfuse-cache-path). 값이 비어 있으면 이 옵션이 사용 중지되었음을 나타냅니다. 이 gcsfuse 옵션은 기본적으로 사용 중지되어 있습니다. ""
Cloud Storage 백엔드와 통신하는 데 사용되는 프로토콜을 지정합니다.
  • HTTP/1.1의 경우 http1
  • HTTP/2의 경우 http2
  • grpc의 경우 gRPC. Cloud Storage FUSE와 함께 gRPC를 사용하려면 Cloud Storage FUSE 버전 2.10.0 이상을 사용하는 것이 좋습니다.
 http1

지정된 간격으로 Cloud Monitoring에 측정항목을 내보냅니다.

 값을 초 단위로 나타내는 정수(예: 10(10초)). 0는 내보내기 없음을 지정합니다. 0
Cloud Storage FUSE 동작을 구성하기 위해 사용하려는 구성 파일의 경로를 지정합니다. 경로입니다(예: /etc/gcsfuse.yaml). ""
데이터 가져오기를 위한 대체 커스텀 엔드포인트를 지정합니다. 커스텀 엔드포인트는 Cloud Storage JSON 엔드포인트 storage.UNIVERSE_DOMAIN_NAME:443과 같이 상응하는 리소스 및 작업을 지원해야 합니다. 커스텀 엔드포인트를 지정하지 않으면 Cloud Storage FUSE가 전역 Cloud Storage JSON API 엔드포인트인 storage.googleapis.com:443을 사용합니다. 지정한 커스텀 엔드포인트에서 인증이 지원되지 않는 경우 --anonymous-access gcsfuse 옵션을 true로 설정하여 인증을 우회합니다. 엔드포인트입니다(예: storage.googleapis.com:443). ""
FUSE 관련 디버깅 출력을 사용 설정합니다. 이 옵션은 --log-severity gcsfuse 옵션으로 대체되었습니다. 디버깅 출력을 사용 설정하려면 --log-severity gcsfuse 옵션을 trace로 설정합니다. 여기에는 추적, 디버그, 정보, 경고, 오류 로그가 포함됩니다. 불리언 값: true, false. false
Cloud Storage 요청 및 타이밍 정보를 출력합니다. 이 gcsfuse 옵션은 --log-severity gcsfuse 옵션으로 대체되었습니다. 디버깅 출력을 사용 설정하려면 --log-severity gcsfuse 옵션을 trace로 설정합니다. 여기에는 추적, 디버그, 정보, 경고, 오류 로그가 포함됩니다. 불리언 값: true, false. false
내부 불변 위반이 감지되면 프로그램을 종료합니다. 불리언 값: true, false. false
뮤텍스가 너무 오랫동안 유지되면 디버그 메시지를 출력합니다. 이 gcsfuse 옵션을 지정하면 로그의 심각도 수준이 trace로 자동 설정되며 trace, 디버그, 정보, 경고, 오류 로그가 포함됩니다. 불리언 값: true, false. false
디렉터리의 권한 비트(8진수)입니다. 000과 777 사이의 정수(양 끝값 포함) 755
Cloud Storage 객체의 일부를 메모리 내 버퍼로 비동기식으로 미리 가져오도록 지정하여 후속 읽기가 네트워크 호출이 필요한 대신 버퍼에서 제공되도록 합니다. 불리언 값: true, false false
파일을 Cloud Storage에서 찾을 수 없으면 NonexistentType 유형으로 유형 캐시 항목을 만듭니다. Cloud Storage에 파일이 생성되지만 파일의 NonexistentType 항목이 캐시되면 NonexistentType 항목이 유형 캐시에서 삭제될 때까지 Cloud Storage FUSE가 파일을 요청할 수 없습니다. 불리언 값: true, false. false
데이터가 로컬에 완전히 스테이징되고 close() 또는 fsync() 시 업로드되는 대신 작성될 때 Cloud Storage에 직접 업로드되도록 쓰기 경로 흐름을 제어합니다. 스트리밍 쓰기에 대한 자세한 내용은 Cloud Storage FUSE GitHub 문서의 Cloud Storage FUSE 시맨틱스를 참고하세요. 불리언 값: true, false. true

파일 캐시에서 사용할 수 있는 최대 크기(MiB)를 지정하고 파일 캐시가 마운트된 디렉터리 내에서 사용할 수 있는 총 용량을 제한할 수 있습니다.
  • 정수
  • -1: cache-dir에 지정한 디렉터리에서 캐시의 사용 가능한 전체 용량을 사용하도록 지정 cache-dir이 전달된 경우에만 기본값입니다.
  • 0: 파일 캐시를 사용 중지
 -1
0이 아닌 오프셋에서 첫 번째 읽기를 완료할 때 전체 객체를 비동기식으로 다운로드하여 Cloud Storage FUSE 캐시 디렉터리에 저장해야 하는지 여부를 결정합니다. 임의 읽기나 부분 읽기를 여러 번 수행하려면 이 gcsfuse 옵션을 true로 설정해야 합니다. 불리언 값: true, false. false
객체를 파일 캐시로 다운로드할 때 각 goroutine이 Cloud Storage에 전송하는 각 읽기 요청의 크기(MiB)를 지정합니다. 정수 200

파일 캐시 디렉터리를 미리 가져오기 버퍼로 사용하여 여러 작업자가 파일의 여러 부분을 동시에 다운로드하게 함으로써 대용량 파일의 읽기를 가속화합니다.

파일 캐싱을 사용 설정하면 동시 다운로드가 자동으로 사용 설정됩니다. 파일 캐싱에 대해 자세히 알아보려면 Cloud Storage FUSE의 파일 캐싱을 참고하세요.

동시 다운로드 및 지원 속성을 구성하는 방법에 관해 자세히 알아보려면 동시 다운로드를 참고하세요.

 불리언 값: true, false. true
파일의 모든 다운로드 작업에서 특정 시점에 생성할 수 있는 최대 goroutine 수입니다.
  • 정수
  • -1: 무제한 동시 다운로드를 지정
  • 0: 병렬 다운로드를 사용 중지. --enable-parallel-downloads가 전달되지 않거나 false로 전달된 경우에만 사용할 수 있습니다.
 머신 CPU 코어 수의 두 배 또는 16 중 더 큰 값입니다.
파일당 동시 다운로드 요청 수입니다. 정수 16
파일의 권한 비트(8진수)를 지정합니다. 000과 777 사이의 정수(양 끝값 포함) 644
포그라운드에서 gcsfuse 명령어를 실행합니다. 불리언 값: true, false. false
모든 노드의 그룹 식별자(GID) 소유자를 지정합니다.
  • GID를 나타내는 정수
  • -1: 호출자의 GID가 사용됨
 -1
Cloud Storage FUSE에 대한 도움말을 표시합니다. 없음 없음
설치한 Cloud Storage FUSE 버전을 표시합니다. 없음 없음
시간 초과되기 전 서버에서 응답을 받기 위해 Cloud Storage FUSE HTTP 클라이언트가 대기할 수 있는 기간을 지정합니다. 재생 시간. 예를 들어 1시간 10분 10초의 경우 1h10m10s입니다. 0s는 제한 시간이 없는 경우입니다. 0s
Control+C에 의해 트리거된 SIGINT와 같은 시스템 중단 신호를 무시하도록 Cloud Storage FUSE에 지시합니다. 그러면 신호로 인해 진행 중인 작업이 종료되지 않습니다. 불리언 값: true, false. true
폴더 및 관리 폴더를 암시적으로 포함합니다. 자세한 내용은 Cloud Storage FUSE GitHub 문서의 파일 및 디렉터리를 참고하세요. 불리언 값: true, false. false
목록 캐시를 사용 설정하고 캐시된 목록 항목의 TTL(수명)을 초 단위로 정의합니다. 목록 캐시는 사용 가능한 메모리를 기반으로 커널에 의해 제어되는 페이지 캐시의 메모리에 보관됩니다.
  • 초를 나타내는 정수(예: 10(10초))
  • 0: 목록 캐싱을 사용 중지
  • -1: 항목 만료를 우회하고 사용 가능한 경우 항상 캐시에서 목록 응답을 반환
 0
Cloud Storage에 대해 요청을 인증하기 위해 JSON 키 파일에 대한 절대 경로를 지정합니다. 기본적으로 Cloud Storage FUSE는 인증 요청을 위해 애플리케이션 기본 사용자 인증 정보를 사용합니다. 경로입니다(예: /home/example_user/gcloud-key.json). 이 옵션을 설정하지 않으면 애플리케이션 기본 사용자 인증 정보가 사용됩니다.
Cloud Storage FUSE가 Clous Storage에서 데이터를 읽을 수 있도록 30초 동안 측정된 대역폭 한도를 지정합니다. 부동 소수점 수. -1는 제한이 없는 경우입니다. -1
30초 동안 측정된, 초당 수행되는 작업 한도를 지정합니다. 부동 소수점 수. -1는 제한이 없는 경우입니다. -1
Fluentd로 파싱될 수 있는 로그를 저장하기 위한 파일을 지정합니다. 경로입니다(예: /tmp/user-example-bucket-gcsfuse-logs.txt). Cloud Storage FUSE가 포그라운드에서 실행될 때 stdout 또는 Cloud Storage FUSE가 백그라운드에서 실행될 때 syslog
로그 파일의 형식을 지정합니다.
  • text
  • json
 json
로그를 쓸 활성 파일을 제외하고 보관할 최대 순환된 로그 파일 수입니다.
  • 정수
  • 0: 모든 회전된 로그 파일을 보관함
 10
순환된 로그 파일이 gzip을 사용하여 압축되는지 여부를 지정합니다. 불리언 값: true, false. true
로그 파일이 순환되기 전에 도달할 수 있는 최대 크기(MB)입니다. 정수. 최솟값은 1입니다. 512

Cloud Storage FUSE에서 로그를 생성할 심각도 수준입니다. 심각도 수준은 심각도가 가장 낮은 순에서 높은 순으로 정렬됩니다. 예를 들어 warning을 지정하면 Cloud Storage FUSE가 주의 및 오류에 대한 로그를 생성합니다. 일반적으로 info 심각도 수준을 사용하는 것이 좋습니다.
  • off: 모든 로깅을 사용 중지합니다.
  • error: Cloud Storage FUSE가 작업을 완료하지 못하도록 하거나 마운트 실패, 권한 오류, 심각한 입력/출력(I/O) 오류와 같은 실패를 나타내는 심각한 문제에 관한 메시지가 포함됩니다.
  • warning: 심각하지는 않지만 해결하지 않으면 문제가 될 수 있는 잠재적 문제를 나타내는 메시지가 포함되어 있습니다. 잠재적인 문제에는 심각하지 않은 연결 문제, 지원 중단 경고, 약간의 성능 저하를 유발할 수 있는 리소스 경합, 일시적인 실패에 대한 재시도가 포함됩니다. 이 심각도 수준에는 error 심각도 수준에서 제공된 정보도 포함됩니다.
  • info: 시작 및 종료 메시지, 성공적인 마운트 작업에 관한 정보, 진행 상황 업데이트, 구성 설정 등 일반 로깅 정보를 포함합니다. 이 심각도 수준에는 warning 및 error 심각도 수준에 관한 정보도 포함됩니다.
  • debug: 시작 및 종료 메시지, 성공적인 마운트 작업에 관한 정보, 진행 상황 업데이트, 구성 설정 등 로깅 정보를 포함합니다. 이 심각도 수준에는 info, warning, error 심각도 수준에서 제공된 정보도 포함됩니다.
  • trace: 각 Cloud Storage FUSE 작업 및 함수 호출에 관한 세부정보를 포함하며, 커널 FUSE 드라이버 및 Cloud Storage와의 gcsfuse 상호작용을 설명합니다. 이 심각도 수준에는 debug, info, warning, error 심각도 수준에서 제공된 세부정보도 포함됩니다.
 info
서버당 허용되는 TCP 연결의 최대 개수를 지정합니다. --client-protocol이 http1로 설정된 경우에 적용됩니다. 0에서 2147483647 사이의 정수입니다. 0은 TCP 연결에 한도가 없음을 지정합니다. 0
서버당 허용되는 유휴 연결의 최대 개수를 지정합니다. --client-protocol이 http1로 설정된 경우에 적용됩니다. 0에서 2147483647 사이의 정수입니다. 0은 서버당 허용되는 유휴 연결의 최대 개수를 지정합니다. 0
작업이 실패할 경우 작업이 재시도되는 최대 횟수를 지정하여 무한 재시도 루프를 방지합니다.
  • 최대 재시도 횟수를 나타내는 정수입니다(예: 10).
  • 0: 무제한 재시도를 허용합니다.
 0
Cloud Storage FUSE가 지수 백오프를 사용하여 재시도 루프에서 절전 모드로 전환될 수 있는 최대 기간을 지정합니다. 백오프 기간이 지정된 최대 기간을 초과하면 지정된 최대 기간 동안 재시도가 계속됩니다. 기간. 예를 들어 1시간 5분 50초의 경우 1h5m50s, 60초의 경우 60s입니다. 30s

캐시에 존재하지 않는 파일의 결과를 저장하는 음성 통계 캐시 항목의 TTL(수명)을 초 단위로 정의합니다.
  • 초를 나타내는 정수(예: 10(10초))
  • 0: 음성 통계 캐싱을 사용 중지
  • -1: 무제한 음성 통계 캐싱을 허용하고 TTL 만료를 사용 중지
 5
캐시된 메타데이터 항목의 TTL(수명)을 초 단위로 정의합니다.
  • 초를 나타내는 정수(예: 30(30초))
  • -1: TTL 만료를 우회하고 사용 가능할 때마다 캐시에서 파일 제공
  • 0: 최신 파일 사용. 이 값을 사용하면 Get 메타데이터 호출을 실행하여 캐시에 있는 파일의 객체 생성이 Cloud Storage에 저장된 객체 생성과 일치하는지 확인합니다.
 60
시스템별 추가 마운트 옵션을 지정합니다. FUSE에서 가장 일반적인 마운트 옵션(예: suid)은 Cloud Storage FUSE에서 지원되며 -o 옵션과 함께 전달할 수 있습니다. 예를 들어 FUSE의 마운트 옵션
  • rw: 읽기-쓰기로 마운트
  • ro: 읽기 전용으로 마운트
 ""
버킷 내에서 특정 디렉터리만 마운트합니다. 경로입니다(예: /etc/gcsfuse.yaml). ""
캐싱, 스레딩, 버퍼 크기에 대해 미리 정의되고 최적화된 Cloud Storage FUSE 구성 집합을 적용하여 학습, 제공, 체크포인트와 같은 특정 워크로드 유형의 고성능을 달성하도록 지원합니다. 워크로드 유형에 따른 각 사전 정의된 구성에 대해 자세히 알아보려면 AI/ML 워크로드의 프로필 기반 구성을 참고하세요.
  • 문자열입니다(예: "aiml-checkpointing").
  • "aiml-training": 대규모 데이터 세트의 높은 처리량 읽기 성능을 최적화하고 Cloud GPU 및 Cloud TPU 하드웨어가 데이터를 기다리지 않도록 합니다.
  • aiml-checkpointing: 멀티 기가바이트 체크포인트를 저장하는 데 걸리는 시간을 대폭 줄여 대용량 파일의 높은 처리량 쓰기 성능을 최적화하여 학습 일시중지를 최소화합니다.
  • aiml-serving: 데이터 액세스를 간소화하고 캐싱 메커니즘을 적용하여 워크로드 제공 성능을 최적화합니다.
 ""

지정된 포트와 /metrics 경로에서 Prometheus 측정항목 엔드포인트를 노출합니다.

 지정하려는 포트를 나타내는 정수 0

모든 파일 핸들에서 버퍼링된 읽기에 사용할 수 있는 최대 블록 수를 지정합니다.
  • 정수
  • 0: 버퍼링된 읽기를 사용 중지합니다.
  • -1: 값을 무제한 블록으로 설정합니다.
 40
지정된 한도보다 하위 요소가 더 적게 포함된 디렉터리의 이름 바꾸기를 허용합니다. 0에서 2147483647 사이의 정수입니다. 0
연속 재시도 사이의 지수 백오프의 배수를 지정합니다. 부동 소수점 수 2
--token-url에서 가져온 토큰을 재사용할지 여부를 지정합니다. 불리언 값: true, false. true
Cloud Storage에서 다운로드할 데이터의 청크 크기 (MB)를 지정합니다. 1에서 1024 사이의 정수입니다. 200
통계 캐시가 보유할 수 있는 항목 수를 지정합니다. 이 gcsfuse 옵션은 --stat-cache-max-size-mb gcsfuse 옵션으로 대체되었습니다. 정수 4096
통계 캐시에서 사용할 수 있는 최대 메모리 크기(MiB)입니다. 통계 캐시는 항상 메모리에 온전히 보관됩니다.
  • 정수. 다음을 권장합니다.
    • 32: 워크로드에 파일이 최대 20,000개까지 포함된 경우
    • 워크로드가 파일 20,000개를 초과하면 파일 6,000개가 추가될 때마다 10씩 크기 증가. 통계 캐시는 파일당 평균 1,500MiB를 사용합니다.
  • -1: 제한을 설정하지 않으며 통계 캐시에서 필요한 만큼 메모리를 사용하는 경우
  • 0: 통계 캐시를 사용 중지하는 경우
 32
StatObject 결과와 아이노드 속성을 캐시할 기간을 지정합니다. 이 옵션은 --metadata-cache-ttl-secs gcsfuse 옵션으로 대체되었습니다. 시간. 예를 들어 20s (20초)입니다. 60s
Cloud Storage에 업로드되기 전 쓰기가 스테이징되는 임시 디렉터리의 경로를 지정합니다. 경로입니다(예: /mnt/ssd/example-user-gcsfuse-temp-dir). /tmp
--key-file이 없으면 액세스 토큰을 가져오기 위한 URL을 지정합니다. URL ""
이름 및 파일 또는 디렉터리 아이노드의 디렉터리 사이에 매핑을 캐시할 기간을 초 단위로 지정합니다. 이 gcsfuse 옵션은 --metadata-cache-ttl-secs gcsfuse 옵션으로 대체되었습니다. 시간(초)(예: 20s(20초)) 60s
유형 캐시에서 사용할 수 있는 디렉터리당 최대 크기(MiB)입니다. 유형 캐시는 항상 메모리에 온전히 보관됩니다.
  • 정수. 다음을 권장합니다.
    • 4: 마운트하는 버킷의 단일 디렉터리 내에 있는 최대 파일 수에 파일이 20,000개 이하로 포함된 경우
    • 마운트하는 단일 디렉터리 내의 최대 파일 수에 파일이 20,000개 넘게 있으면 파일 5,000개(파일당 평균 약 200 바이트)마다 값을 1씩 증분
  • -1: 한도를 지정하지 않고 유형 캐시에서 필요한 만큼 메모리를 사용하도록 하는 경우
  • 0: 유형 캐시를 사용 중지하는 경우
 4
모든 아이노드의 사용자 식별자(UID) 소유자를 지정합니다.
  • UID를 나타내는 정수
  • -1: 호출자의 UID가 사용됨
 -1

모든 파일에서 스트리밍 쓰기에 사용할 수 있는 최대 데이터 청크 수를 지정합니다. 각 파일은 기본적으로 32MiB 데이터 청크 하나를 사용합니다.
  • 정수
  • 0: 스트리밍 쓰기를 사용 중지합니다.
  • -1: 값을 무제한 청크로 설정합니다.
  • 리소스가 제한된 사양이 낮은 머신의 기본값: 4
  • 리소스가 많은 고사양 머신의 기본값: 1600

맨 위로