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.

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:

Before pulling images from Artifact Registry, you need to authenticate Docker with Google Cloud. The authentication process for Artifact Registry is streamlined through the gcloud command-line tool.

Use the following command to configure Docker authentication for your Artifact Registry region:

Replace us-central1 with your actual repository region. This command configures Docker to use your Google Cloud credentials when accessing Artifact Registry in the specified region. When authentication succeeds, you'll see a message indicating that Docker has been configured:

This authentication configuration persists across sessions and uses your active Google Cloud credentials. If you're working with multiple regions, you can configure Docker for multiple Artifact Registry endpoints by running the command for each region or by listing them together:

The authentication relies on your active Google Cloud credentials, which you can verify using gcloud auth list. If you need to refresh your credentials or switch accounts, use gcloud auth login to authenticate with a different Google Cloud account.

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.

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.

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.

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:

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.

Now you'll run the pulled image as a container, simulating what happens when Google Cloud services like GKE or Cloud Run deploy your containerized applications:

The -d flag runs the container in detached mode (background), and -p 5000:5000 maps port 5000 from your local machine to port 5000 inside the container. Docker returns the container ID when successful—make note of this ID as you'll need it for checking logs in the next step.

Verify the container is running with docker ps:

Check the container logs to confirm your application started properly, using the container ID from the run command:

Replace <container-id> with the actual ID returned from the docker run command. Alternatively, you can use the container ID shown in the docker ps output.

Test your application by making a request to the mapped port:

If your application is a web service, this should return a response from your containerized application, confirming the entire Artifact Registry pull-to-run workflow is working correctly.

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:

• 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:

In this lesson, you completed the full container workflow by learning to pull images from Artifact Registry and run them locally. You mastered the key commands: docker pull for retrieving images from Artifact Registry and docker run for starting containers from those images. This workflow mirrors exactly what happens when Google Cloud services like GKE and Cloud Run deploy your containerized applications.

The skills you've developed across these four lessons provide a solid foundation for working with container registries in production environments. You can create secure repositories, build and push images, and pull and run those images as containers.

In the upcoming practice exercises, you'll reinforce these concepts by repeating the pull and run workflow with different variations, solidifying your understanding of Google Artifact Registry operations.