Welcome to the fourth lesson in our course on Working with Container Registries. You've made excellent progress building your ECR expertise, learning what Amazon ECR is, creating secure repositories, and mastering the complete workflow of building and pushing Docker images to ECR. Now that you have container images stored securely in ECR, 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 ECR represents the development and build phase, pulling images represents the deployment and runtime phase. This lesson focuses on consuming images from ECR, which mirrors exactly how AWS services like Amazon ECS and Amazon EKS retrieve and run your containerized applications in production environments.
The practical outcome you'll achieve in this lesson is pulling an image from your ECR repository and running it locally as a container. You'll master the key commands docker pull for retrieving images from ECR 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 ECR, you need to gather the same key information you used when pushing images in the previous lesson. This information ensures that your pull operations target the correct repository and region where your images are stored.
Your account ID remains the 12-digit number that uniquely identifies your AWS account and forms part of your ECR repository URI. Your region must match the region where your ECR repository exists, and this consistency is critical for both authentication and pull operations. Your repository URI combines these elements with your repository name to create the complete address that Docker uses to locate and pull your images.
As a reminder from the previous lesson, you can retrieve this information using the aws ecr describe-repositories command. This command displays your repository details, including the complete repository URI that follows the format {account-id}.dkr.ecr.{region}.amazonaws.com/{repository-name}. You'll use this exact URI format when pulling images, just as you did when pushing them.
The output shows your repository URI in the repositoryUri field, which you'll need for the pull operation. For example, if your account ID is 123456789012 and your repository is in us-east-1, your repository URI would be 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-web-app.
For pulling images from ECR, your AWS credentials need specific permissions that differ slightly from the push permissions you used previously. The essential permissions for pulling images are ecr:BatchGetImage and ecr:GetDownloadUrlForLayer. These permissions allow Docker to retrieve the image manifest and download the individual layers that make up your container image. You also need ecr:GetAuthorizationToken for authentication, which is the same permission required for pushing images.
Most AWS environments and IAM roles that have ECR access include these pull permissions by default, since pulling images is a common operation for deployment services like ECS and EKS. However, if you encounter permission errors during the pull process, these are the specific permissions to verify in your IAM policies or roles.
As you learned in the previous lesson, you need to authenticate Docker with ECR before pulling images. Use the same authentication command:
Replace 123456789012 with your actual AWS account ID and ensure the region matches your repository's region. When authentication succeeds, Docker displays:
Remember that authentication tokens expire after 12 hours, so re-authenticate if significant time has passed since your last session.
With Docker authenticated to ECR, you can now pull the image you pushed in the previous lesson. The docker pull command downloads the image from ECR to your local Docker environment, making it available for running as a container.
The pull command requires the complete ECR repository URI, including your account ID, region, repository name, and tag. This URI must exactly match the tag you used when pushing the image in the previous lesson. Remember to replace 123456789012 with your actual account 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 ECR. 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 ECR image listed alongside any other local images, identified by its complete ECR repository URI as the repository name and the tag you specified.
Now you'll run the pulled image as a container, simulating what happens when AWS services like ECS or EKS deploy your containerized applications:
The -d flag runs the container in detached mode (background), and -p 3000:3000 maps port 3000 from your local machine to port 3000 inside the container. Docker returns the container ID when successful.
Verify the container is running with docker ps:
Check the container logs to confirm your application started properly:
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 ECR 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 ECR repository URI contains errors or typos. Common mistakes include using the wrong account ID, misspelling the repository name, or using an incorrect tag. Double-check your repository URI against the output from
aws ecr describe-repositoriesto ensure accuracy. -
Permission issues can prevent pull operations even when authentication succeeds. If you encounter access denied errors during image pulls, verify that your AWS credentials have the necessary ECR permissions:
ecr:BatchGetImageandecr:GetDownloadUrlForLayer. -
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 runcommand fails to start your container. Common causes include port conflicts, missing environment variables, or application-specific configuration issues. Examine container logs usingdocker logsto 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.
In this lesson, you completed the full container workflow by learning to pull images from ECR and run them locally. You mastered the key commands: docker pull for retrieving images from ECR and docker run for starting containers from those images. This workflow mirrors exactly what happens when AWS services like ECS and EKS 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 Amazon ECR operations.
