gsutil에서 gcloud 스토리지로 전환

gcloud storage (일반 가용성)은 Cloud Storage와 상호작용하는 데 권장되는 명령줄 도구입니다. 이 페이지에서는 두 도구 간의 주요 차이점과 명령어 매핑을 설명하여 gsutil에서 gcloud storage로 전환하는 데 도움을 줍니다. gcloud storage 도구의 자세한 설명은 gcloud storage 참조 문서를 참고하세요.

Google Cloud CLI를 설치하고 사용을 시작하는 방법을 알아보려면 Google Cloud CLI 설치를 참고하세요.

동작 차이

다음 섹션에서는 gsutil와 gcloud storage 간의 동작 차이점을 설명합니다.

동시 호출

gcloud storage는 서로 다른 터미널에서 CLI의 여러 인스턴스를 동시에 실행하는 것을 지원하지 않습니다.

병렬 처리

gcloud storage은 병렬 처리를 지원합니다.

와일드 카드 처리

gcloud storage에서는 별표 여러 개를 단순화합니다. 별표를 세 개 이상 연속으로 사용하면 (***) 별표 하나 (*)로 처리됩니다.

계층적 네임스페이스 버킷 처리

gcloud storage을 사용하여 계층적 네임스페이스가 사용 설정된 버킷을 만들고 관리할 수 있습니다.

화면출력 형식

gcloud storage 및 gsutil 명령어는 출력을 다르게 형식화합니다. 로깅 형식과 같은 사소한 변경사항은 영향을 미치지 않을 수 있지만 오류 메시지와 데이터 목록의 더 큰 차이로 인해 자동 스크립트가 중단될 수 있습니다.

gsutil 명령어 출력을 파싱하는 스크립트가 있는 경우 전환하기 전에 gcloud storage 형식에 맞게 검토하고 업데이트해야 합니다.

gcloud 명령어에 상응하는 명령어

기존의 모든 gsutil 명령어는 gcloud storage의 명령어와 동일하지만, 몇 가지 예외가 있습니다. 참조 문서에 방문하거나 gcloud storage --help를 실행하여 gcloud storage 명령어의 전체 목록을 가져올 수 있습니다. 다음 표에는 자주 사용되는 gsutil 명령어의 변경사항이 간략하게 설명되어 있습니다.

작업 gsutil 명령어 gcloud storage 명령어
액세스 제어 목록 (ACL) 관리 
gsutil acl get
gsutil acl set
gsutil acl ch

gcloud storage RESOURCE describe --format="multi(acl:format=json)"
gcloud storage RESOURCE update --acl-file=ACL_FILE_PATH
gcloud storage RESOURCE update --add-acl-grant=GRANT
gcloud storage RESOURCE update --remove-acl-grant=GRANT
작업 gsutil 명령어 gcloud storage 명령어
객체를 연결하고 객체 콘텐츠 표시 
gsutil cat
 
gcloud storage cat
작업 gsutil 명령어 gcloud storage 명령어
새 객체로 결합하여 객체 연결 
gsutil compose
 
gcloud storage objects compose
참고
gcloud storage objects compose에서 사전 조건을 적용하려면 --if-generation-match 또는 --if-metageneration-match와 같은 특정 플래그를 사용하세요.
작업 gsutil 명령어 gcloud storage 명령어
객체 및 기타 리소스 복사 
gsutil cp
 
gcloud storage cp
참고

Google Cloud 콘솔을 사용하여 만든 시뮬레이션된 폴더는 0바이트 자리표시자 객체로 인식됩니다. gcloud storage cp는 시뮬레이션된 폴더를 복사하는 데 사용할 수 있지만 gsutil cp는 사용할 수 없습니다.

오류를 처리할 때 gcloud storage cp는 리소스 중 하나가 유효하지 않거나 존재하지 않더라도 모든 리소스를 복사하려고 시도합니다. gsutil cp는 잘못된 리소스를 발견하는 즉시 전체 작업을 중지할 수 있습니다.

객체를 다운로드할 때 gcloud storage cp는 대상 경로에 지정된 누락된 로컬 디렉터리를 만듭니다. 대상 디렉터리가 없으면 gsutil cp가 실패합니다.
작업 gsutil 명령어 gcloud storage 명령어
객체에서 사용한 총 디스크 공간 표시 
gsutil du
 
gcloud storage du
작업 gsutil 명령어 gcloud storage 명령어
파일 해시 계산 
gsutil hash
 
gcloud storage hash
참고

gsutil hash는 -c 또는 -m와 같은 특정 해시를 포함하기 위해 추가 플래그를 사용합니다. gcloud storage hash는 --skip-md5 또는 --skip-crc32c와 같은 해시를 제외하기 위해 빼기 플래그를 사용합니다.
작업 gsutil 명령어 gcloud storage 명령어
버킷 라벨 관리 
gsutil label get
gsutil label set
gsutil label ch

gcloud storage buckets describe
gcloud storage buckets update
gcloud storage buckets update
참고

단일 gsutil label ch 명령어에서 라벨을 추가, 업데이트, 삭제하는 조합은 gcloud storage buckets update을 사용하는 동등한 작업과 다르게 동작할 수 있습니다. gsutil의 특정 읽기-수정-쓰기 동작을 사용하는 스크립트는 gcloud storage로 전환한 후 신중하게 테스트해야 합니다.
작업 gsutil 명령어 gcloud storage 명령어
버킷, 객체, 폴더 나열 
gsutil ls
 
gcloud storage ls
참고

와일드 카드를 사용하여 프로젝트의 객체를 나열하면 gsutil ls는 객체의 플랫 목록을 반환하는 반면 gcloud storage ls는 버킷 이름으로 그룹화된 객체를 반환합니다.

gcloud storage ls -L를 사용하여 자세한 목록을 출력으로 반환할 때는 다음 동작이 적용됩니다.

  • 각 메타데이터의 라벨('키'라고도 함)은 각 단어의 첫 글자가 대문자로 표시됩니다.
  • 객체의 메타데이터에 값이 없으면 gcloud storage가 출력에서 해당 줄을 생략합니다.

gcloud storage은 항상 UTC로 날짜/시간을 출력합니다.

gcloud storage는 명령어 출력의 끝에 오류 메시지를 반환합니다.
작업 gsutil 명령어 gcloud storage 명령어
객체 또는 디렉터리 이동 및 이름 바꾸기 
gsutil mv
 
gcloud storage mv
작업 gsutil 명령어 gcloud storage 명령어
객체를 제자리에서 다시 작성 
gsutil rewrite
 
gcloud storage objects update
참고

boto 구성 파일에 encryption_key이 설정된 경우 gsutil rewrite -k은 객체에 키를 적용합니다. encryption_key이 설정되지 않은 경우 gsutil rewrite -k에 해당하는 값은 gcloud storage objects update --clear-encryption-key입니다. 이렇게 하면 객체에서 고객 제공 암호화 키 (CSEK) 또는 고객 관리 암호화 키(CMEK)가 삭제됩니다. 그러면 객체가 버킷의 기본 KMS 키 또는 Google관리 암호화로 암호화됩니다.

gsutil rewrite에는 요청된 변환으로 인해 객체의 상태가 변경되지 않는 경우 (예: 객체가 이미 타겟 스토리지 클래스에 있는 경우) 객체 다시 쓰기를 건너뛰는 로직이 포함되어 있습니다. gcloud storage objects update는 동일한 검사를 수행하지 않을 수 있으므로 불필요한 작업이 발생할 수 있습니다.
작업 gsutil 명령어 gcloud storage 명령어
객체 또는 버킷 삭제 
gsutil rm
 
gcloud storage rm
참고

gsutil 별칭 del, delete, remove은 지원되지 않습니다.

-l 및 -r 플래그를 함께 사용할 때 gsutil 및 gcloud storage의 동작이 서로 다른 알려진 문제가 있습니다. 재귀적으로 삭제할 디렉터리 목록을 파이프하는 스크립트는 gsutil 사용에서 gcloud storage로 전환하기 전에 철저히 테스트해야 합니다.
작업 gsutil 명령어 gcloud storage 명령어
두 버킷 또는 디렉터리의 콘텐츠 동기화 
gsutil rsync
 
gcloud storage rsync
참고

기본적으로 gsutil rsync는 소스와 대상 간에 객체의 크기와 마지막 수정 시간이 일치하면 객체가 변경되지 않은 것으로 간주합니다. 객체에 수정 시간이 누락되었거나 -c 플래그를 사용하여 수동으로 강제하는 경우에만 더 철저한 체크섬 비교를 실행합니다. gcloud storage rsync도 파일의 크기와 마지막 수정 시간을 확인하는 것으로 시작합니다. 하지만 객체 크기가 일치하지만 수정 시간이 다르거나 누락된 경우 체크섬 비교가 자동으로 실행됩니다.

gcloud storage rsync는 성능 향상을 위해 기본적으로 작업을 병렬로 실행합니다. 최상위 -m 플래그를 사용하지 않는 한 gsutil rsync는 순차적으로 실행됩니다.

gsutil rsync는 기본적으로 심볼릭 링크를 따릅니다. --no-ignore-symlinks 플래그를 사용하지 않는 한 gcloud storage rsync는 기본적으로 이를 무시합니다.
작업 gsutil 명령어 gcloud storage 명령어
업로드된 객체에 메타데이터 설정 
gsutil setmeta
 
gcloud storage objects update
참고

gsutil setmeta는 단일 반복 가능한 -h 플래그를 사용하여 설정하거나 삭제할 메타데이터를 지정합니다. gcloud storage objects update는 각 메타데이터 필드 (예: --content-type, --clear-cache-control 또는 --update-custom-metadata)에 별도의 플래그를 사용합니다.

gsutil setmeta에서는 -h 플래그를 사용하여 전체 헤더 이름 (예: -h "x-goog-meta-icecreamflavor:vanilla")을 설정합니다. gcloud storage objects update에서는 대신 --update-custom-metadata 플래그를 사용하며 키-값 쌍 (예: --update-custom-metadata=icecreamflavor=vanilla)을 사용합니다. 맞춤 메타데이터 필드를 삭제하려면 gsutil setmeta에서는 -h "x-goog-meta-icecreamflavor"를 사용하고 gcloud storage objects update에서는 --remove-custom-metadata=icecreamflavor를 사용합니다.
작업 gsutil 명령어 gcloud storage 명령어
객체 상태 표시 
gsutil stat
 
gcloud storage objects list --stat --fetch-encrypted-object-hashes
참고

gcloud storage objects list --stat의 출력 형식은 gsutil stat의 출력 형식과 다르며, 일관되지 않은 간격과 관련된 알려진 문제가 있습니다. gsutil stat의 출력을 파싱하도록 작성된 스크립트는 새로운 출력 형식을 처리하기 위해 조정이 필요할 수 있습니다.

다음 단계

명령어 및 플래그 매핑에 관한 자세한 내용은 gsutil GitHub 저장소의 이전 참조를 참고하세요.