Introduction
Using a Docker image from Amazon ECR in EKS has three parts: build the image, push it to ECR, and deploy Kubernetes resources that reference that image. The missing detail in many short answers is authentication. The cluster can only pull from ECR if the nodes or execution environment have permission to read from that registry.
Build and Push the Image to ECR
First create or identify the ECR repository, then authenticate Docker and push the image.
aws ecr get-login-password --region us-east-1 \
| docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com docker build -t myapp . docker tag myapp:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:latest docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:latest ``` After that, the image is available in ECR. But EKS still needs pull access. ## Make Sure EKS Can Pull From ECR In a typical EKS setup, worker nodes pull images from ECR using the node IAM role. That role needs the relevant ECR read permissions. This is why referencing a correct image URL is necessary but not sufficient. If the IAM side is wrong, the pods will still fail with image-pull errors. ## Reference the ECR Image in a Deployment ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: myapp spec: replicas: 2 selector: matchLabels: app: myapp template: metadata: labels: app: myapp spec: containers: - name: myapp image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:latest ports: - containerPort: 8080 ``` Apply it with: ```bash kubectl apply -f deployment.yaml ``` That is the Kubernetes side. If permissions and networking are correct, the kubelet will pull the image from ECR. ## Verify Pull and Runtime Status After deploying, check whether the pods actually pulled the image and started successfully. ```bash kubectl get pods kubectl describe pod <pod-name> ``` If the pull fails, `kubectl describe` usually shows events such as authentication failure, repository not found, or image tag not found. ## Common Pitfalls - Pushing the image to ECR successfully but forgetting that EKS nodes also need ECR pull permissions. - Using the wrong account, region, or repository URL in the Kubernetes manifest. - Referencing a tag that was never pushed. - Debugging the deployment YAML first when the real problem is IAM or ECR access. ## Summary - Build the Docker image, tag it with the ECR repository URL, and push it to ECR. - Make sure the EKS execution environment has permission to pull from that ECR repository. - Reference the full ECR image URL in the Kubernetes deployment. - Use `kubectl describe pod` to debug pull failures. - In EKS, image deployment is both a Kubernetes configuration task and an IAM configuration task.
