Introduction
When Minikube cannot pull an image from Amazon ECR, the problem is usually not Kubernetes itself. It is almost always one of three things: the image reference is wrong, the Minikube node runtime is not authenticated to ECR, or the Pod is missing a valid imagePullSecrets configuration.
Start With the Exact Image Name
ECR image references are strict. The registry, region, repository name, and tag all need to match exactly.
A valid reference looks like this:
123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:1.0.0
Check these first:
If the path is wrong, authentication changes will not help.
Understand Where the Pull Happens
The image pull is performed by the container runtime on the Minikube node, not by Docker on your host shell unless your setup explicitly shares that runtime. That distinction matters.
A host-side login such as this:
aws ecr get-login-password --region us-east-1 \
| docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com ``` may authenticate your local Docker client, but Kubernetes still needs credentials available to the node runtime that actually pulls the image. ## The Kubernetes-Friendly Fix: `imagePullSecrets` For Minikube, the most reliable pattern is usually to create a Docker registry secret and attach it to the Pod or service account. First get a fresh ECR password and create the secret: ```bash AWS_ACCOUNT_ID=123456789012 AWS_REGION=us-east-1 REGISTRY="$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com" kubectl create secret docker-registry ecr-creds \ --docker-server=$REGISTRY \ --docker-username=AWS \ --docker-password="$(aws ecr get-login-password --region $AWS_REGION)" ``` Then reference it in the Pod spec: ```yaml apiVersion: v1 kind: Pod metadata: name: demo spec: containers: - name: app image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:1.0.0 imagePullSecrets: - name: ecr-creds ``` Apply it with: ```bash kubectl apply -f pod.yaml ``` This is usually easier to reason about than trying to log the node runtime in manually. ## Remember That ECR Tokens Expire An ECR auth token is temporary. If image pulls suddenly start failing later, the secret may simply contain an expired token. That is why an initial success does not prove the configuration is permanently correct. For local Minikube use, recreating the secret when needed is often enough. For longer-lived clusters, you need automated credential refresh. ## Check the Pod Events Before Guessing Kubernetes usually tells you what went wrong. ```bash kubectl describe pod demo ``` Look for events such as: - '`pull access denied`' - '`no basic auth credentials`' - '`repository does not exist`' - DNS or network timeouts Those messages narrow the problem quickly. ## Verify Minikube Can Reach ECR If authentication is correct but pulls still time out, inspect network reachability from the Minikube node. ```bash minikube ssh curl -I https://123456789012.dkr.ecr.us-east-1.amazonaws.com ``` If your network requires a proxy or blocks outbound traffic, the runtime may never reach ECR even with valid credentials. ## Node Runtime Differences Matter Depending on your Minikube driver and Kubernetes version, the node may use Docker or `containerd`. That affects debugging commands. Inside the Minikube node, Docker-based checks might look like: ```bash docker info ``` For `containerd`, use CRI tools instead: ```bash sudo crictl images ``` Do not assume host Docker behavior matches what the cluster runtime is doing. ## An Alternative for Local Development If this is only local development, pulling from ECR may be more complexity than you need. In some cases, building the image directly into Minikube's runtime is simpler. ```bash eval "$(minikube docker-env)" docker build -t my-app:dev . ``` Then reference `my-app:dev` in the Pod spec and set: ```yaml imagePullPolicy: IfNotPresent ``` That bypasses ECR entirely for local work. ## Common Pitfalls Logging into host Docker and assuming Kubernetes on the Minikube node will reuse those credentials. Using the wrong AWS region or repository path in the image reference. Forgetting that ECR auth tokens expire and secrets must be refreshed. Debugging image pulls without checking `kubectl describe pod` events first. Using local development against ECR when a direct Minikube build would be simpler. ## Summary - Minikube ECR pull failures usually come from image naming, missing credentials, or expired credentials. - The most reliable Kubernetes-side fix is an `imagePullSecrets` entry backed by an ECR registry secret. - Always inspect Pod events to distinguish auth errors from network errors. - The runtime on the Minikube node, not the host shell, performs the actual pull. - For purely local workflows, building directly into Minikube may be easier than authenticating to ECR.
