# cloud-sdk-docker: a pinned gcloud CLI in a container

> The Google Cloud CLI Docker image packages gcloud and its bundled components on Debian and Alpine bases so a pipeline can run a specific CLI version without installing the SDK on the host. Six image variants differ in what they pre-install, the images are built with a non-root user and version-pinned apt packages, and every tag older than a year is deleted automatically.

**GoogleCloudPlatform/cloud-sdk-docker** — Google Cloud CLI Docker Image - Docker Image containing the gcloud CLI and its bundled components.

- Repository: https://github.com/GoogleCloudPlatform/cloud-sdk-docker
- Website: https://cloud.google.com/sdk/docs/downloads-docker
- Stars: 795 · Forks: 248
- Language: Dockerfile
- License: Apache-2.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/googlecloudplatform-cloud-sdk-docker

## A gcloud you can pin, without installing the SDK

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

That sentence contains the whole argument for the project. The gcloud CLI is a Python tool with a large set of bundled components, it is installed through Google's own apt repository, and it updates itself in the background unless you pin it. In a container image, all of that becomes an image tag, and a build step that says which tag it wants is a build step whose result does not change under you.

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

The images are hosted on Artifact Registry under the repository name gcr.io/google.com/cloudsdktool/google-cloud-cli, and the same images are also available through the us.gcr.io, eu.gcr.io, and asia.gcr.io repositories, which is the practical detail that matters for a machine in a particular region, since a registry close to you pulls faster.

The repository is Apache-2.0 licensed, the primary language is Dockerfile, and the project is not archived with the last push on 2026-10-14. There are no GitHub releases, which is expected, since the artefacts that matter here are the image tags in the registry rather than the source in the repository.

## Six images that differ only in what is already inside

There are six images, and all of them install the gcloud and bq command line tools. Every one of them is built with --no-install-recommends to keep them minimal, and the README adds a warning that follows directly from that: users should not rely on recommended or transient dependencies, such as make, being present, and if your workflow requires additional tools you should install them explicitly.

That single line is the most operationally important statement in the README, and it is the thing that will bite a build that assumes a normal Debian environment.

The stable image, and its version-pinned form :VERSION-stable, gives a gcloud installation with the bq components, built on the latest Debian trixie-slim base image, and it supports both linux/amd and linux/arm platforms. The README recommends the stable image for a minimal environment and, more interestingly, suggests you can use it as the base image for your own deployments, which gives you the flexibility of installing only the components and packages you need in your own image.

The alpine image is similar but built on the latest Alpine 3.23 base image, and it too supports both linux/amd and linux/arm.

The emulators image is similar to stable with the addition of all the emulator components, installed with the component manager rather than with deb packages, and the :latest image is similar to stable with additional components pre-installed, installed with deb packages instead. The :slim image adds packages such as curl, gcc, python3-dev, python3-pip, apt-transport-https, lsb-release, openssh-client, git, and gnupg. The :debian_component_based image is similar to stable with additional components pre-installed, again through the component manager.

So the choice comes down to three questions: which base family, whether you want the emulator components, and whether you want the extra system packages or the extra CLI components. The distinction between installing components with the component manager and installing them as deb packages is the one that is easy to miss, and it exists because the two mechanisms produce different images.

## The Dockerfile: a fixed uid, a pinned repo, and versioned packages

The Dockerfile in the repository root is the stable image, and it is worth reading because it shows the choices the images make on your behalf.

The base is the Debian trixie-slim image, and the Cloud SDK version comes in as a build argument that is then exposed as an environment variable, so the same Dockerfile can be built for any release.

```dockerfile
FROM debian:trixie-slim
ARG CLOUD_SDK_VERSION
ENV CLOUD_SDK_VERSION=$CLOUD_SDK_VERSION
RUN groupadd -r -g 1000 cloudsdk && \
    useradd -r -u 1000 -m -s /bin/bash -g cloudsdk cloudsdk
```

The next block is where the interesting decisions are. The system packages are installed with apt-get install -q --no-install-recommends, which is the mechanism behind the warning about minimal images. The Google apt repository is then added by writing a sources.list entry whose distribution component is derived from lsb_release, and the repository signing key is fetched and dearmoured into /etc/apt/keyrings, so the install is verified rather than trusted.

The final install pins every package to the requested version with the ${CLOUD_SDK_VERSION}-0 suffix, across google-cloud-cli itself, the App Engine python, python extras, java and go components, the datastore, pubsub and bigtable emulators, the firestore emulator, the cbt and local-extract commands, and the gke gcloud auth plugin, followed by kubectl, which is installed without a version pin.

Two things follow from that listing. The image is not a thin wrapper, it carries a specific set of components chosen by the maintainers, and adding a component to your workflow means either finding a variant that has it or installing it in a derived image. The other is the non-root user: a group and a user with uid 1000 and a bash shell are created up front, so the container runs as an unprivileged user rather than as root, which is what you want when a pipeline mounts credentials into it.

## The one year retention window changes how you pin

The README devotes a section to a policy that operators need to know about before they depend on a specific tag.

All Google Cloud CLI Docker image repositories enforce automated retention policies, and the policy is a one year retention window: package versions published within the last 365 days are retained, and package versions older than 1 year are automatically cleaned up.

This is a sharp edge for the main use case of the project. The whole point of the image is pinning a specific version, and the pinned version is a URL that stops resolving once it is a year old. A pipeline that pinned 573.0.0-stable a year and a half ago will now fail at the pull step, and it will fail in a way that looks like a registry outage rather than a policy.

The floating tags are the escape hatch. The :stable tag always points to the latest release, and the version-pinned form exists for the cases where you need a specific one. In practice that means a pipeline that must be reproducible has to be rebuilt periodically, or it has to vendor the image into a registry it controls, which is the standard answer to a retention policy and the reason the regional repository names are worth knowing about.

For a team that wants long lived reproducibility, mirroring the image into your own Artifact Registry is the durable move. For a team that just wants a current CLI in CI, the floating stable tag is simpler and has no expiry at all.

## Pulling and verifying in two commands

The install procedure in the README is two steps, and the second one is there for a reason.

First you pull the image, with the tag that names the version you want.

```bash
    docker pull gcr.io/google.com/cloudsdktool/google-cloud-cli:573.0.0-stable
```

Then you verify the installation by running the container and asking the CLI what it is.

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

If you have used the floating :stable tag, which always points to the latest release, the verification command uses that tag instead.

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

The --rm flag matters more than it looks in a CI context, because it keeps the container from lingering in the host's list of containers, and the pattern of the command is the pattern you will use everywhere else: image, then the gcloud subcommand you actually want.

What the README does not cover in this section is authentication, and it says so by pointing elsewhere. For detailed instructions on authenticating, installing additional components, troubleshooting, and migrating to the :stable image, there is a User Guide and a Migration Guide in the docs directory of the repository. The migration guide in particular suggests that there was an earlier default tag, and that the move to :stable is something a pipeline with pinned expectations should read about rather than infer.

For tracking when new versions land, the README points at the Google Cloud SDK announce group, which is where the release schedule is published.

## Six directories, one generation script

The repository is a set of build directories with a generator in the middle, and that structure explains how six images stay consistent.

There is a stable directory, an alpine directory, an emulators directory, a debian_slim directory, a debian_component_based directory, and an all_components directory, alongside the root Dockerfile, a cloudbuild.yaml for the build pipeline, and a generate_cloudbuild.py script. There are also two test scripts, test-latest.sh and test-all-emulators-latest.sh, which build the images and check them.

The naming inside those directories matches the tag names exactly, which is the practical benefit: a directory named debian_component_based produces the :debian_component_based tag, and the same mapping holds for the others. The difference between the variants is the mechanism used to add the extra components, with the component manager in the emulators and debian_component_based directories, and deb packages in the all_components style of build, and the root Dockerfile above shows the apt repository route in full.

The docs directory holds the user guide and the migration guide that the README points to, and the rest of the top level is the usual project furniture: the licence, the contributing guide, the github directory, and the ignore files.

The build itself runs through Cloud Build, and the generator script is what keeps the six definitions in step with each other, so a change to the base image or the package list is made once. That is a sensible arrangement for a project whose output is six images that must not drift apart, and it is also the reason the release model of this repository looks unusual: there is nothing to release, because the artefact is the image in the registry, and the registry, not the repository, is where the version history lives.

## Conclusion

The cloud-sdk-docker images fit a CI pipeline or a build script that needs a gcloud version it can pin, on a machine where installing the Cloud SDK is inconvenient or would drift between runs, and where the version it needs is recent enough to still be published. It does not fit a deployment that needs an old CLI version, because anything published more than 365 days ago is removed, and it does not fit a build that assumes a tool is present in the image, because the images are built with no-install-recommends and the README says not to rely on recommended or transient dependencies being there. Verify first that the exact version tag you want still exists, that the platform you need is covered, since the Debian based tags list linux/amd and linux/arm, and that you install any extra tooling explicitly rather than assuming it is in the base image.

## FAQ

### What does the Google Cloud CLI Docker image give me?

It is the gcloud CLI and its bundled components installed on a Debian or Alpine base, so you can run Google Cloud CLI commands in an isolated, correctly configured container without installing the SDK on the host. All six variants install the gcloud and bq tools.

### Which Docker tags are available for the gcloud CLI image?

Six variants, each with a version pinned form: stable, alpine, emulators, latest, slim, and debian_component_based. The stable, alpine, emulators, latest, and slim tags support both linux/amd and linux/arm platforms, and all are built on the latest Debian trixie-slim or, for alpine, Alpine 3.23.

### Why are packages missing from the gcloud CLI Docker images?

The images are built with --no-install-recommends to keep them minimal, so the README says not to rely on recommended or transient dependencies such as make being present. If your workflow needs extra tools, install them explicitly, or use the slim image, which adds packages such as curl, gcc, git, and python3-pip.

### How long are the gcloud CLI Docker image versions kept?

All the image repositories enforce a one year retention window. Package versions published within the last 365 days are retained, and older versions are automatically cleaned up, so a long lived pin eventually stops resolving.

### How do I pull and verify the gcloud CLI Docker image?

Pull the image with docker pull and the repository name gcr.io/google.com/cloudsdktool/google-cloud-cli plus your tag, then verify with docker run --rm and the gcloud version subcommand. The images are also available from the us.gcr.io, eu.gcr.io, and asia.gcr.io repositories.

## Sources

- [GoogleCloudPlatform/cloud-sdk-docker on GitHub](https://github.com/GoogleCloudPlatform/cloud-sdk-docker)
- [Issues](https://github.com/GoogleCloudPlatform/cloud-sdk-docker/issues)
- [License: Apache-2.0](https://github.com/GoogleCloudPlatform/cloud-sdk-docker/blob/master/LICENSE)
- [Project website](https://cloud.google.com/sdk/docs/downloads-docker)
- [README](https://github.com/GoogleCloudPlatform/cloud-sdk-docker/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/googlecloudplatform-cloud-sdk-docker