DOCSEARCHbyAlgolia
Submit Docs

Google Cloud CLI Docker Images

repository·master·Indexed 21 days ago

https://github.com/googlecloudplatform/cloud-sdk-docker

Official Docker images for the Google Cloud CLI (gcloud), providing isolated containers to run gcloud and bq commands. Includes various image tags such as :stable, :alpine, :emulators, :slim, and :latest, with guides on authentication via user credentials or service accounts, and instructions for extending the :stable image using environment variables or custom Dockerfiles.

Tokens
4.1K
Snippets
8
Records
10
Agent score
74%

What's inside cloud-sdk-docker

  1. Pull and use the Google Cloud CLI Docker image

    master

    The Google Cloud CLI Docker image allows you to execute gcloud and bq commands in an isolated container without local installation. The images are hosted on Artifact Registry under the repository gcr.io/google.com/cloudsdktool/google-cloud-cli (or regional mirrors like us.gcr.io, eu.gcr.io, and asia.gcr.io).

    To pull a specific version of the stable release, use docker pull. To verify the installation, run gcloud version within the container using docker run.

    # Pull a specific version
docker pull gcr.io/google.com/cloudsdktool/google-cloud-cli:573.0.0-stable

# Verify the installation
docker run --rm gcr.io/google.com/cloudsdktool/google-cloud-cli:573.0.0-stable gcloud version

# Or verify using the floating stable tag
docker run --rm gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud version

  2. Extend the :stable image at runtime using environment variables

    master

    You can customize the :stable image at runtime by passing APT_PACKAGES and COMPONENTS environment variables to docker run. This allows you to replicate the behavior of other specific images without building a new one.

    Customize to the :latest image

    Use this to include common utilities and a wide range of gcloud components.

    Customize to the :emulators image

    Use this to include the necessary packages and gcloud emulators (Datastore, Pub/Sub, Bigtable, Firestore, Spanner).

    Customize to the :slim image

    Use this for a minimal environment including core build tools and Python dependencies.

    # Customize to :latest
docker run -e APT_PACKAGES='curl python3-crcmod lsb-release openssh-client git make gnupg' \
-e COMPONENTS='google-cloud-cli-datastore-emulator google-cloud-cli-pubsub-emulator google-cloud-cli-bigtable-emulator google-cloud-cli-firestore-emulator google-cloud-cli-spanner-emulator google-cloud-cli-cbt google-cloud-cli-kpt google-cloud-cli-local-extract google-cloud-cli-gke-gcloud-auth-plugin kubectl' \
gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud version

# Customize to :emulators
docker run -e APT_PACKAGES='curl python3-crcmod lsb-release gnupg bash' \
-e COMPONENTS='google-cloud-cli-datastore-emulator google-cloud-cli-pubsub-emulator google-cloud-cli-bigtable-emulator google-cloud-cli-firestore-emulator google-cloud-cli-spanner-emulator' \
gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud version

# Customize to :slim
docker run -e APT_PACKAGES='curl gcc python3-crcmod python3-pip lsb-release openssh-client git gnupg' \
gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud version

  3. Build a custom :emulators image from :stable

    master

    To create a custom image containing only the gcloud emulators, use the following Dockerfile pattern. This installs the necessary system packages and then uses the current SDK version to install the specific emulator components via apt.

    FROM gcr.io/google.com/cloudsdktool/google-cloud-cli:stable

RUN apt-get update -qqy && apt-get -qqy upgrade && apt-get install -qqy --no-install-recommends \
      curl \
      python3-crcmod \
      lsb-release \
      gnupg \
      bash && \
   export CLOUD_SDK_REPO="cloud-sdk-$(lsb_release -c -s)" && \
   export CLOUD_SDK_VERSION=$(gcloud version | grep "Google Cloud SDK" | grep -oE '[^ ]+$') && \
   echo "deb https://packages.cloud.google.com/apt $CLOUD_SDK_REPO main" > /etc/apt/sources.list.d/google-cloud-sdk.list && \
   curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | apt-key add - && \
   apt-get update && \
   apt-get install -y --no-install-recommends google-cloud-cli-datastore-emulator=${CLOUD_SDK_VERSION}-0 \
      google-cloud-cli-pubsub-emulator=${CLOUD_SDK_VERSION}-0 \
      google-cloud-cli-bigtable-emulator=${CLOUD_SDK_VERSION}-0 \
      google-cloud-cli-firestore-emulator=${CLOUD_SDK_VERSION}-0 \
      google-cloud-cli-spanner-emulator=${CLOUD_SDK_VERSION}-0

    To build:

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

  4. Authenticate using a service account

    master

    To use a service account, you must mount the service account JSON key as a volume and configure gcloud to use it via the auth/credential_file_override property. You should also set the CLOUDSDK_CONFIG environment variable to point to the directory containing your custom configuration.

    Example Workflow:

    1. Mount the directory containing your custom config (e.g., /config/mygcloud) and the directory containing your service account key (e.g., /certs).
    2. Ensure the auth/credential_file_override in your config points to the path inside the container (e.g., /certs/svc_account.json).
    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
    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

  5. Build a custom :latest image from :stable

    master

    If you need a permanent image that includes the full suite of components and utilities (similar to the old :latest image), or if you need to include the Docker engine itself, build a custom Dockerfile using :stable as your base. This method uses a multi-stage build to copy the Docker binary from a static source.

    FROM docker:27.1.1 as static-docker-source

FROM gcr.io/google.com/cloudsdktool/google-cloud-cli:stable
COPY --from=static-docker-source /usr/local/bin/docker /usr/local/bin/docker
COPY --from=static-docker-source /usr/local/libexec/docker/cli-plugins/docker-buildx /usr/local/libexec/docker/cli-plugins/docker-buildx

RUN apt-get update -qqy && apt-get -qqy upgrade && apt-get install -qqy --no-install-recommends \
      curl \
      python3-crcmod \
      lsb-release \
      openssh-client \
      git \
      make \
      gnupg && \
   export CLOUD_SDK_REPO="cloud-sdk-$(lsb_release -c -s)" && \
   export CLOUD_SDK_VERSION=$(gcloud version | grep "Google Cloud SDK" | grep -oE '[^ ]+$') && \
   echo "deb https://packages.cloud.google.com/apt $CLOUD_SDK_REPO main" > /etc/apt/sources.list.d/google-cloud-sdk.list && \
   curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | apt-key add - && \
   apt-get update && \
   apt-get install -y --no-install-recommends google-cloud-cli-datastore-emulator=${CLOUD_SDK_VERSION}-0 \
      google-cloud-cli-pubsub-emulator=${CLOUD_SDK_VERSION}-0 \
      google-cloud-cli-bigtable-emulator=${CLOUD_SDK_VERSION}-0 \
      google-cloud-cli-firestore-emulator=${CLOUD_SDK_VERSION}-0 \
      google-cloud-cli-spanner-emulator=${CLOUD_SDK_VERSION}-0 \
      google-cloud-cli-cbt=${CLOUD_SDK_VERSION}-0 \
      google-cloud-cli-kpt=${CLOUD_SDK_VERSION}-0 \
      google-cloud-cli-local-extract=${CLOUD_SDK_VERSION}-0 \
      google-cloud-cli-gke-gcloud-auth-plugin=${CLOUD_SDK_VERSION}-0 \
      kubectl

    To build:

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

  6. Build a custom :slim image from :stable

    master

    To create a custom minimal image containing only essential build tools and Python development headers, use the following Dockerfile pattern.

    FROM docker:27.1.1 as static-docker-source

FROM gcr.io/google.com/cloudsdktool/google-cloud-cli:stable
COPY --from=static-docker-source /usr/local/bin/docker /usr/local/bin/docker
COPY --from=static-docker-source /usr/local/libexec/docker/cli-plugins/docker-buildx /usr/local/libexec/docker/cli-plugins/docker-buildx

RUN apt-get update -qqy && apt-get -qqy upgrade && apt-get install -qqy --no-install-recommends \
      curl \
      gcc \
      python3-dev \
      python3-crcmod \
      python3-pip \
      lsb-release \
      openssh-client \
      git \
      gnupg

    To build:

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

  7. Authenticate with the Google Cloud CLI Docker image

    master

    You can authenticate the gcloud CLI within the Docker container using user credentials or Application Default Credentials (ADC). To persist these credentials across container runs, name the container (e.g., --name gcloud-config) so that its volume can be reused.

    Authenticate with user credentials

    Run gcloud auth login inside the container:

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

    Authenticate for applications (ADC)

    To authenticate applications that use Google Cloud APIs, use the --update-adc flag:

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

    Set a default project during authentication

    You can combine authentication and project configuration in a single 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>'

    Reuse authenticated credentials

    Once authenticated, you can run new containers using the credentials from the gcloud-config container via the --volumes-from flag:

    docker run --rm --volumes-from gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud compute instances list --project <your-project>
    docker run -ti --name gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud auth login

  8. Migrate to the :stable Docker image

    master
    If you are currently using the :latest, :alpine, :emulators, :slim, or :debian_component_based images, it is recommended to migrate to the Debian-based :stable image. The :stable image offers a smaller size and more timely security updates. You can extend the :stable image using environment variables at runtime or by building a custom Dockerfile to match the functionality of your previous image.

  9. Extend the :stable image using Cloud Build configuration

    master

    You can use a Google Cloud Build configuration file to customize the :stable image. This is useful for automated CI/CD pipelines where you need to install specific APT_PACKAGES and COMPONENTS during the build process.

    steps:
  - id: 'extend-stable'
    name: gcr.io/google.com/cloudsdktool/google-cloud-cli:500.0.0-stable
    args:
      - gcloud
      - version
    env:
      - 'APT_PACKAGES=python3-google-auth python3-requests'
      - 'COMPONENTS=google-cloud-cli-pubsub-emulator'

  10. Choose the appropriate Google Cloud CLI Docker image tag

    master

    All images include gcloud and bq tools and are built with --no-install-recommends to remain minimal. Users should explicitly install any additional dependencies (like make) if needed. Most images support both linux/amd and linux/arm platforms.

    Base Images

    • :stable or :VERSION-stable: Built on Debian (trixie-slim). Recommended for minimal environments or as a base image for custom deployments.
    • :alpine or :VERSION-alpine: Built on Alpine 3.23. Use this if you prefer an Alpine-based environment.

    Specialized Images

    • :emulators or :VERSION-emulators: Includes all emulator components (installed via component manager) on a Debian base.
    • :latest or :VERSION: Includes additional components pre-installed via deb packages on a Debian base.
    • :slim or :VERSION-slim: Includes common development packages: curl, gcc, python3-dev, python3-pip, apt-transport-https, lsb-release, openssh-client, git, and gnupg on a Debian base.
    • :debian_component_based or :VERSION-debian_component_based: Includes additional components pre-installed via component manager on a Debian base.