gsutil 설치

이 페이지에서는 HTTPS를 사용하여 명령줄에서 Cloud Storage에 액세스할 수 있는 도구인 gsutil의 설치 및 설정을 설명합니다.

gsutil을 설치하면 공개 데이터에 대한 즉시 읽기 또는 쓰기 액세스가 가능합니다. Cloud Storage 서비스를 인증하면 공유되는 보호된 데이터에 대한 읽기 또는 쓰기 액세스가 가능합니다. 결제를 사용 설정하면 버킷을 직접 만들고 관리할 수 있습니다.

시스템 요구사항

  • gsutil 도구는 Linux/Unix, Mac OS, Windows(XP 이상)에서 실행됩니다.

  • gsutil 버전 5.0 이상에는 Python 3이 필요합니다.

  • 복합 객체를 사용하려면 컴파일된 crcmod를 설치해야 합니다. Windows에서는 32비트 Python용으로만 제공됩니다. crcmod에 대한 자세한 내용을 보려면 gsutil을 설치하고 gsutil help crc32c 명령어를 사용하여 도움말 항목을 참조하세요.

gsutil 설치

공식적으로 지원되는 gsutil의 설치 및 업데이트 방법은 Google Cloud CLI를 사용하는 것입니다.

Google Cloud CLI의 일부로 gsutil 설치

운영체제의 안내에 따라 gsutil을 Google Cloud CLI의 일부로 설치하세요.

Linux
  1. 지원되는 Python 버전이 있는지 확인합니다. Google Cloud CLI에는 Python 3.8~3.12가 필요합니다. x86_64 Linux 패키지에는 기본적으로 선호되는 번들 Python 인터프리터가 포함되어 있습니다. Python 인터프리터를 선택하고 구성하는 방법에 대한 자세한 내용은 gcloud topic startup를 참조하세요.
  2. 다음 중 하나를 다운로드합니다.
    플랫폼 패키지 이름 크기 SHA256 체크섬
    Linux 64비트

    (x86_64)

    		 google-cloud-cli-linux-x86_64.tar.gz 130.6MB b7db92463d1f5c355c94f7a1af107f26ed17b191deb3de6746dc39c48293787d
    Linux 64비트

    (Arm)

    		 google-cloud-cli-linux-arm.tar.gz 52.1MB feaf39c5a3f27d08c6056e296202ff72fde9f4bfcad96724c97a78acb360c2d7
    Linux 32비트

    (x86)

    		 google-cloud-cli-linux-x86.tar.gz 52.2MB 338a1be595215a8d4e6aae4ca97f5aea4410b64a041dac6160c9b579e059be7c

    Linux 보관 파일을 다운로드하려면 다음 명령어를 실행합니다. 

    curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz

    위 표를 참조하고 google-cloud-cli-linux-x86_64.tar.gz을 구성에 적용되는 *.tar.gz 패키지 이름으로 바꿉니다.

  3. 파일 콘텐츠를 파일 시스템(홈 디렉터리 추천)에 추출하려면 다음 명령어를 실행합니다. 
    tar -xf google-cloud-cli-linux-x86_64.tar.gz
    선택사항: 기존 설치를 교체하려면 기존 google-cloud-sdk 디렉터리를 제거한 다음 아카이브를 동일한 위치로 추출합니다.
  4. gcloud CLI를 경로에 추가합니다. 추출한 폴더의 루트에서 다음 명령어를 사용하여 설치 스크립트를 실행합니다. 
    ./google-cloud-sdk/install.sh
    이 작업은 비대화형(예: 스크립트 사용)으로 수행하거나 환경설정을 플래그로 제공하여 수행할 수도 있습니다. 사용 가능한 플래그를 보려면 다음을 실행합니다. 
    ./google-cloud-sdk/install.sh --help
    선택사항:
    • gcloud CLI 개선을 위해 익명 사용 통계를 보내려면 메시지가 표시될 때 Y로 응답합니다.
    • PATH에 gcloud CLI를 추가하고 명령어 완성을 사용 설정하려면 메시지가 표시될 때 Y로 응답합니다.
  5. 변경사항이 적용되도록 새 터미널을 엽니다.
  6. gcloud CLI를 초기화하려면 gcloud init를 실행합니다. 
    7. ./google-cloud-sdk/bin/gcloud init
  7. 선택사항: 구성요소 관리자를 사용하여 추가 구성요소를 설치합니다.
Debian/Ubuntu

패키지 콘텐츠

Debian 및 Ubuntu 시스템에서 gcloud CLI는 설치용 패키지 형식으로 제공됩니다. 이 패키지에는 gcloud, gcloud alpha, gcloud beta, gsutil, bq 명령어만 포함됩니다. gcloud 명령어를 사용하여 애플리케이션을 배포하는 데 필요한 kubectl 또는 App Engine 확장 프로그램은 포함되지 않습니다. 이러한 구성요소를 사용하려면 별도로 설치해야 합니다.

시작하기 전에

gcloud CLI를 설치하기 전 운영체제가 다음 요구사항을 충족하는지 확인합니다.

  • 지원 종료에 도달하지 않은 Ubuntu 출시 버전 또는 지원 종료에 도달하지 않은 Debian 안정적인 출시 버전
  • 패키지가 최근에 업데이트되었습니다. 
    sudo apt-get update
  • apt-transport-https가 있고 curl이 설치되어 있습니다. 
    sudo apt-get install apt-transport-https ca-certificates gnupg curl
설치
  1. Google Cloud 공개 키를 가져옵니다.

    • 최신 배포판(Debian 9+ 또는 Ubuntu 18.04+)의 경우 다음 명령어를 실행합니다.

      curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
    • 이전 배포판의 경우 다음 명령어를 실행합니다. 
      curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -

    • 배포판의 apt-key 명령어가 --keyring 인수를 지원하지 않는 경우 다음 명령어를 실행합니다.

      curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -

    • 키가 만료되어 최신 업데이트를 가져올 수 없는 경우에는 최신 apt-get.gpg 키 파일을 가져오세요.

  2. 패키지 소스로 gcloud CLI 배포 URI를 추가합니다.
    • 최신 배포판(Debian 9+ 또는 Ubuntu 18.04+)의 경우 다음 명령어를 실행합니다. 
      echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list

    • 서명 옵션을 지원하지 않는 이전 배포판의 경우에는 다음 명령어를 실행합니다.

      echo "deb https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
  3. gcloud CLI 업데이트 및 설치: 
    sudo apt-get update && sudo apt-get install google-cloud-cli
    프롬프트 사용 중지 또는 테스트 실행과 같은 추가 apt-get 옵션은 apt-get 설명 페이지를 참고하세요.

    Docker 팁: Docker 이미지 내에 gcloud CLI를 설치하는 경우 대신 단일 RUN 단계를 사용합니다.

    RUN echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list && curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg && apt-get update -y && apt-get install google-cloud-sdk -y
    gpg --dearmor 명령어를 지원하지 않는 이전의 기본 이미지의 경우: 
    RUN echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list && curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | apt-key --keyring /usr/share/keyrings/cloud.google.gpg  add - && apt-get update -y && apt-get install google-cloud-cli -y
  4. (선택 사항) 다음 추가 구성요소를 설치합니다.
    • google-cloud-cli
    • google-cloud-cli-anthos-auth
    • google-cloud-cli-app-engine-go
    • google-cloud-cli-app-engine-grpc
    • google-cloud-cli-app-engine-java
    • google-cloud-cli-app-engine-python
    • google-cloud-cli-app-engine-python-extras
    • google-cloud-cli-bigtable-emulator
    • google-cloud-cli-cbt
    • google-cloud-cli-cloud-build-local
    • google-cloud-cli-cloud-run-proxy
    • google-cloud-cli-config-connector
    • google-cloud-cli-datastore-emulator
    • google-cloud-cli-firestore-emulator
    • google-cloud-cli-gke-gcloud-auth-plugin
    • google-cloud-cli-kpt
    • google-cloud-cli-kubectl-oidc
    • google-cloud-cli-local-extract
    • google-cloud-cli-minikube
    • google-cloud-cli-nomos
    • google-cloud-cli-pubsub-emulator
    • google-cloud-cli-skaffold
    • google-cloud-cli-spanner-emulator
    • google-cloud-cli-terraform-validator
    • google-cloud-cli-tests
    • kubectl

    예를 들어 google-cloud-cli-app-engine-java 구성요소는 다음과 같이 설치할 수 있습니다.

    sudo apt-get install google-cloud-cli-app-engine-java
  5. 시작하려면 gcloud init을 실행합니다. 
    gcloud init

gcloud CLI 버전 다운그레이드

VERSION이123.0.0 형식이고 gcloud CLI의 특정 버전으로 되돌리려면 다음 명령어를 실행합니다.

sudo apt-get update && sudo apt-get install google-cloud-cli=123.0.0-0

최신 출시 버전 10개가 저장소에서 항상 제공됩니다.

참고: 371.0.0 이전 출시 버전의 경우 패키지 이름이 google-cloud-sdk입니다.

Red Hat/Fedora/CentOS

패키지 콘텐츠

gcloud CLI는 Red Hat Enterprise Linux 7, 8, 9, Fedora 33 및 34, CentOS 7 및 8 시스템에 설치할 수 있는 패키지 형식으로 제공됩니다. 이 패키지에는 gcloud, gcloud alpha, gcloud beta, gsutil, bq 명령어만 포함됩니다. gcloud 명령어를 사용하여 애플리케이션을 배포하는 데 필요한 kubectl 또는 App Engine 확장 프로그램은 포함되지 않으며, 이 섹션의 뒷부분에 설명된 대로 별도로 설치할 수 있습니다.

설치
  1. gcloud CLI 저장소 정보로 DNF를 업데이트합니다. 다음 샘플 명령어는 Red Hat Enterprise Linux 9 호환 가능한 설치를 위한 것이지만 해당 구성의 필요에 따라 설정을 업데이트해야 합니다.
    sudo tee -a /etc/yum.repos.d/google-cloud-sdk.repo << EOM
[google-cloud-cli]
name=Google Cloud CLI
baseurl=https://packages.cloud.google.com/yum/repos/cloud-sdk-el9-x86_64
enabled=1
gpgcheck=1
repo_gpgcheck=0
gpgkey=https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
EOM
  2. Fedora 34 또는 35에 설치하는 경우 libxcrypt-compat.x86_64를 설치합니다. 
    sudo dnf install libxcrypt-compat.x86_64
  3. gcloud CLI 설치: 
    sudo dnf install google-cloud-cli
  4. (선택 사항) 다음 추가 구성요소를 설치합니다.
    • google-cloud-cli
    • google-cloud-cli-anthos-auth
    • google-cloud-cli-app-engine-go
    • google-cloud-cli-app-engine-grpc
    • google-cloud-cli-app-engine-java
    • google-cloud-cli-app-engine-python
    • google-cloud-cli-app-engine-python-extras
    • google-cloud-cli-bigtable-emulator
    • google-cloud-cli-cbt
    • google-cloud-cli-cloud-build-local
    • google-cloud-cli-cloud-run-proxy
    • google-cloud-cli-config-connector
    • google-cloud-cli-datastore-emulator
    • google-cloud-cli-firestore-emulator
    • google-cloud-cli-gke-gcloud-auth-plugin
    • google-cloud-cli-kpt
    • google-cloud-cli-kubectl-oidc
    • google-cloud-cli-local-extract
    • google-cloud-cli-minikube
    • google-cloud-cli-nomos
    • google-cloud-cli-pubsub-emulator
    • google-cloud-cli-skaffold
    • google-cloud-cli-spanner-emulator
    • google-cloud-cli-terraform-validator
    • google-cloud-cli-tests
    • kubectl

    예를 들어 google-cloud-cli-app-engine-java 구성요소는 다음과 같이 설치할 수 있습니다.

    sudo dnf install google-cloud-cli-app-engine-java
  5. 시작하려면 gcloud init을 실행합니다. 
    gcloud init

gcloud CLI 버전 다운그레이드

VERSION이 123.0.0 형식인 특정 버전의 gcloud CLI로 되돌려야 할 경우에는 다음을 실행합니다. sudo dnf downgrade google-cloud-cli-VERSION 최신 출시 버전 10개가 저장소에서 항상 제공됩니다. 참고: 371.0.0 이전 출시 버전의 경우 패키지 이름이 google-cloud-sdk입니다.

macOS
  1. 지원되는 Python 버전이 있는지 확인합니다.
    • 현재 Python 버전을 확인하려면 python3 -V 또는 python -V를 실행합니다. 지원되는 버전은 Python 3.8~3.12입니다.
    • 기본 설치 스크립트는 CPython의 Python 3.11을 설치하도록 제공합니다.
    • 그렇지 않고 지원되는 Python 버전을 설치하려면 Python.org macOS용 Python 출시 버전을 방문하세요.
    • 머신에 여러 Python 인터프리터가 설치된 경우 셸 내에서 선호하는 인터프리터의 경로를 가리키도록 CLOUDSDK_PYTHON 환경 변수를 설정합니다.
    • Python 인터프리터를 선택하고 구성하는 방법에 대한 자세한 설명은 gcloud topic startup를 참조하세요.
  2. 다음 중 하나를 다운로드합니다.

    3. 플랫폼 패키지 크기 SHA256 체크섬
    macOS 64비트

    (x86_64)

    		 google-cloud-cli-darwin-x86_64.tar.gz 52.2MB aaa06b5b0750f689eb11228de4bb632352d1e5c190e02c0e7bdb83472e494821
    macOS 64비트

    (ARM64, Apple M1 silicon)

    		 google-cloud-cli-darwin-arm.tar.gz 52.2MB 92be93c51405f166ec06bc3226ad64f93572178b02b0fe0d9d09fd328b0ccd0e
    macOS 32비트

    (x86)

    		 google-cloud-cli-darwin-x86.tar.gz 50.9MB bc2652bc43fa5b68c560528503d6f228309c719056867dc92976c117d6bcfb37
    1. 파일 시스템의 임의 위치(예: 홈 디렉터리)에 보관 파일 압축을 풉니다. macOS에서는 다운로드된 .tar.gz 보관 파일을 원하는 위치에서 열어 압축을 풀 수 있습니다.

      기존 설치를 대체하려면 기존 google-cloud-sdk 디렉터리를 삭제하고 동일한 위치에 보관 파일 압축을 풉니다.

    2. (선택사항) 설치 스크립트를 사용하여 gcloud CLI 도구를 PATH에 추가합니다. 또한 셸인 사용 통계 수집에 명령어 완성을 선택하고 Python 3.11을 설치합니다.

      다음 명령어를 사용하여(마지막 단계에서 추출한 폴더의 루트에서) 스크립트를 실행합니다. 

      ./google-cloud-sdk/install.sh
      This can also be done non-interactively (for example, using a script) by providing preferences as flags. To describe the available flags, run: 
      ./google-cloud-sdk/install.sh --help
      To run the install script with screen reader mode on: 
      ./google-cloud-sdk/install.sh --screen-reader=true
      Open a new terminal so that the changes take effect.
    3. To initialize the gcloud CLI, run gcloud init: 
      4. ./google-cloud-sdk/bin/gcloud init
    4. Optional. Install additional components using the component manager.
Windows
    The Google Cloud CLI works on Windows 8.1 and later and Windows Server 2012 and later.

  1. Download the Google Cloud CLI installer.

    Alternatively, open a PowerShell terminal and run the following PowerShell commands: 

    (New-Object Net.WebClient).DownloadFile("https://dl.google.com/dl/cloudsdk/channels/rapid/GoogleCloudSDKInstaller.exe", "$env:Temp\GoogleCloudSDKInstaller.exe")

& $env:Temp\GoogleCloudSDKInstaller.exe

  2. 설치 프로그램을 실행하고 안내 메시지를 따릅니다. 설치 프로그램 서명자는 Google LLC입니다.

    스크린 리더를 사용하는 경우 스크린 리더 모드 설정 체크박스를 선택합니다. 이 옵션은 유니코드 스피너 대신 상태 추적기를 사용하고, 진행 상태를 백분율로 표시하고, 테이블을 평면화하도록 gcloud를 구성합니다. 자세한 내용은 가용성 기능 가이드를 참조하세요.

  3. Google Cloud CLI에는 Python이 필요하며 지원되는 버전은 Python 3.8~3.12입니다. 기본적으로 Windows 버전의 Google Cloud CLI는 Python 3과 함께 제공됩니다. Google Cloud CLI를 사용하려면 운영체제에서 지원되는 Python 버전을 실행할 수 있어야 합니다.

    설치 프로그램은 필요한 Python 버전을 포함하여 필요한 모든 종속 항목을 설치합니다. Google Cloud CLI는 기본적으로 Python 3을 설치 및 관리하지만 필요한 경우 번들 Python 설치 옵션을 선택 해제하여 기존 Python 설치를 사용할 수 있습니다. 기존 Python 설치를 사용하는 방법은 gcloud topic startup을 참조하세요.

  4. 설치가 완료되면 설치 프로그램에서 시작 메뉴 및 바탕화면 바로가기를 만들고, Google Cloud CLI 셸을 시작하고, gcloud CLI를 구성할 수 있는 옵션이 제공됩니다. 셸을 시작하고 설치를 구성하는 옵션은 선택한 상태로 두세요. 설치 프로그램이 터미널 창을 시작하고 gcloud init 명령어를 실행합니다.

  5. 기본 설치에는 gcloud 명령어를 사용하여 애플리케이션을 배포하는 데 필요한 App Engine 확장 프로그램이 포함되지 않습니다. 이러한 구성요소는 gcloud CLI 구성요소 관리자를 사용해서 설치할 수 있습니다.
문제 해결 팁:
  • find 명령어가 인식되지 않아 설치에 실패하는 경우 find가 들어 있는 폴더를 포함하도록 PATH 환경 변수가 설정되어 있는지 확인합니다. 일반적으로는, C:\WINDOWS\system32;입니다.
  • gcloud CLI를 제거한 후 gcloud CLI를 다시 설치하려면 먼저 시스템을 재부팅해야 합니다.
  • 압축을 풀 수 없다면 설치 프로그램을 관리자로 실행합니다.

components update 명령어 gcloud components update를 사용하여 업데이트를 수행합니다.

보호된 데이터 액세스를 위해 사용자 인증 정보 설정하기

보호된 데이터에 액세스하거나 보호된 버킷에 쓰려면 사용자 인증 정보(인증)를 설정해야 합니다. 예를 들어 다른 누군가가 Cloud Storage 계정을 만들고 사용자나 다른 특정 개인만 액세스할 수 있는 데이터를 업로드한 경우 Cloud Storage 서비스에 사용자 인증 정보를 설정해야 이 데이터에 액세스할 수 있습니다.

gsutil을 Google Cloud CLI의 일부로 사용할 경우 Cloud Storage 리소스에 대한 액세스를 인증하고 승인하는 데 OAuth2가 사용됩니다. 액세스 권한을 설정하려면 gcloud init 명령어를 실행하고 명령줄에 제공되는 안내에 따라 사용자 계정에 로그인합니다. 위의 설치 단계를 수행한 경우 이 설정을 이미 완료했을 수 있습니다. gcloud init를 이전에 실행한 경우 명령어를 다시 실행하면 구성을 다시 초기화하거나 새 구성을 만들지 묻는 메시지가 표시됩니다. 자세한 내용은 Google Cloud CLI 초기화를 참조하세요.

이상입니다. 보호된 데이터에 액세스할 준비가 되었습니다. gsutil 명령어 목록을 보려면 명령 프롬프트에서 gsutil을 입력하세요.

문제 해결

gcloud init 명령어를 사용하여 gsutil을 인증하려 시도할 때도 예상 버킷 또는 객체에 액세스할 수 없는 경우 시스템에 기존 독립형 gsutil 버전과 여기에 설치된 gsutil의 Google Cloud CLI 번들 버전이 모두 설치되어 있을 수 있습니다. gsutil version -l 명령어를 실행하고 using cloud sdk 값을 확인합니다. False이면 명령어를 실행할 때 시스템이 독립형 버전의 gsutil을 사용한다는 의미입니다. 시스템에서 독립 실행형 gsutil 버전을 삭제하는 것이 좋습니다. 하지만 gsutil config -a 또는 gsutil config -e를 사용하여 인증할 수도 있습니다.

HMAC로 인증

OAuth 2.0을 사용하여 gsutil을 인증하는 것이 좋지만 사용자 인증 정보용 HMAC 키를 사용할 수도 있습니다. HMAC를 사용하여 인증하려면 다음

gsutil config -a
명령어를 사용합니다.

이 명령어를 사용하면 HMAC 키와 연결된 보안 비밀 및 액세스 ID를 입력하라는 메시지가 표시되는 인증 프로세스가 수행됩니다.

HMAC 키로 인증할 때는 gcloud config set pass_credentials_to_gsutil false 명령어를 사용하여 Google Cloud CLI에서 전달되는 사용자 인증 정보를 중지해야 합니다.

mTLS 사용 설정

상호 TLS(mTLS)를 사용 설정할 수도 있습니다. 기기에 mTLS가 사용 설정되면 기기는 storage.mtls.googleapis.com에 연결을 시도합니다. 연결이 허용되기 전에 Cloud Storage는 기기의 인증서를 확인합니다.

인증서를 가져오는 가장 간단한 방법은 Google Cloud CLI를 사용하는 것입니다. .boto 파일에서 '사용자 인증 정보'에 다음 값을 설정하여 수동으로 설정할 수 있습니다.

  1. use_client_certificate: mTLS 사용 여부를 제어하는 플래그입니다.
  2. cert_provider_command: gsutil에서 읽을 수 있도록 인증서를 stdout에 출력하는 셸 명령어입니다.

직접 사용해 보기

Google Cloud를 처음 사용하는 경우 계정을 만들어 실제 시나리오에서 Cloud Storage의 성능을 평가할 수 있습니다. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

Cloud Storage 무료로 사용해 보기