Container Images in GCP Explained: Docker, Artifact Registry, and Best Practices

Simple explanation

A container image is a self-contained, portable package of your application. It bundles your code, the runtime it needs (Python, Node, Go, or whatever you use), all dependencies, and the instructions to start the app into a single unit you can build once and run anywhere.

The key distinction beginners often miss: an image is static. It does not run. A container is a running instance of an image, the same way a class is a blueprint and an object is an instance of it. Cloud Run and GKE pull images from a registry and create containers from them.

What is a container image in GCP?

In GCP, a container image is the deployable artefact for most container-based services. It contains:

• your application code
• the runtime (e.g. Python 3.12, Node 20)
• all installed dependencies
• environment defaults and startup commands
• the filesystem layout the app expects

When you deploy a Cloud Run service, GCP pulls the image you specify from Artifact Registry and starts a container from it. When you deploy a workload to GKE, each pod starts a container from an image stored in the same place. The image format is standard: it follows the OCI (Open Container Initiative) specification, which means images built locally with Docker run on GCP without modification.

How container images fit into a typical GCP workflow

Here is the end-to-end flow from code to running service. Each step is covered in more detail further down this page.

1. Write application code. A Python Flask API, a Node.js server, a Go binary. Any language works.
2. Create a Dockerfile. The Dockerfile is the recipe: it tells Docker how to build the image from a base image, install dependencies, copy your code, and set the start command.
3. Build the image. Run docker build locally or use Cloud Build to build without local Docker dependencies.
4. Push the image to Artifact Registry. The built image gets a name like us-central1-docker.pkg.dev/PROJECT_ID/my-repo/my-app:v1 and is uploaded to GCP.
5. Deploy to Cloud Run or GKE. You reference that image name when deploying. GCP pulls the image and starts containers from it.
6. Roll forward or roll back. New versions get new tags or digests. Rolling back means pointing your service at an earlier image. The old image stays in Artifact Registry.

This workflow is the same whether you are deploying once manually or automating it with a CI/CD pipeline.

Dockerfile basics

A Dockerfile is a text file containing ordered instructions that tell Docker how to build your image. Each instruction creates a layer. Understanding layers is the key to fast, efficient builds.

# Python 3.12 slim base image
FROM python:3.12-slim

# Set the working directory inside the container
WORKDIR /app

# Copy only the dependency file first
COPY requirements.txt .

# Install dependencies (cached unless requirements.txt changes)
RUN pip install --no-cache-dir -r requirements.txt

# Now copy the rest of the source code
COPY . .

# Tell Docker how to start the app
CMD ["python", "app.py"]

Layer caching and instruction order

Every Dockerfile instruction that modifies the filesystem creates a layer. Docker stores each layer separately and reuses cached layers on subsequent builds, as long as nothing above that layer changed.

Cache invalidation works top-to-bottom. As soon as one layer changes, every layer below it is rebuilt from scratch. This means instruction order is not just style. It directly affects how long your builds take.

# Bad: source code copied before dependencies are installed
FROM python:3.12-slim
WORKDIR /app
COPY . .                               # Invalidated on every code change
RUN pip install -r requirements.txt    # Reinstalls everything every build
CMD ["python", "app.py"]

# Good: dependencies installed before source code is copied
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .                # Only invalidated if requirements.txt changes
RUN pip install -r requirements.txt    # Cached unless dependencies actually change
COPY . .                               # Rebuilt on code changes, but this is fast
CMD ["python", "app.py"]

Multi-stage builds

A multi-stage build uses two or more FROM instructions in a single Dockerfile. The first stage (the builder) has all the tools needed to compile or bundle the app. The second stage (the runtime) contains only what is needed to run it.

# Stage 1: builder stage with full Go toolchain
FROM golang:1.22 AS builder
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 go build -o /app .

# Stage 2: runtime stage with tiny distroless base
FROM gcr.io/distroless/static-debian12
COPY --from=builder /app /app
ENTRYPOINT ["/app"]

The Go compiler, test dependencies, and source code never appear in the final image. Only the compiled binary and the minimal distroless base are included. The result is an image under 10MB instead of 800MB+.

Choosing a base image

The base image you choose has a significant impact on image size, startup time, and security posture. Here is a comparison of the four main types:

The .dockerignore file

When you run docker build, Docker sends the entire contents of the current directory to the build daemon as the build context. This happens before any instructions run. Without a .dockerignore file, the context includes node_modules, .git, test fixtures, and local .env files.

# .dockerignore
.git
.gitignore
node_modules
__pycache__
*.pyc
.env
.env.*
.env.local
tests/
docs/
README.md
*.log
dist/
.DS_Store

A .dockerignore file belongs in every project that uses Docker. Create it at the same time as the Dockerfile. Storing secrets in Secret Manager and loading them at runtime is safer than any exclusion list.

Artifact Registry overview

Artifact Registry is the managed service in GCP for storing container images and other build artefacts. It replaced the older Container Registry (gcr.io) and adds support for npm, Maven, PyPI, Helm charts, and other formats alongside Docker.

Images in Artifact Registry are organised into repositories. A repository belongs to a specific region and holds images with a consistent naming format:

REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME:TAG

For example: us-central1-docker.pkg.dev/my-project/backend/api:v2.1

Teams use Artifact Registry for four main reasons:

• Storage. Images are stored close to where they run, reducing pull latency.
• Access control. IAM roles control who can push and pull from each repository.
• Cleanup. Retention policies automatically delete old or untagged images.
• Vulnerability scanning. Artifact Analysis scans images for known CVEs automatically after push.

# Create a Docker repository in Artifact Registry
gcloud artifacts repositories create my-repo \
  --repository-format=docker \
  --location=us-central1

# Configure Docker to authenticate with Artifact Registry
gcloud auth configure-docker us-central1-docker.pkg.dev

# Build, tag, and push an image
docker build -t us-central1-docker.pkg.dev/PROJECT_ID/my-repo/my-app:v1 .
docker push us-central1-docker.pkg.dev/PROJECT_ID/my-repo/my-app:v1

# List images in a repository
gcloud artifacts docker images list \
  us-central1-docker.pkg.dev/PROJECT_ID/my-repo

For a deeper walkthrough of repository setup, access control, and cleanup policies, see the Artifact Registry Overview and Artifact Registry Best Practices.

Container Registry vs Artifact Registry

If you see documentation or tutorials referencing gcr.io, they are using the old Container Registry. Here is the key difference:

Tags vs digests

Every image in a registry can be referenced in two ways.

Tags are human-readable labels like :v1.2, :latest, or :production. They are mutable: pushing a new image with the same tag silently moves the pointer to the new image. Tags are useful during development and for communicating intent, but they are not reliable identifiers for production deployments.

Digests are content-addressed identifiers like sha256:a8f3c2d…. They are computed from the image content and are immutable: a digest will always refer to exactly the image that produced it. If you pin a deployment to a digest, it will run the same image every time, regardless of what happens to the tag.

The practical advice: use tags in your CI/CD workflow for readability (tag with the git commit SHA, for example). When deploying to production or writing rollback procedures, resolve the tag to a digest and use the digest reference. This is what Binary Authorization enforces by default: it requires a digest-based image reference to verify attestations.

Building with Cloud Build

Cloud Build is GCP’s managed build service. It builds container images in the cloud without requiring Docker installed on your machine. Builds run in a consistent, isolated environment and push directly to Artifact Registry, which makes it the standard approach in CI/CD pipelines.

# Build and push in one command, no local Docker needed
gcloud builds submit \
  --tag=us-central1-docker.pkg.dev/PROJECT_ID/my-repo/my-app:v1 \
  .

# cloudbuild.yaml: tag with the git commit SHA for traceability
steps:
  - name: 'gcr.io/cloud-builders/docker'
    args:
      - 'build'
      - '-t'
      - 'us-central1-docker.pkg.dev/$PROJECT_ID/my-repo/my-app:$SHORT_SHA'
      - '.'
images:
  - 'us-central1-docker.pkg.dev/$PROJECT_ID/my-repo/my-app:$SHORT_SHA'

Using $SHORT_SHA tags each image with the git commit hash. This makes images traceable back to the exact commit that produced them, which is essential for debugging and rollbacks. For a detailed walkthrough of CI/CD with Cloud Build, see Building Docker Images with Cloud Build.

Security and best practices

• Use small base images. Fewer installed packages means fewer potential CVEs. Slim and distroless bases have smaller attack surfaces than full images.
• Scan images after push. Enable Artifact Analysis in Artifact Registry. It automatically scans pushed images for known CVEs and surfaces the results in the GCP console.
• Pin base image versions. Using FROM python:3.12-slim instead of FROM python:slim prevents surprise upgrades when base images change.
• Rebuild images regularly. Even if your app code has not changed, the base image may have had security patches applied. Rebuild to pick them up.
• Use non-root users where possible. Add a USER instruction to run the app as a non-root user inside the container.
• Consider Binary Authorization for production. Binary Authorization enforces that only attested, approved images are deployed to Cloud Run or GKE.

Cloud Run and GKE: two ways to run the same image

Container images are the common currency between Cloud Run and GKE. You build and push the image once; the platform you choose determines how it runs.

Cloud Run is serverless. You deploy a service, specify the image, and Cloud Run handles scaling, load balancing, and infrastructure. Each new deployment creates a new revision that references a specific image. Traffic can be split between revisions, making canary rollouts and rollbacks straightforward. See the Cloud Run Overview for more, and Cloud Run Security for securing the service account and invocation.

GKE is managed Kubernetes. Your pods reference a container image in their spec, and Kubernetes pulls and runs it across nodes in the cluster. You have more control over networking, scheduling, and persistent workloads, though with more configuration to manage. See the GKE Overview for when this trade-off makes sense.

If you are not sure which to use, the Cloud Run vs GKE vs VMs comparison works through the decision.

Container images vs VM images

GCP has two different types of images that beginners sometimes confuse:

Container images share the host OS kernel and include only the application layer above it. VM images include a full operating system. This makes container images much smaller and faster to start, but they depend on the host kernel. If you need a specific OS kernel version or kernel modules, a VM is the right tool. See the VM Images guide for how Compute Engine images work.

When to use container images

Container images are the right packaging format when:

• you are deploying a custom application to Cloud Run or GKE
• you want consistency between local development, staging, and production
• you are building a CI/CD pipeline that needs reproducible, versioned builds
• you need to run multiple services with different runtimes on the same infrastructure
• you want fast rollbacks by pointing the service at an older image