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가지가 있습니다. 다음 안정적인 이미지를 설치하는 것이 좋습니다.
:stable,:VERSION-stable: 표준 gcloud 설치가 포함된 가장 작은 기본(Debian 기반) 이미지입니다.
Alpine 기반 이미지를 사용하려면 다음 이미지를 설치하면 됩니다.
:alpine,:VERSION-alpine: 추가 구성요소가 설치되지 않은 작은(Alpine 기반) 이미지입니다. 이 이미지는 linux/arm을 지원합니다.
추가 패키지 또는 gcloud 구성요소가 미리 설치된 이미지를 사용하려면 다음 옵션 중 하나를 설치하면 됩니다.
:emulators,:VERSION-emulators: 에뮬레이터 구성요소가 사전 설치된 작은(Debian 기반) 이미지입니다.:latest,:VERSION: 추가 구성요소가 사전 설치된 큰(Debian 기반) 이미지입니다.:slim,:VERSION-slim: 구성요소가 사전 설치되지 않은 작은(Debian 기반) 이미지입니다.:debian_component_based,:VERSION-debian_component_based: 추가 구성요소가 사전 설치된 큰(Debian 기반) 이미지입니다. deb 패키지가 사용된:latest와 반대로 이 이미지는 구성요소 관리자를 사용해서 구성요소를 설치합니다. 이 이미지는 linux/arm을 지원합니다.
각 태그에 설치된 구성요소
| 구성요소 | :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 |
프로덕션에서 특정 버전 사용
Google Cloud CLI Docker 이미지 :<tag> 및 :<VERSION-tag> 태그는 기본 이미지 취약점 수정사항을 즉시 통합하기 위해 매일 다시 빌드됩니다.
특정 버전에 연결되지 않은 태그를 사용하면 환경에 다음과 같은 브레이킹 체인지가 발생할 수 있습니다.
- Google Cloud SDK 버전 업데이트로 인해 도구의 동작이 변경될 수 있습니다.
- 설치된 구성요소 목록 업데이트
브레이킹 체인지가 발생할 수 있으므로 프로덕션 환경에서는 다음 중 하나를 사용하는 것이 좋습니다.
- 날짜가 지정된 버전 태그(예:
:496.0.0-stable-20241015) - 특정 이미지 해시(예:
gcr.io/google.com/cloudsdktool/google-cloud-cli@sha256:9c0efc06918d5405b13bfe4bb5ce1d98ea4695cc703446e9e0aa0ee8800622df)
최신 gcloud 버전을 가져오려면 주기적으로 이미지를 업데이트해야 합니다.
최신 Google Cloud CLI 버전 및 이전의 모든 Google Cloud CLI 버전을 확인합니다.
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 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 loginGoogle 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의 볼륨에 사용자 인증 정보가 보존됩니다.확인하려면
--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를 사용하도록 하기 위해서만 해결됩니다.