Pulling and Running Images

Introduction and Lesson Outcome

Welcome to the fourth lesson in our course on working with container registries . You've made excellent progress building your Artifact Registry expertise, learning what Google Artifact Registry is, creating secure repositories, and mastering the complete workflow of building and pushing Docker images to Artifact Registry. Now that you have container images stored securely in Artifact Registry, it's time to learn the other half of the container workflow: pulling and running those images. Understanding the pull and run workflow is crucial because it completes the full container lifecycle. While pushing images to Artifact Registry represents the development and build phase, pulling images represents the deployment and runtime phase. This lesson focuses on consuming images from Artifact Registry, which mirrors exactly how Google Cloud services like Google Kubernetes Engine (GKE) and Cloud Run retrieve and run your containerized applications in production environments. The practical outcome you'll achieve in this lesson is pulling an image from your Artifact Registry repository and running it locally as a container. You'll master the key commands docker pull for retrieving images from Artifact Registry and docker run for starting containers from those images, completing the essential skills needed for working with container registries in production environments.

What You Need (Repo URI, Region, Permissions)

Before pulling images from Artifact Registry, you need to gather key information that identifies where your images are stored in Google Cloud. This information ensures that your pull operations target the correct repository and region where your images are stored. In Google Artifact Registry, images are identified by a URI that follows a specific format: {region}-docker.pkg.dev/{project-id}/{repository-name}/{image-name}:{tag}. Let's break down each component: Region: The Google Cloud region where your repository exists (e.g., us-central1, us-east1, europe-west1). This must match the region you specified when creating your repository. Project ID: Your Google Cloud project identifier, which is a unique string that identifies your Google Cloud project (not to be confused with the project number). Repository name: The name you gave your repository when you created it (e.g., my-web-app). Image name: The name of the specific image within your repository (e.g., my-web-app). Tag: The version identifier for your image (e.g., latest, v1.0, dev). You can retrieve your repository details using the gcloud artifacts repositories describe command. This command displays information about your repository, including its location and format: Shellgcloud artifacts repositories describe my-web-app \ --location=us-central1 The output shows your repository details, including the format (which should be DOCKER) and the location. To construct your complete image URI, you'll combine these elements. For example, if your project ID is my-project-123, your repository is named my-web-app in the us-central1 region, and your image is named my-web-app, your complete URI would be: textus-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:latest For pulling images from Artifact Registry, your Google Cloud credentials need specific IAM permissions. The essential role for pulling images is roles/artifactregistry.reader, which grants the necessary permissions to read repository contents and download images. This role includes permissions to list repositories, view repository metadata, and download container images. You can verify your current permissions or grant the reader role using: Shellgcloud artifacts repositories add-iam-policy-binding my-web-app \ --location=us-central1 \ --member=user:your-email@example.com \ --role=roles/artifactregistry.reader Most Google Cloud environments that have Artifact Registry access include these pull permissions by default, since pulling images is a common operation for deployment services like GKE and Cloud Run. However, if you encounter permission errors during the pull process, verify that your account or service account has the roles/artifactregistry.reader role for the specific repository.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Pull the Image from Artifact Registry

With Docker authenticated to Artifact Registry, you can now pull the image you pushed in the previous lesson. The docker pull command downloads the image from Artifact Registry to your local Docker environment, making it available for running as a container.

Shell

docker pull us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:latest

docker pull us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:latest

The pull command requires the complete Artifact Registry repository URI, including your region, project ID, repository name, image name, and tag. This URI must exactly match the tag you used when pushing the image in the previous lesson. Remember to replace my-project-123 with your actual project ID and ensure the region matches your repository's location.

During the pull process, Docker displays detailed progress information showing the download of each image layer. Container images consist of multiple layers, and Docker downloads each layer separately. If you've pulled this image before, Docker might skip downloading layers that already exist locally and display "Layer already exists" messages.

text

latest: Pulling from my-web-app
5f70bf18a086: Pull complete
d1e017099d17: Pull complete
8ac48589692a: Pull complete
Digest: sha256:8f2a1b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a
Status: Downloaded newer image for us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:latest

latest: Pulling from my-web-app
5f70bf18a086: Pull complete
d1e017099d17: Pull complete
8ac48589692a: Pull complete
Digest: sha256:8f2a1b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a
Status: Downloaded newer image for us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:latest

The successful completion of a pull operation displays the same digest you saw when pushing the image. This digest provides cryptographic verification that you've downloaded exactly the same image you uploaded to Artifact Registry. The "Downloaded newer image" status confirms that Docker has successfully retrieved the image and made it available locally.

After the pull completes, you can verify that the image exists locally by running docker images. You'll see your Artifact Registry image listed alongside any other local images, identified by its complete Artifact Registry repository URI as the repository name and the tag you specified.

Understanding and Working with Image Tags

Image tags are version labels that help you manage multiple versions of the same container image. Think of tags as bookmarks that point to specific versions of your application—they allow you to maintain different versions for production (v1.0, v1.1), development (dev), staging (staging), or simply mark the most recent version (latest).

The same Docker image can have multiple tags, and each tag represents a specific version or variation of your application. For example, you might tag your image as v1.0 for your stable production release, latest for the most recent build, and dev for active development work. These tags make it easy to pull and run specific versions without remembering complex image digests.

When you pushed your image in the previous lesson, you used the latest tag by default. However, in production environments, teams typically create multiple tags for the same image to support different deployment scenarios:

Shell

# Tag the same image with multiple version labels
docker tag my-web-app:latest us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:v1.0
docker tag my-web-app:latest us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:dev

# Push each tagged version to Artifact Registry
docker push us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:latest
docker push us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:v1.0
docker push us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:dev

# Tag the same image with multiple version labels
docker tag my-web-app:latest us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:v1.0
docker tag my-web-app:latest us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:dev

# Push each tagged version to Artifact Registry
docker push us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:latest
docker push us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:v1.0
docker push us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:dev

The docker tag command creates a new tag reference to an existing image without duplicating the actual image data—it's simply another name pointing to the same image layers. This makes tagging extremely efficient, as you're not creating copies of the image.

To pull specific tagged versions from Artifact Registry, include the tag in your pull command:

Shell

# Pull the latest version
docker pull us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:latest

# Pull a specific version
docker pull us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:v1.0

# Pull the development version
docker pull us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:dev

# Pull the latest version
docker pull us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:latest

# Pull a specific version
docker pull us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:v1.0

# Pull the development version
docker pull us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:dev

You can list all available tags for an image in your Artifact Registry repository using:

Shell

gcloud artifacts docker images list us-central1-docker.pkg.dev/my-project-123/my-web-app

gcloud artifacts docker images list us-central1-docker.pkg.dev/my-project-123/my-web-app

This command displays all images and their tags in your repository, helping you identify which versions are available for pulling and deployment.

Running containers from different tagged versions allows you to test multiple versions simultaneously or perform gradual rollouts. You can run different tagged versions on different ports to compare behavior:

Shell

# Run the latest version on port 3000
docker run -d -p 3000:5000 us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:latest

# Run v1.0 on port 4000
docker run -d -p 4000:5000 us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:v1.0

# Run the dev version on port 5000
docker run -d -p 5000:5000 us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:dev

# Run the latest version on port 3000
docker run -d -p 3000:5000 us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:latest

# Run v1.0 on port 4000
docker run -d -p 4000:5000 us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:v1.0

# Run the dev version on port 5000
docker run -d -p 5000:5000 us-central1-docker.pkg.dev/my-project-123/my-web-app/my-web-app:dev

This ability to manage and deploy multiple image versions simultaneously is essential for production environments, where you might need to support version rollbacks, A/B testing, or blue-green deployments.

Quick Troubleshooting

Several common issues can occur during the pull and run workflow:

Incorrect repository URI leads to pull failures when the Artifact Registry repository URI contains errors or typos. Common mistakes include using the wrong project ID, misspelling the repository name, incorrect region format, or using an incorrect tag. The URI must follow the exact format: {region}-docker.pkg.dev/{project-id}/{repository-name}/{image-name}:tag. Double-check your repository URI against the output from gcloud artifacts repositories describe to ensure accuracy.
Permission issues can prevent pull operations even when authentication succeeds. If you encounter access denied errors during image pulls, verify that your Google Cloud account has the necessary IAM role for the repository. The required role is roles/artifactregistry.reader. You can check your permissions using gcloud artifacts repositories get-iam-policy or grant the necessary role using the add-iam-policy-binding command shown earlier.
Image not found errors occur when you attempt to pull an image that doesn't exist in your repository or when you specify an incorrect tag. You can verify which images and tags exist in your repository using:

Shell

gcloud artifacts docker images list us-central1-docker.pkg.dev/my-project-123/my-web-app

gcloud artifacts docker images list us-central1-docker.pkg.dev/my-project-123/my-web-app

Container startup failures can happen after successful pulls when the docker run command fails to start your container. Common causes include port conflicts, missing environment variables, or application-specific configuration issues. Port conflicts occur when another container or process is already using the port you're trying to map. To check if port 5000 is already in use by another container, run:

Shell

docker ps --filter "publish=5000"

docker ps --filter "publish=5000"

If a container is already using port 5000, you can either stop that container using docker stop <container-id> or map your new container to a different local port, such as -p 5001:5000. For other startup issues, examine container logs using docker logs to diagnose these problems.

Most of these issues can be resolved by carefully verifying your repository details, checking permissions, and examining container logs for specific error messages.

Introduction and Lesson Outcome

What You Need (Repo URI, Region, Permissions)

Join the 1M+ learners on CodeSignal

Authenticate Docker to Artifact Registry

Pull the Image from Artifact Registry

Understanding and Working with Image Tags

Run the Container Locally (Simulating GKE/Cloud Run)

Quick Troubleshooting

Summary and What's Next