이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Google Cloud CLI Docker 이미지 설치

Google Cloud CLI Docker 이미지를 사용하면 Artifact Registry에서 특정 버전의 gcloud CLI를 Docker 이미지로 가져오고, 격리되어 올바르게 구성된 컨테이너에서 Google Cloud CLI 명령어를 빠르게 실행할 수 있습니다.

Google Cloud CLI Docker 이미지는 Debian 또는 Alpine 이미지 위에 설치되는 gcloud CLI입니다. Google Cloud CLI Docker 이미지를 사용하면 로컬 머신에 gcloud를 수동으로 설치하지 않고도 gcloud와 번들 구성요소를 사용할 수 있습니다.

Docker 이미지 옵션

Google Cloud CLI Docker 이미지에는 6가지가 있으며 모두 gcloud, gsutil, bq 명령줄 도구를 설치합니다. 최소 환경의 경우 :stable 이미지를 설치하는 것이 좋습니다. 안정적인 이미지를 자체 배포의 기본 이미지로 사용할 수도 있습니다. 이렇게 하면 이미지에 필요한 구성요소와 패키지만 유연하게 설치할 수 있습니다.

:stable, :VERSION-stable: gsutil 및 bq 구성요소가 포함된 gcloud 설치를 제공합니다. 이 이미지는 최신 Google 제공 Debian 12 기본 이미지를 기반으로 빌드됩니다. 이 이미지는 linux/amd 및 linux/arm 플랫폼을 모두 지원합니다. 특정 gcloud 버전을 설치하려면 :VERSION-stable 태그를 사용하세요.

Alpine 기반 이미지를 사용하려면 다음 이미지를 설치하면 됩니다.

:alpine, :VERSION-alpine: 안정화 버전과 유사하지만 최신 Alpine 3.19 기본 이미지를 기반으로 빌드됩니다. 이 이미지는 linux/amd 및 linux/arm 플랫폼을 모두 지원합니다. 특정 gcloud 버전을 설치하려면 :VERSION-alpine 태그를 사용하세요.

추가 구성요소 또는 패키지가 미리 설치된 이미지를 사용하려면 다음 옵션 중 하나를 설치하면 됩니다.

:emulators, :VERSION-emulators: 모든 에뮬레이터 구성요소가 추가된 안정화 버전과 유사합니다. 이 이미지는 최신 Google 제공 Debian 12 기본 이미지를 기반으로 빌드되며 구성요소 관리자를 사용하여 구성요소를 설치합니다. 이 이미지는 linux/amd 및 linux/arm 플랫폼을 모두 지원합니다. 특정 gcloud 버전을 설치하려면 :VERSION-emulators 태그를 사용하세요.
:latest, :VERSION: 안정화 버전과 유사하지만 추가 구성요소(이미지에 설치된 구성요소 목록은 아래에 나열됨)가 사전 설치되어 있습니다. 이 이미지는 최신 Google 제공 Debian 12 기본 이미지를 기반으로 빌드되며 deb 패키지를 사용하여 구성요소를 설치합니다. 특정 gcloud 버전을 설치하려면 :VERSION 태그를 사용하세요.
:slim, :VERSION-slim: 안정화 버전과 유사하지만 curl, python3-crcmod, apt-transport-https, lsb-release, openssh-client, git, make, gnupg와 같은 서드 파티 패키지가 추가로 포함되어 있습니다. 이 이미지는 최신 Google 제공 Debian 12 기본 이미지를 기반으로 빌드됩니다. 이 이미지는 linux/amd 및 linux/arm 플랫폼을 모두 지원합니다. 특정 gcloud 버전을 설치하려면 :VERSION-slim 태그를 사용하세요.
:debian_component_based, :VERSION-debian_component_based: 안정화 버전과 유사하며 추가 구성요소(이미지에 설치된 구성요소 목록은 아래에 나열됨)가 사전 설치되어 있습니다. 이 이미지는 최신 Google 제공 Debian 12 기본 이미지를 기반으로 빌드되며 구성요소 관리자를 사용하여 구성요소를 설치합니다. 이 이미지는 linux/amd 및 linux/arm 플랫폼을 모두 지원합니다. 특정 gcloud 버전을 설치하려면 :VERSION-debian_component_based 태그를 사용하세요.

프로덕션에서 특정 버전 사용

특정 gcloud 버전에 연결되지 않은 태그를 사용하면 환경에 다음과 같은 브레이킹 체인지가 발생할 수 있습니다.

Google Cloud SDK 버전 업데이트로 인해 도구의 동작이 변경될 수 있습니다.
설치된 구성요소 목록 업데이트

브레이킹 체인지가 발생할 수 있으므로 프로덕션 환경에서는 다음 중 하나를 사용하는 것이 좋습니다.

버전이 지정된 태그(예: :496.0.0-stable)
특정 이미지 해시(예: gcr.io/google.com/cloudsdktool/google-cloud-cli@sha256:9c0efc06918d5405b13bfe4bb5ce1d98ea4695cc703446e9e0aa0ee8800622df)
자체 저장소에 이미지 호스팅

또한 최신 gcloud 버전을 가져오기 위해 주기적으로 이미지를 업데이트해야 합니다.

각 태그에 설치된 구성요소

구성요소	:stable	:alpine	:emulators	:latest	:slim	:debian_component_based
App Engine Go 확장 프로그램				x		x
Appctl						x
BigQuery 명령줄 도구	x	x	x	x	x	x
번들 Python 3.9	x	x	x	x	x	x
Bigtable 명령줄 도구				x		x
Bigtable 에뮬레이터			x	x		x
Cloud Datastore 에뮬레이터			x	x		x
Cloud Firestore 에뮬레이터			x	x
Cloud Pub/Sub 에뮬레이터			x	x		x
Spanner 에뮬레이터			x	x
Cloud Storage 명령줄 도구	x	x	x	x	x	x
Google Cloud CLI 핵심 라이브러리	x	x	x	x	x	x
Google Cloud CRC32C 해시 도구	x	x	x	x	x	x
Kustomize						x
Minikube						x
Nomos CLI						x
On-Demand Scanning API 추출 도우미				x		x
Skaffold						x
anthos-auth						x
gcloud Alpha 명령어	x			x	x	x
gcloud 베타 명령어			x	x	x	x
gcloud 앱 자바 확장 프로그램						x
gcloud 앱 Python 확장 프로그램						x
gcloud 앱 Python 확장 프로그램(Extra Libraries)				x		x
gke-gcloud-auth-plugin				x		x
kpt				x		x
kubectl				x		x

Docker 이미지 설치

Docker 이미지 자체는 Artifact Registry에서 호스팅되며 저장소 이름은 gcr.io/google.com/cloudsdktool/google-cloud-cli입니다. us.gcr.io, eu.gcr.io, asia.gcr.io 저장소를 사용하여 이미지를 사용할 수도 있습니다.

안정화(stable) Google Cloud CLI 출시 버전의 이미지(gcr.io/google.com/cloudsdktool/google-cloud-cli:stable)를 사용하려면 다음 명령어를 실행하여 Artifact Registry에서 가져옵니다.
```
docker pull gcr.io/google.com/cloudsdktool/google-cloud-cli:489.0.0-stable
```
이미지 해시를 사용하여 저장소에서 특정 Docker 이미지를 가져올 수도 있습니다. 이미지 해시를 사용하여 이전 예시 (:489.0.0-stable)에서 동일한 이미지를 가져오려면 다음 명령어를 실행합니다.
```
docker pull gcr.io/google.com/cloudsdktool/google-cloud-cli@sha256:589a0db8919614ef919dfd6ed89127211b4b6bf5ee6a2e2ce92abf33cbfe49d8
```
다음을 실행하여 설치를 확인합니다.
```
docker run --rm gcr.io/google.com/cloudsdktool/google-cloud-cli:489.0.0-stable gcloud version
```
항상 최신 출시 버전을 가리키는 플로팅 :stable 태그를 사용한 경우 다음 명령어를 실행하여 설치를 확인합니다.
```
docker run --rm gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud version
```

Google Cloud CLI Docker 이미지로 인증

다음 명령어 중 하나를 실행하여 Google Cloud CLI Docker 이미지로 인증합니다.

gcloud auth login을 실행하여 사용자 인증 정보로 gcloud를 인증합니다.

docker run -ti --name gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud auth login

Google Cloud API를 사용하는 애플리케이션을 인증해야 하는 경우 --update-adc 옵션을 전달합니다.

docker run -ti --name gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud auth login --update-adc

컨테이너를 열 때마다 선택되는 기본 프로젝트를 설정하려면 다음 명령어를 실행합니다.
```
docker run -ti --name gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli:stable /bin/bash -c 'gcloud auth login && gcloud config set project your-project'
```
인증이 성공하면 gcloud-config container의 볼륨에 사용자 인증 정보가 보존됩니다.

참고: gcloud-config container에 이제 Google Cloud 사용자 인증 정보가 포함된 볼륨이 있습니다. 다른 컨테이너에서 gcloud-config 볼륨을 사용하지 마세요.

확인하려면 --volumes-from과 함께 컨테이너를 실행하여 사용자 인증 정보를 사용하는 컴퓨팅 인스턴스를 나열합니다.
```
docker run --rm --volumes-from gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud compute instances list --project your-project
```

서비스 계정을 사용하여 인증하려면 auth/credential_file_override 속성을 사용하여 마운트된 서비스 계정의 경로를 설정하세요. 그런 다음 CLOUDSDK_CONFIG 환경 변수를 사용하여 마운트된 서비스 계정을 읽도록 구성을 업데이트합니다.

다음 예시에서는 mycloud 구성에 auth/credential_file_override가 이미 설정되어 있습니다. 구성은 컨테이너 내에 별도의 볼륨 마운트로 있는 인증서 파일을 가리킵니다.

$ docker run -ti -e CLOUDSDK_CONFIG=/config/mygcloud \
              -v `pwd`/mygcloud:/config/mygcloud \
              -v `pwd`:/certs  gcr.io/google.com/cloudsdktool/google-cloud-cli:stable /bin/bash

bash-4.4# gcloud config list
[auth]
credential_file_override = /certs/svc_account.json

bash-4.4# head -10  /certs/svc_account.json
{
   "type": "service_account",
   "project_id": "project_id1",
....

bash-4.4# gcloud projects list
PROJECT_ID           NAME         PROJECT_NUMBER
project_id1          GCPAppID     1071284184432

환경 변수 설정에 대한 자세한 내용은 다음을 참조하세요.

추가 구성요소 설치

Google Cloud CLI Docker 이미지에 추가 구성요소를 설치할 수 있습니다. 추가 구성요소를 설치하는 접근 방식은 기본 이미지 유형에 따라 다릅니다.

Debian 기반 이미지

기본적으로 안정적인 이미지(:stable 및 :VERSION-stable)에는 bq 및 gsutil 이외의 구성요소가 설치되어 있지 않습니다. 안정적인 이미지에 구성요소를 추가로 설치하려면 다음 중 하나를 실행합니다.

:stable 이미지 Dockerfile을 사용하여 자체 이미지 빌드: apt-get을 통해 직접 사용할 수 없는 패키지(예: docker engine)를 설치합니다.
런타임에 추가 패키지 또는 구성요소 설치: 이미지를 호스팅하지 않고 맞춤설정합니다.

`:stable` 이미지 Dockerfile을 사용하여 자체 이미지 빌드

:stable의 추가 구성요소로 자체 이미지를 빌드하려면 cloud-sdk-docker GitHub 디렉터리를 클론하고 docker build 명령어를 사용하여 INSTALL_COMPONENTS 인수와 함께 Dockerfile에서 :stable Docker 이미지를 빌드하면 됩니다. 예를 들어 datastore-emulator 구성요소를 추가하려면 다음 안내를 따르세요.

# clone the GitHub docker directory 
$ git clone https://github.com/GoogleCloudPlatform/cloud-sdk-docker.git
$ docker build --build-arg CLOUD_SDK_VERSION=<release_version> \
   --build-arg INSTALL_COMPONENTS="google-cloud-cli-datastore-emulator=<release_version>-0" \
   -t my-cloud-sdk-docker:stable .

런타임에 추가 패키지 또는 구성요소 설치

stable Docker 이미지를 가져온 경우 런타임 중에 다음 구성요소를 추가로 설치할 수 있습니다.

COMPONENTS 환경 변수를 사용하여 gcloud 구성요소를 설치할 수 있습니다
APT_PACKAGES 환경 변수를 사용하여 apt-packages를 설치할 수 있습니다

예를 들어 런타임에 cbt 및 kpt 구성요소를 설치하려면 다음 명령어를 실행하면 됩니다.

docker run -e COMPONENTS='google-cloud-cli-cbt google-cloud-cli-kpt' \
gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud version

Docker 이미지를 실행하는 동안 apt-packages curl 및 gcc를 설치하려면 다음 명령어를 실행합니다.

docker run -e APT_PACKAGES='curl gcc' \
gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud version

Alpine 기반 이미지

Alpine 기반 이미지의 추가 구성요소를 설치하려면 cloud-sdk 이미지를 기본 이미지로 사용하는 Dockerfile을 만듭니다.

예를 들어 kubectl 및 app-engine-java 구성요소를 추가하려면 다음 안내를 따르세요.

다음과 같이 Dockerfile을 만듭니다.

FROM gcr.io/google.com/cloudsdktool/google-cloud-cli:alpine
RUN apk --update add gcompat openjdk8-jre
RUN gcloud components install app-engine-java kubectl

다음 명령어를 실행하여 이미지를 빌드합니다.

docker build -t my-cloud-sdk-docker:alpine .

Alpine 기반 이미지의 경우 추가 구성요소의 종속 항목을 수동으로 설치해야 합니다.

`:stable` 이미지로 마이그레이션

:latest, :slim, :emulators, :alpine, :debian_component_based Docker 이미지를 사용하는 경우 이미지 크기를 줄이고 보안 수정사항을 개선하려면 Debian 기반 :stable 이미지로 마이그레이션하는 것이 좋습니다. :stable 이미지로 마이그레이션하는 단계는 :stable 이미지로 마이그레이션을 참조하세요.

이미지 지원 받기

Artifact Registry에 호스팅된 이미지는 완전한 기능을 갖춘 Google Cloud CLI 설치를 제공합니다. Docker 이미지와 관련된 버그나 문제가 발견되면 지원 티켓을 만들 수 있습니다.

추가 구성요소, 패키지 또는 도구가 포함된 이미지가 필요한 경우 Google Cloud CLI Docker 이미지 위에 자체 이미지 레이어를 만들 수 있습니다.

문제 해결

Docker 이미지를 가져오는 중에 failed to fetch <image-tag> 오류가 표시되면 어떻게 해야 하나요?

Google Cloud CLI Docker 이미지를 가져오려고 할 때 failed to fetch <image-tag> 오류가 발생하면 지원 중단되고 삭제된 이미지 태그를 가져오려고 하는 것일 수 있습니다. 사용 가능한 Docker 이미지 옵션은 Docker 이미지 옵션을 확인하고 지원되는 태그 중 하나로 마이그레이션합니다.

현재 워크플로를 지원하기 위해 :stable Docker 이미지를 직접 확장할 수 없는 사용 사례는 무엇인가요?

다음 표에는 워크플로에 맞게 :stable Docker 이미지를 직접 확장할 수 없는 사용 사례와 해결 옵션이 나와 있습니다.

사용 사례	해결 옵션
`app-engine` 구성요소 (`:latest` 또는 `:debian_component_based` Docker 이미지에 사용됨)는 Debian 12와 호환되지 않습니다.	호환되는 Debian (Debian 11) 이미지에서 자체 이미지를 빌드하여 `app-engine` 구성요소를 설치합니다.
docker 또는 docker-buildx와 같은 서드 파티 패키지가 `:stable` 이미지에 포함되지 않음	이러한 서드 파티 패키지가 필요한 경우 자체 이미지를 빌드하거나 `:stable` Docker 이미지에 이러한 패키지를 수동으로 설치합니다.

스캐너가 Docker 이미지에서 취약점을 발견한 경우 어떻게 해야 하나요?

Google Cloud CLI Docker 이미지는 Artifact Registry에서 호스팅됩니다. 이미지는 매일 스캔되며, 새로운 gcloud 출시가 있을 때마다 Common Vulnerabilities and Exposures(CVE)가 완화됩니다. 그러나 스캐너가 해결되지 않은 취약점을 Google Cloud CLI Docker 이미지에서 감지한 경우 다음 정보가 포함된 버그를 신고할 수 있습니다.

취약점 유형
이미지의 정확한 위치

기본 OS 이미지 내의 취약점은 Google Cloud CLI Docker 이미지가 최신 안정화 버전의 Debian 또는 Alpine Linux를 사용하도록 하기 위해서만 해결됩니다.