Installing the Google Cloud CLI Docker image

The Google Cloud CLI Docker image lets you pull a specific version of gcloud CLI as a Docker image from Artifact Registry and quickly execute Google Cloud CLI commands in an isolated, correctly configured container.

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

Docker image options

There are six Google Cloud CLI Docker images. We recommend that you install the following stable image:

  • :stable, :VERSION-stable: Default, Smallest (Debian-based) image with a standard gcloud installation.

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

  • :alpine, :VERSION-alpine: Smaller (Alpine-based) image with no additional components installed. This image supports linux/arm.

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

  • :emulators, :VERSION-emulators: Smaller (Debian-based) image with emulator components pre-installed.
  • :latest, :VERSION: Large (Debian-based) image with additional components pre-installed.
  • :slim, :VERSION-slim: Smaller (Debian-based) image with no components pre-installed.
  • :debian_component_based, :VERSION-debian_component_based: Large (Debian-based) image with additional components pre-installed. As opposed to :latest which used deb packages, this image uses the component manager to install components. This image supports linux/arm.

Components installed in each tag

Component :stable :alpine :emulators :latest :slim :debian_component_based
App Engine Go Extensions x x
Appctl x
BigQuery Command Line Tool x x x x x x
Bundled Python 3.9 x x x x x x
Bigtable Command Line Tool x x
Bigtable Emulator x x x
Cloud Datastore Emulator x x x
Cloud Firestore Emulator x x
Cloud Pub/Sub Emulator x x x
Spanner Emulator x x
Cloud Storage Command Line Tool x x x x x x
Google Cloud CLI Core Libraries x x x x x x
Google Cloud CRC32C Hash Tool x x x x x x
Kustomize x
Minikube x
Nomos CLI x
On-Demand Scanning API extraction helper x x
Skaffold x
anthos-auth x
gcloud Alpha Commands x x x x
gcloud Beta Commands x x x x
gcloud app Java Extensions x
gcloud app Python Extensions x
gcloud app Python Extensions (Extra Libraries) x x
gke-gcloud-auth-plugin x x
kpt x x
kubectl x x

Use a specific version in production

The Google Cloud CLI Docker image :<tag> and :<VERSION-tag> tags are rebuilt daily to incorporate any base image vulnerability fixes immediately. If you use a tag that is not tied to a specific 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 production environment use either of the following:

  • A dated versioned tag, such as :496.0.0-stable-20241015
  • A specific image hash such as: gcr.io/google.com/cloudsdktool/google-cloud-cli@sha256:9c0efc06918d5405b13bfe4bb5ce1d98ea4695cc703446e9e0aa0ee8800622df

You should also update the images periodically to get the latest gcloud version.

Check the latest Google Cloud CLI version and all previous Google Cloud CLI versions.

Installing a Docker image

The Docker image is hosted on Artifact Registry with the following repository name: gcr.io/google.com/cloudsdktool/google-cloud-cli. The images are also available using the us.gcr.io, eu.gcr.io, and asia.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 from Artifact Registry by running the following command:

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

  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 latest release), 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 the following commands:

  • Authenticate gcloud with your user credentials by running gcloud 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 project your-project'

    After you've authenticated successfully, credentials are preserved in the volume of the gcloud-config container.

    To verify, list the compute instance using the credentials by running the container with --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

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

    In the following example, the mycloud configuration has the auth/credential_file_override already set. The configuration points to a certificate file that is present within the container as a separate volume mount.

    $ 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

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

Installing additional components

You can install additional components in the Google Cloud CLI Docker image. The approach to install additional components varies depending on the underlying base image type.

Debian-based images

By default, the stable images (:stable and :VERSION-stable) have no components installed other than bq and gsutil. To install additional components for the stable image, do one of the following:

Building your own image using the :stable image Dockerfile

To build your own image with additional component from :stable, you can clone the cloud-sdk-docker GitHub directory and use the docker build command to build the :stable Docker image from the Dockerfile with the INSTALL_COMPONENTS argument. For example, to add datastore-emulator components:

# 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 .

Installing additional packages or components at runtime

If you have pulled the stable Docker image, you can install the following additional components during runtime:

  • gcloud components by using the COMPONENTS environment variable.
  • apt-packages by using the APT_PACKAGES environment variable.

For example, if you want to install the cbt and kpt 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-packages curl and gcc 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 Dockerfile that uses the cloud-sdk image as the base image.

For example, to add kubectl and app-engine-java components:

  1. Create the Dockerfile as:
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. 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 additional components 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 to the Debian-based :stable image for a smaller image size and improved security fixes. For steps to migrate to the :stable image, see Migrating to the :stable image.

Getting support for images

The images hosted on the Artifact Registry provide fully functional installs of Google Cloud CLI. If you find bugs or issues related to the Docker images you can create a support ticket.

When you need an image with additional components, packages, or tools, you can create your own image layer on top of the Google Cloud CLI Docker image.

Troubleshooting

What should you do if you see a failed to fetch <image-tag> error while pulling the Docker image?

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

What are the use-cases where you cannot directly extend the :stable Docker image 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:

Use-cases Remediation Options
app-engine components (used in :latest or :debian_component_based Docker image) are not compatible with Debian 12. Build your own image from a compatible Debian (Debian 11) image to install app-engine components.
Third party packages like docker or docker-buildx are not included in the :stable image If you need these third-party packages, build your own image or install these packages in the :stable Docker image manually.

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

Google Cloud CLI Docker images are hosted in Artifact Registry. Images are scanned daily and common vulnerabilities and exposures (CVEs) are mitigated before each new gcloud release. However, if your scanner has detected vulnerabilities in the Google Cloud CLI Docker images that are not resolved, you can file a bug that includes the following information:

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

Vulnerabilities within base OS images are only addressed to ensure that the Google Cloud CLI Docker images are using recent, stable releases of Debian or Alpine Linux.