Reduce latency with image prewarming

Prewarming images lets you explicitly trigger the downloading of container images into the Image Streaming cache before a runtime client requests them. This effectively eliminates the "cold start" latency associated with the first pull of a new image version for workloads using image streaming.

Overview

When you push an image to Artifact Registry, it's stored in an underlying storage system. For low-latency access, Artifact Registry also uses an Image Streaming cache, which typically populates on the first pull from a client that has image streaming enabled. For latency-sensitive workloads, like scaling up a Google Kubernetes Engine cluster, waiting for this cache to warm up can cause delays. Prewarming helps get images into the Image streaming cache in advance.

The Prewarm Artifact API lets you manually request that a specific image version or tag is precached. You also specify a retention period to ensure the image remains in the cache for a specified duration.

Limitations

  • API only: prewarming is available only using the Artifact Registry REST API. Prewarming is not available using the gcloud CLI or Cloud de Confiance console.
  • GKE only: Prewarming is only effective for GKE clusters with Image Streaming enabled. Image streaming requires specific software running on the client node.
  • Single artifact: you can prewarm only one artifact (version or tag) per API request.

Before you begin

  1. Enable the Artifact Registry API. For more information, see Enable Artifact Registry.
  2. Install the gcloud CLI to obtain authentication tokens for REST API requests.

Required roles

To get the permissions that you need to manage prewarmed images, ask your administrator to grant you the following IAM roles on the repository:

  • Prewarm or remove artifacts from cache (artifactregistry.repositories.prewarmArtifact, artifactregistry.repositories.removePrewarmedArtifact): Artifact Registry Writer (roles/artifactregistry.writer)
  • Check or list prewarmed artifacts (artifactregistry.repositories.checkPrewarmedArtifact, artifactregistry.repositories.listPrewarmedArtifacts): Artifact Registry Reader (roles/artifactregistry.reader)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

This permission model ensures that only users with write access can manage the cache state, preventing unauthorized users from overfilling the cache. Meanwhile, users with read access can verify which artifacts are available for streaming.

Prewarm an image

To prewarm an image, you make a POST request to the :prewarmArtifact method of your repository.

REST API

Reference: projects.locations.repositories.prewarmArtifact

The request body has the following structure:

{
  "artifact": {
    "version": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY/packages/PACKAGE/versions/VERSION"
  },
  "retention_days": 3
}

Alternatively, use a tag:

{
  "artifact": {
    "tag": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY/packages/PACKAGE/tags/TAG"
  },
  "retention_days": 3,
  "force": true
}
Field Description
artifact Required. The specific artifact to prewarm. You specify either a version or a tag.
retention_days Optional. The number of days to keep the artifact in the cache. If you don't specify this field, the default is 3 days.
force Optional. If true, the system might evict older artifacts to make space for this one.

Example: Prewarm a specific version

The following example prewarms the version sha256:52e... of the nginx package in the my-repo repository.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "artifact": {
      "version": "projects/my-project/locations/us-central1/repositories/my-repo/packages/nginx/versions/sha256:52e85304675567b5e656f5e997576a9d20c57176"
    },
    "retention_days": 7
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:prewarmArtifact"

Example: Prewarm a tag

The following example prewarms the image tagged production of the my-app package.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "artifact": {
      "tag": "projects/my-project/locations/us-central1/repositories/my-repo/packages/my-app/tags/production"
    },
    "force": true
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:prewarmArtifact"

Check prewarm status

To check if an artifact is prewarmed, use the :checkPrewarmedArtifact method.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "artifact": {
      "version": "projects/my-project/locations/us-central1/repositories/my-repo/packages/nginx/versions/sha256:52e85304675567b5e656f5e997576a9d20c57176"
    }
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:checkPrewarmedArtifact"

Remove from cache

To explicitly remove an artifact from the prewarm cache, use the :removePrewarmedArtifact method. Use this method to free up space or when a specific image version is no longer needed in the cache.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "artifact": {
      "version": "projects/my-project/locations/us-central1/repositories/my-repo/packages/nginx/versions/sha256:52e85304675567b5e656f5e997576a9d20c57176"
    }
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:removePrewarmedArtifact"

What's next