Home Google CloudGoogle Cloud Artifact Registry: Store Docker Images

Google Cloud Artifact Registry: Store Docker Images

by Knowledge Base Linux
Google Cloud Artifact Registry vault storing Docker images with version tags and a secure delivery pipeline

Pulling container images from public registries works for getting started, but production teams need private storage, access control, vulnerability scanning, and images that live close to where they run. Google Cloud Artifact Registry is Google Cloud’s managed registry for container images and other artifacts, with IAM access control, regional storage, and integration with Cloud Build, GKE, and Cloud Run.

Google Cloud Artifact Registry receiving Docker images from a workstation and delivering them to cloud servers

This guide covers Google Cloud Artifact Registry end to end: creating a repository, authenticating Docker, pushing and pulling images, cleaning up old images, and securing access. If you deploy containers to Cloud Run, see our Cloud Run deployment guide, and for scheduled cloud jobs, our Cloud Scheduler guide.

Prerequisites

  • A Google Cloud project with billing enabled, the Artifact Registry API enabled, and the Google Cloud CLI installed and authenticated.
  • Docker installed locally, and a small test image you can push, for example a simple web server image.
  • Permission to create repositories and grant IAM roles in the project, or a project administrator to grant them.

Google Cloud Artifact Registry Basics: Repositories and Regions

Artifact Registry organises images into repositories, each in one region or multi-region, with a format such as Docker. Choose a region close to where your workloads run to keep pull latency low and avoid cross-region egress charges. A repository name is part of the image path, so pick a clear, stable name: changing it later means retagging every image.

gcloud artifacts repositories create my-app \
  --repository-format=docker \
  --location=europe-west1 \
  --description="Application container images"

List repositories and images to confirm the setup, and note the full repository path, which follows the pattern of region, project, and repository name. That path is what Docker will use as the registry address.

gcloud artifacts repositories list
gcloud artifacts docker images list europe-west1-docker.pkg.dev/my-project/my-app

Replace the example region and project with your own. Artifact Registry also supports other formats, including Maven, npm, and Python packages, but this guide focuses on Docker images, which is the most common use for deployment pipelines.

Authenticating Docker with Google Cloud Artifact Registry

Docker needs credentials for the registry. The simplest reliable method is the gcloud credential helper, which configures Docker to use your gcloud authentication for the registry host. Run it once per machine, and it handles token refresh automatically:

gcloud auth configure-docker europe-west1-docker.pkg.dev

For CI pipelines, prefer a dedicated service account with only the Artifact Registry writer role, and use short-lived credentials rather than a long-lived key file. A service account that can push images should not also be able to delete repositories or change IAM policies; scope it to the repository it needs.

Pushing and Pulling Images in Google Cloud Artifact Registry

Tag your local image with the full registry path, then push it. Use immutable tags for releases, such as a git commit hash or a version number, and reserve the latest tag for development convenience only, because latest moves and makes rollbacks ambiguous.

docker tag my-app:1.0 europe-west1-docker.pkg.dev/my-project/my-app/my-app:1.0
docker push europe-west1-docker.pkg.dev/my-project/my-app/my-app:1.0
docker pull europe-west1-docker.pkg.dev/my-project/my-app/my-app:1.0

On a GKE node or Cloud Run service in the same project, pulls usually work with the workload’s service account, provided it has the Artifact Registry reader role. If a pull fails with a permission error, check the service account’s role first, then check that the image path, region, and tag are spelled exactly right, because a typo produces a misleading not-found error.

Cleaning Up and Securing Google Cloud Artifact Registry

Images accumulate quickly in a busy pipeline, so set a cleanup policy to delete old untagged images and keep only a set number of recent versions. Cleanup policies run on a schedule you define, and they are far cheaper than a manual delete job. Always protect release tags from cleanup, or a policy can delete the image a production deployment still references.

gcloud artifacts repositories set-cleanup-policies my-app \
  --location=europe-west1 \
  --policy=cleanup.json

The cleanup policy file defines which images to keep and which to delete, for example keeping the newest ten versions and deleting untagged images older than 30 days. Test a policy on a test repository first, because deleted images cannot be recovered, and a bad policy can break a rollback.

For security, enable vulnerability scanning on the repository so new images are scanned for known issues, grant reader access at the repository level rather than the project level, and use VPC Service Controls or private access where your workloads run in a private network. Review who has writer access regularly: anyone who can push an image can change what your production services run.

Troubleshooting Google Cloud Artifact Registry

Docker push fails with denied permission. Confirm the credential helper is configured for the exact registry host, and that your account or service account has the writer role on the repository. Re-run the configure command if you switched projects or regions.

Pull fails in GKE or Cloud Run. Check the workload service account’s reader role, the image path, and whether the cluster is in a different project that needs cross-project access granted explicitly.

Images disappear after cleanup. Check the cleanup policy and whether a release tag was protected. Restore from a rebuild if the image source is available, and fix the policy before the next run.

Pushes are slow. Push to a repository in the same region as your build machine, and check that large layers are not being re-uploaded unnecessarily. Layer caching in your build pipeline matters more than registry tuning for most slow pushes.

Google Cloud Artifact Registry Best Practices

Use one repository per application or team, tag releases immutably, scope IAM to the repository, enable scanning, and clean up old images with a tested policy. Keep the registry region close to your workloads, and document the image naming scheme so a new team member can find the right image without guessing.

Google Cloud Artifact Registry gives your images a private, access-controlled home that fits naturally into Google Cloud deployments. Create a repository, authenticate once, push with immutable tags, and clean up deliberately. For the official reference, see the Google Cloud Artifact Registry documentation.

You may also like

KbLinux

Typically replies within a day

Hello, Welcome to the site. Please click below button for chatting me through Telegram.