The Google Cloud CLI Docker image lets you pull a specific version ofgcloud CLI as a Docker image fromArtifact Registry and quickly executeGoogle Cloud CLI commands in an isolated, correctly configured container.

The Google Cloud CLI Docker image is the gcloud CLI installed ontop of a Debian or Alpine image. TheGoogle Cloud CLI Docker Images enable the usage of gcloudas well as its bundled components without having to manually installgcloud in your local machine.

Docker image options

There are six Google Cloud CLI Docker images, and all will install thegcloud,gsutil andbq command-line tools. We recommend that you installthe:stable image for a minimal environment. You can alsouse the stable image as the base image for your own deployments which gives youthe flexibility of installing only the components and packages that you need inyour image:

• :stable,:VERSION-stable: Provides a gcloud installationwithgsutil andbq components. The image is built upon the latestGoogle-ProvidedDebian 12 base image. This image supports bothlinux/amd andlinux/armplatforms. To install specific gcloud versions, usethe:VERSION-stable tag.

If you want to use an Alpine-based image, you can install the followingimage:

• :alpine,:VERSION-alpine: Similar to stable but built upon the latestAlpine 3.20base image. This image supports bothlinux/amd andlinux/arm platforms. Toinstall specific gcloud versions, use the:VERSION-alpine tag.

If you want images with additionalcomponents or packages pre-installed,you can install one of the following options:

• :emulators,:VERSION-emulators: Similar to stable, with theaddition of all the emulator components. The image is build upon the latestGoogle-ProvidedDebian 12 base image and uses component manager to install the components. Thisimage supports bothlinux/amd andlinux/arm platforms. To install specificgcloud versions, use the:VERSION-emulatorstag.

• :latest,:VERSION: Similar to stable, with additional components(List of components installed in the image are listedbelow) pre-installed. The image is buildupon the latestGoogle-ProvidedDebian 12 base image and uses deb packages to install the components.This image supports bothlinux/amd andlinux/arm platforms. To installspecific gcloud versions, use the:VERSIONtag.

• :slim,:VERSION-slim: Similar to stable but includes the additionalthird party packages likecurl,python3-crcmod,apt-transport-https,lsb-release,openssh-client,git,make, andgnupg. This image isbuilt upon the latestGoogle-ProvidedDebian 12 base image. This image supports bothlinux/amd andlinux/armplatforms. To install specific gcloud versions, usethe:VERSION-slim tag.

• :debian_component_based,:VERSION-debian_component_based: Similar tostable, with additional components(List of components installed in the image are listedbelow) pre-installed. The image is buildupon the latestGoogle-ProvidedDebian 12 base image and uses component manager to install the components. Thisimage supports bothlinux/amd andlinux/arm platforms. To install specificgcloud versions, use the:VERSION-debian_component_based tag.

Use a specific version in production

If you use a tag that is not tied to a specific gcloud version,your environment might experience the following possible breaking changes:

• Google Cloud SDK version updates, which may change the behavior of the tool.
• Updates to the list of installed components.

To avoid possible breaking changes, it is recommended that your productionenvironment use either of the following:

• A versioned tag, such as:496.0.0-stable
• A specific image hash such as:gcr.io/google.com/cloudsdktool/google-cloud-cli@sha256:9c0efc06918d5405b13bfe4bb5ce1d98ea4695cc703446e9e0aa0ee8800622df
• Host the image in your own repository

You should also update the images periodically to get the latestgcloud version.

Checkthe latest Google Cloud CLI version andall previous Google Cloud CLI versions.

Components installed in each tag

Installing a Docker image

The Docker image is hosted onArtifact Registrywith the following repository name:gcr.io/google.com/cloudsdktool/google-cloud-cli. The images are also availableusing theus.gcr.io,eu.gcr.io, andasia.gcr.io repositories.

1. To use the image of the stable Google Cloud CLI release,gcr.io/google.com/cloudsdktool/google-cloud-cli:stable,pull it fromArtifact Registryby running the following command:

   docker pull gcr.io/google.com/cloudsdktool/google-cloud-cli:489.0.0-stable

   You can also use theimage hashto pull a specific Docker image from the repository. To pull the same imagefrom the previous example (:489.0.0-stable) using the image hash, run thefollowing command:

   docker pull gcr.io/google.com/cloudsdktool/google-cloud-cli@sha256:589a0db8919614ef919dfd6ed89127211b4b6bf5ee6a2e2ce92abf33cbfe49d8

2. Verify the installation by running:

   docker run --rm gcr.io/google.com/cloudsdktool/google-cloud-cli:489.0.0-stable gcloud version

   If you have used the floating:stable tag (which always point to the latestrelease), verify the installation by running the following command:

   docker run --rm gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud version

Authenticating with the Google Cloud CLI Docker image

Authenticate with the Google Cloud CLI Docker image by running one of thefollowing commands:

• Authenticate gcloud with your user credentials byrunninggcloud auth login:

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

• If you need to authenticate applications that use the Google Cloud APIs,pass the--update-adc option:

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

• To set a default project that is selected each time you open the container,run the following command:

  docker run -ti --name gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli:stable /bin/bash -c 'gcloud auth login && gcloud config set projectyour-project'

  After you've authenticated successfully, credentials are preservedin the volume of thegcloud-config container.

  Note:gcloud-config container now has a volume containing yourGoogle Cloud credentials. Don't usegcloud-config volume in othercontainers.

  To verify, list the compute instance using the credentials by running thecontainer with--volumes-from:

  docker run --rm --volumes-from gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud compute instances list --projectyour-project

• If you want to authenticate using a service account, use theauth/credential_file_override property to set a path to amounted service account. Then update the config to read the mounted serviceaccount using theCLOUDSDK_CONFIG environment variable.

  In the following example, themycloud configuration has theauth/credential_file_override already set. The configuration points to acertificate file that is present within the container as a separatevolume mount.

  $dockerrun-ti-eCLOUDSDK_CONFIG=/config/mygcloud\-v`pwd`/mygcloud:/config/mygcloud\-v`pwd`:/certsgcr.io/google.com/cloudsdktool/google-cloud-cli:stable/bin/bashbash-4.4#gcloudconfiglist[auth]credential_file_override=/certs/svc_account.jsonbash-4.4#head-10/certs/svc_account.json{"type":"service_account","project_id":"project_id1",....bash-4.4#gcloudprojectslistPROJECT_IDNAMEPROJECT_NUMBERproject_id1GCPAppID1071284184432

  For more information about setting environment variables, see the following:

  • Setting properties using environment variables
  • gcloud config

Installing additional components

You can install additional components in the Google Cloud CLI Docker image. Theapproach to install additional components varies depending on the underlyingbase image type.

Debian-based images

By default, the stable images (:stable and:VERSION-stable) have nocomponents installed other thanbq andgsutil. To install additionalcomponents for the stable image, do one of the following:

• Building your own image using the:stable image Dockerfile:Install packages that are not directly availablethroughapt-get, i.e.- docker engine.
• Installing additional packages or components at runtime:Customize your image without hosting it.

Building your own image using the:stable image Dockerfile

To build your own image with additional component from:stable, you can clonethecloud-sdk-dockerGitHub directory and use thedocker build command to buildthe:stable Docker image from the Dockerfile with theINSTALL_COMPONENTSargument. For example, to adddatastore-emulator components:

# clone the GitHub docker directory$gitclonehttps://github.com/GoogleCloudPlatform/cloud-sdk-docker.git$dockerbuild--build-argCLOUD_SDK_VERSION=<release_version>\--build-argINSTALL_COMPONENTS="google-cloud-cli-datastore-emulator=<release_version>-0"\-tmy-cloud-sdk-docker:stable.

Installing additional packages or components at runtime

If you have pulled thestable Docker image, you can install the followingadditional components during runtime:

• gcloud components by using theCOMPONENTS environmentvariable.
• apt-packages by using theAPT_PACKAGES environment variable.

For example, if you want to install thecbt andkpt components at runtime,you can run the following command:

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

To install apt-packagescurl andgcc while running the Docker image,execute the following command:

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

Alpine-based images

To install additional components for Alpine-based images, create a Dockerfilethat uses thecloud-sdk image as the base image.

For example, to addkubectl andapp-engine-java components:

1. Create the Dockerfile as:

FROMgcr.io/google.com/cloudsdktool/google-cloud-cli:alpineRUNapk--updateaddgcompatopenjdk8-jreRUNgcloudcomponentsinstallapp-engine-javakubectl

1. Build the image by executing the following command:

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

For Alpine based images, you must install dependencies of additionalcomponents manually.

Migrating to the:stable image

If you are using the:latest,:slim,:emulators,:alpine and:debian_component_based Docker images, we recommend that you migrate tothe Debian-based:stable image for a smaller image size and improved securityfixes. For steps to migrate to the:stable image, seeMigrating to the:stable image.

Getting support for images

The images hosted on theArtifact Registryprovide fully functional installs of Google Cloud CLI. If you find bugs orissues related to the Docker images you can create asupport ticket.

When you need an image with additional components, packages, or tools, you cancreate your own image layer on top of theGoogle Cloud CLI Docker image.

Troubleshooting

What should you do if you see afailed to fetch <image-tag> errorwhile pulling the Docker image?

If you get afailed to fetch <image-tag> error while trying to pull aGoogle Cloud CLI Docker image, you are most likely trying to fetch an imagetag that has been deprecated and removed. Check theDocker Image Options for available Docker image Optionsand migrate to one of the supported tags.

What are the use-cases where you cannot directly extend the:stable Dockerimage to support your current workflow?

The following table lists the use-cases when you cannot directly extend the:stable docker image to fit your workflow and lists the options to remediate:

What should you do if your scanner found vulnerabilities in the docker images?

Google Cloud CLI Docker images are hosted inArtifact Registry.Images are scanned daily and common vulnerabilities and exposures (CVEs) aremitigated before each new gcloud release. However, if your scannerhas detected vulnerabilities in theGoogle Cloud CLI Docker images that are not resolved, you canfile a bug thatincludes the following information:

• The type of vulnerability.
• The exact location in the image.

Vulnerabilities within base OS images are only addressed to ensure that theGoogle Cloud CLI Docker images are using recent, stable releases of Debian orAlpine Linux.

Why are there tagless images in theArtifact Registry repository?

Google Cloud CLI Docker images with tags:stable,:alpine,:emulators,and:debian_component_based support both arm64 and amd64 platforms. The imagesare build with a multi-arch build process, which combinesarchitecture-specific imagesinto a singlemanifest.The manifest also includesplatform specificattestationimages. The multi-arch build process only adds tag to the final manifest image,but doesn't tag the individual architecture-specific images or attestationimages. As a result, you might see tagless images in theArtifact Registryrepository. These images are not intended for use and you can safely ignorethem.

Where can I get the information about removed 3P packages from gcloud Docker images?

Information about all the removed 3P packages are available through theannouncements on GitHub.