安裝 Google Cloud CLI Docker 映像檔

您可以使用 Google Cloud CLI Docker 映像檔，從 Artifact Registry 以 Docker 映像檔形式提取特定版本的 gcloud CLI，並在已正確設定的獨立容器中快速執行 Google Cloud CLI 指令。

Google Cloud CLI Docker 映像檔是在 Debian 或 Alpine 映像檔上安裝的 gcloud CLI。使用 Google Cloud CLI Docker 映像檔，即可使用 gcloud 及其隨附元件，不必在本機手動安裝 gcloud。

Docker 映像檔選項

Google Cloud CLI Docker 映像共有六種，全部都會安裝 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.20 為基礎映像檔。這個映像檔支援 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 套件安裝元件。這個映像檔支援 linux/amd 和 linux/arm 平台。如要安裝特定 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。

查看最新版 Google Cloud CLI 和所有舊版 Google Cloud CLI。

每個代碼中安裝的元件

元件	:stable	:alpine	:emulators	:latest	:slim	:debian_component_based
App Engine Go 擴充功能				x		x
Appctl						x
BigQuery 指令列工具	x	x	x	x	x	x
隨附的 Python	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 Emulator			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 Beta 版指令			x	x	x	x
gcloud app Java 擴充功能						x
gcloud app Python 擴充功能						x
gcloud app Python 擴充功能 (額外程式庫)				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 存放區取得這些圖片。

1. 如要使用穩定版 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
   

2. 執行下列指令，驗證安裝作業：

   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
  

  如要進一步瞭解如何設定環境變數，請參閱下列說明：

  • 使用環境變數設定屬性
  • gcloud config

安裝其他元件

您可以在 Google Cloud CLI Docker 映像檔中安裝其他元件。安裝額外元件的方法會因基礎映像檔類型而異。

以 Debian 為基礎的映像檔

根據預設，穩定版映像檔 (:stable 和 :VERSION-stable) 除了 bq 和 gsutil 之外，不會安裝任何元件。如要為穩定版映像檔安裝其他元件，請採取下列任一做法：

• 使用 :stable 映像檔 Dockerfile 建構自己的映像檔： 安裝無法透過 apt-get 直接取得的套件，例如 Docker 引擎。
• 在執行階段安裝其他套件或元件： 自訂映像檔，不必代管。

使用 :stable 映像檔 Dockerfile 建構自己的映像檔

如要使用 :stable 中的其他元件建構自己的映像檔，可以複製 cloud-sdk-docker GitHub 目錄，並使用 docker build 指令，從 Dockerfile 搭配 INSTALL_COMPONENTS 引數建構 :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 環境變數。
• 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 為基礎的映像檔安裝其他元件，請建立 Dockerfile，並使用 cloud-sdk 映像檔做為基本映像檔。

舉例來說，如要新增 kubectl 和 app-engine-java 元件：

1. 建立 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

1. 執行下列指令來建構映像檔：

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 映像檔來配合工作流程的使用案例，以及補救選項：

使用案例	修復選項
:stable 映像檔不包含 docker 或 docker-buildx 等第三方套件	如需這些第三方套件，請自行建構映像檔，或在 :stable Docker 映像檔中手動安裝這些套件。

如果掃描器在 Docker 映像檔中發現安全漏洞，該怎麼辦？

Google Cloud CLI Docker 映像檔託管於 Artifact Registry。系統每天都會掃描映像檔，並在每次發布新版 gcloud 前，先減輕常見的安全漏洞與弱點 (CVE) 影響。不過，如果掃描器在 Google Cloud CLI Docker 映像檔中偵測到未解決的安全性漏洞，您可以回報錯誤，並提供下列資訊：

• 安全漏洞類型。
• 圖片中的確切位置。

我們只會處理基本 OS 映像檔中的安全漏洞，確保 Google Cloud CLI Docker 映像檔使用最新且穩定的 Debian 或 Alpine Linux 版本。

為什麼 Artifact Registry 存放區中有沒有標記的映像檔？

標記為 :stable、:alpine、:emulators 和 :debian_component_based 的 Google Cloud CLI Docker 映像檔同時支援 arm64 和 amd64 平台。這些映像檔是透過多架構建構程序建構而成，可將特定架構的映像檔合併為單一資訊清單。資訊清單也包含平台專用的認證映像檔。多架構建構程序只會將標記新增至最終資訊清單映像檔，但不會標記個別架構專屬的映像檔或認證映像檔。因此，您可能會在 Artifact Registry 存放區中看到沒有標記的映像檔。這些圖片並非供您使用，可以放心忽略。

哪裡可以取得從 gcloud Docker 映像檔移除的第三方套件相關資訊？

如要瞭解所有已移除的第三方套件，請參閱 GitHub 上的公告。