安装 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 映像选项

共有 6 个 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 软件包安装组件。如需安装特定的 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 3.9 x x x x x x
Bigtable 命令行工具 x x
Bigtable 模拟器 x x x
Cloud Datastore Emulator x x x
Cloud Firestore 模拟器 x x
Cloud Pub/Sub Emulator 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 Commands 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 的卷中。

    如需进行验证，请使用这些凭据列出计算实例，方法是将该容器与 --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 构建自己的映像

如需使用 :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 映像，则可以在运行时安装以下其他组件：

  • gcloud 组件，方法是使用 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 的映像安装其他组件，请创建一个将 cloud-sdk 映像用作基础映像的 Dockerfile。

例如，如需添加 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 映像相关的 bug 或问题，可以创建支持服务工单。

如果您需要包含其他组件、软件包或工具的映像，可以在 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 映像中检测到未解决的漏洞，您可以提交 bug，并附上以下信息：

  • 漏洞类型。
  • 图片中的确切位置。

我们仅解决了基础操作系统映像中的漏洞，以确保 Google Cloud CLI Docker 映像使用的是近期稳定版的 Debian 或 Alpine Linux。

为什么 Artifact Registry 代码库中存在无标记映像？

标记为 :stable、:alpine、:emulators 和 :debian_component_based 的 Google Cloud CLI Docker 映像同时支持 arm64 和 amd64 平台。这些映像是使用多架构构建流程构建的，该流程会将特定于架构的映像合并到单个清单中。该清单还包含平台专用认证映像。多架构构建流程仅会向最终清单映像添加标记，但不会为各个架构专用映像或认证映像添加标记。因此，您可能会在 Artifact Registry 代码库中看到无标记映像。这些图片不适合使用，您可以放心地忽略它们。