安装 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 映像共有六种，它们都会安装 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、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 模拟器 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 的卷中。

    如需进行验证，请使用凭据列出计算实例，方法是将该容器与 --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 命令通过带有 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 软件包。

例如，如果您想在运行时安装 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 软件包 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 代码库中看到无标记的映像。这些映像不适合使用，您可以放心地忽略它们。

在哪里可以获取有关从 gcloud Docker 映像中移除的第三方软件包的信息？

您可以通过 GitHub 上的公告获取有关所有已移除的第三方软件包的信息。