Linden Consulting.
DevOps

ECR RepositoryNotFoundException und Image-Pull-Fehler in ECS/EKS

2026-05-06 · 8 Min. Lesezeit

Ihr ECS-Deployment ist gerade fehlgeschlagen. Das Service-Event-Log zeigt die gefürchtete Meldung:

CannotPullContainerError: Error response from daemon: pull access denied for
123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app, repository does not exist
or may require 'docker login'

Oder vielleicht steckt Ihr EKS-Pod im ImagePullBackOff:

Failed to pull image "123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:v2.1.0":
rpc error: code = NotFound desc = failed to pull and unpack image: failed to
resolve reference: 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:v2.1.0:
not found

Diese Fehler sehen einfach aus — das Image ist nicht da. Aber nach meiner Erfahrung als AWS-Berater existiert das Image fast immer. Das Problem liegt normalerweise an Berechtigungen, Authentifizierung, Netzwerk oder einem subtilen Namens-Mismatch. Lassen Sie mich Sie durch den systematischen Ansatz zur Diagnose und Behebung von ECR-Image-Pull-Fehlern führen.

Schritt 1: Repository-Existenz verifizieren

Beginnen Sie mit dem Offensichtlichen. Bestätigen Sie, dass das Repository im erwarteten Account und der erwarteten Region existiert:

aws ecr describe-repositories \
  --repository-names my-app \
  --region us-east-1 \
  --query 'repositories[0].{Name:repositoryName,URI:repositoryUri,CreatedAt:createdAt}' \
  --output table

Wenn dies RepositoryNotFoundException zurückgibt, ist entweder der Repository-Name falsch, Sie zielen auf die falsche Region, oder Sie sind im falschen AWS-Account authentifiziert.

Prüfen Sie Ihre aktuelle Identität:

aws sts get-caller-identity \
  --query '{Account:Account,Arn:Arn}' \
  --output table

Häufige Fehler: Das Repository heißt myapp, aber die Task-Definition referenziert my-app, oder das Repository ist in eu-west-1, aber der ECS-Cluster in us-east-1.

Ursache 1: ECR-Authentifizierungstoken abgelaufen

ECR-Authentifizierungstoken sind nur 12 Stunden gültig. Wenn Ihre Deployment-Pipeline das Token cached oder das Kubelet-Token Ihres Knotens abgelaufen ist, schlagen Image-Pulls mit einem Access-Denied-Fehler fehl, der wie ein Repository-Not-Found-Fehler aussieht.

Für ECS auf EC2 übernimmt der ECS-Agent die Authentifizierung automatisch — aber nur, wenn die EC2-Instanzrolle die korrekten Berechtigungen hat. Für EKS müssen Sie sicherstellen, dass das Kubelet das ECR-Token erneuern kann.

Prüfen Sie, ob Sie sich gerade authentifizieren können:

aws ecr get-login-password --region us-east-1 | docker login \
  --username AWS \
  --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

Wenn dies fehlschlägt, sind Ihre IAM-Berechtigungen das Problem. Die Rolle benötigt mindestens:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage"
      ],
      "Resource": "arn:aws:ecr:us-east-1:123456789012:repository/my-app"
    }
  ]
}

Beachten Sie, dass ecr:GetAuthorizationToken Resource: "*" benötigt — es kann nicht auf ein bestimmtes Repository eingeschränkt werden.

Ursache 2: Fehlende ECS-Task-Execution-Role-Berechtigungen

Dies ist die häufigste Ursache für Image-Pull-Fehler in ECS Fargate. Die Task-Execution-Role (nicht die Task-Role) ist das, was ECS zum Pullen von Images und Senden von Logs verwendet. Wenn Sie kürzlich eine neue Task-Definition erstellt oder die Execution-Role geändert haben, fehlen möglicherweise die ECR-Berechtigungen.

Prüfen Sie die Task-Execution-Role:

# Execution-Role aus der Task-Definition abrufen
aws ecs describe-task-definition \
  --task-definition my-app:latest \
  --query 'taskDefinition.executionRoleArn' \
  --output text

# Angehängte Policies prüfen
ROLE_NAME=$(aws ecs describe-task-definition \
  --task-definition my-app:latest \
  --query 'taskDefinition.executionRoleArn' \
  --output text | awk -F'/' '{print $NF}')

aws iam list-attached-role-policies \
  --role-name $ROLE_NAME \
  --query 'AttachedPolicies[*].PolicyName' \
  --output table

Die Execution-Role sollte die AWS-verwaltete Policy AmazonECSTaskExecutionRolePolicy haben, oder gleichwertige benutzerdefinierte Berechtigungen. Wenn Sie eine benutzerdefinierte Policy verwenden, verifizieren Sie, dass sie Folgendes enthält:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken",
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "*"
    }
  ]
}

Ursache 3: Image-Tag existiert nicht

Sie pullen my-app:v2.1.0, aber dieser Tag wurde nie gepusht — oder er wurde gepusht und dann durch eine Lifecycle-Policy überschrieben oder gelöscht.

Listen Sie die verfügbaren Tags auf:

aws ecr describe-images \
  --repository-name my-app \
  --query 'imageDetails[*].{Tags:imageTags,PushedAt:imagePushedAt,Size:imageSizeInBytes}' \
  --output table \
  | sort -k3 -r \
  | head -20

Prüfen Sie, ob ein bestimmter Tag existiert:

aws ecr batch-get-image \
  --repository-name my-app \
  --image-ids imageTag=v2.1.0 \
  --query 'images[0].imageId' \
  --output json

Wenn der Tag fehlt, prüfen Sie zwei Dinge:

Lifecycle-Policies könnten das Image gelöscht haben:

aws ecr get-lifecycle-policy \
  --repository-name my-app \
  --query 'lifecyclePolicyText' \
  --output text | python3 -m json.tool

Eine häufige Fehlkonfiguration ist eine Lifecycle-Policy, die Images älter als N Tage löscht, ohne getaggte Releases auszuschließen. Diese Policy behält sicher die letzten 10 getaggten Images:

{
  "rules": [
    {
      "rulePriority": 1,
      "description": "Nur die letzten 10 getaggten Images behalten",
      "selection": {
        "tagStatus": "tagged",
        "tagPrefixList": ["v"],
        "countType": "imageCountMoreThan",
        "countNumber": 10
      },
      "action": {
        "type": "expire"
      }
    },
    {
      "rulePriority": 2,
      "description": "Ungetaggte Images nach 1 Tag entfernen",
      "selection": {
        "tagStatus": "untagged",
        "countType": "sinceImagePushed",
        "countUnit": "days",
        "countNumber": 1
      },
      "action": {
        "type": "expire"
      }
    }
  ]
}

Tag-Mutability-Probleme: Wenn Ihr Repository Tag-Mutability erlaubt (Standard), könnte jemand ein anderes Image unter demselben Tag gepusht haben, oder der Tag wurde verschoben. Erwägen Sie, Tag-Immutability für Produktions-Repositories zu aktivieren:

aws ecr put-image-tag-mutability \
  --repository-name my-app \
  --image-tag-mutability IMMUTABLE

Ursache 4: Cross-Account-ECR-Zugriff

Wenn Ihre ECS/EKS-Workloads in Account B laufen, das ECR-Repository aber in Account A ist, benötigen Sie eine Repository-Policy in Account A, die Account B das Pullen von Images erlaubt.

Prüfen Sie die Repository-Policy:

aws ecr get-repository-policy \
  --repository-name my-app \
  --query 'policyText' \
  --output text | python3 -m json.tool

Wenn dies RepositoryPolicyNotFoundException zurückgibt, wurde kein Cross-Account-Zugriff konfiguriert. Richten Sie einen ein:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCrossAccountPull",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::222222222222:root"
      },
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage"
      ]
    }
  ]
}

aws ecr set-repository-policy \
  --repository-name my-app \
  --policy-text file://ecr-policy.json

Der konsumierende Account benötigt ebenfalls IAM-Berechtigungen — die Repository-Policy allein reicht nicht aus. Die Task-Execution-Role in Account B benötigt ecr:GetAuthorizationToken (auf *) und die Image-Pull-Aktionen auf dem Repository-ARN in Account A.

Ursache 5: VPC-Endpoints fehlen für private Subnetze

Wenn Ihre ECS-Tasks oder EKS-Pods in privaten Subnetzen ohne NAT-Gateway laufen, können sie die öffentlichen ECR-Endpoints nicht erreichen. Sie benötigen VPC-Endpoints für ECR.

ECR erfordert zwei VPC-Endpoints — das wird häufig übersehen:

  • com.amazonaws.us-east-1.ecr.api — für ECR-API-Aufrufe (Authentifizierung, Describe)
  • com.amazonaws.us-east-1.ecr.dkr — für Docker-Image-Layer-Downloads

Außerdem benötigen Sie einen S3-Gateway-Endpoint, da ECR Image-Layer in S3 speichert:

  • com.amazonaws.us-east-1.s3 — Gateway-Endpoint für S3

Prüfen Sie, ob die Endpoints existieren:

aws ec2 describe-vpc-endpoints \
  --filters "Name=vpc-id,Values=vpc-abc123" \
  --query 'VpcEndpoints[*].{Service:ServiceName,State:State,Type:VpcEndpointType}' \
  --output table

Wenn einer der drei fehlt, hängen Image-Pulls und laufen schließlich in ein Timeout. Das Timeout sieht wie ein Netzwerkfehler aus, nicht wie ein Berechtigungsfehler, was die Diagnose erschwert:

CannotPullContainerError: ref pull has been retried 5 time(s): failed to copy:
httpReadSeeker: failed open: failed to do request: dial tcp
123456789012.dkr.ecr.us-east-1.amazonaws.com:443: i/o timeout

Erstellen Sie die fehlenden Endpoints:

# ECR-API-Endpoint
aws ec2 create-vpc-endpoint \
  --vpc-id vpc-abc123 \
  --vpc-endpoint-type Interface \
  --service-name com.amazonaws.us-east-1.ecr.api \
  --subnet-ids subnet-111 subnet-222 \
  --security-group-ids sg-xxx \
  --private-dns-enabled

# ECR-Docker-Endpoint
aws ec2 create-vpc-endpoint \
  --vpc-id vpc-abc123 \
  --vpc-endpoint-type Interface \
  --service-name com.amazonaws.us-east-1.ecr.dkr \
  --subnet-ids subnet-111 subnet-222 \
  --security-group-ids sg-xxx \
  --private-dns-enabled

# S3-Gateway-Endpoint
aws ec2 create-vpc-endpoint \
  --vpc-id vpc-abc123 \
  --vpc-endpoint-type Gateway \
  --service-name com.amazonaws.us-east-1.s3 \
  --route-table-ids rtb-xxx

Stellen Sie sicher, dass die Security-Group der Interface-Endpoints eingehenden HTTPS-Traffic (Port 443) von der Security-Group Ihrer ECS-Tasks oder EKS-Pods erlaubt.

Ursache 6: Pull-Through-Cache-Fehlkonfiguration

Wenn Sie ECR-Pull-Through-Cache-Regeln verwenden, um Images von Docker Hub, Quay oder anderen Registries zu spiegeln, wurde das gecachte Image möglicherweise noch nicht gezogen, oder die Upstream-Credentials sind ungültig.

Prüfen Sie Ihre Pull-Through-Cache-Regeln:

aws ecr describe-pull-through-cache-rules \
  --query 'pullThroughCacheRules[*].{Prefix:ecrRepositoryPrefix,Upstream:upstreamRegistryUrl}' \
  --output table

Diagnose-Workflow-Zusammenfassung

Wenn Sie auf einen ECR-Image-Pull-Fehler stoßen, arbeiten Sie diese Checkliste ab:

  1. Repository-Existenz verifizieren im richtigen Account und der richtigen Region
  2. Authentifizierung prüfen — können Sie ein Login-Token erhalten?
  3. Image-Tag-Existenz verifizieren — wurde er durch eine Lifecycle-Policy gelöscht?
  4. Task-Execution-Role prüfen auf ECR-Pull-Berechtigungen
  5. Für Cross-Account: sowohl Repository-Policy als auch IAM-Berechtigungen verifizieren
  6. Für private Subnetze: sicherstellen, dass alle drei VPC-Endpoints existieren (ecr.api, ecr.dkr, s3)

Präventions-Best-Practices

  1. Image-Digests statt Tags verwenden für Produktions-Deployments. Digests sind unveränderlich und können nicht versehentlich überschrieben oder gelöscht werden:
# Digest für einen bestimmten Tag abrufen
aws ecr batch-get-image \
  --repository-name my-app \
  --image-ids imageTag=v2.1.0 \
  --query 'images[0].imageId.imageDigest' \
  --output text

  1. Tag-Immutability aktivieren für Produktions-Repositories, um das Überschreiben von Tags zu verhindern.

  2. Lifecycle-Policies regelmäßig auditieren, um sicherzustellen, dass sie keine Images löschen, die noch von laufenden Task-Definitionen referenziert werden.

  3. ECR-Image-Scanning nutzen, um Schwachstellen vor dem Deployment zu erkennen, und EventBridge-Regeln einrichten, die bei kritischen Findings alarmieren.

  4. ECR-Berechtigungen in Infrastructure as Code standardisieren. Definieren Sie Task-Execution-Role, Repository-Policy und VPC-Endpoints in CloudFormation oder CDK für konsistente Konfiguration.

Hilfe bei Container-Deployments nötig?

ECR-Image-Pull-Fehler blockieren Deployments und frustrieren Engineering-Teams. Wenn Ihre Container-Deployment-Pipeline unzuverlässig ist oder Sie Cross-Account-ECR-Zugriff und VPC-Endpoints zum ersten Mal einrichten, können wir Ihnen helfen. Kontaktieren Sie uns für eine kostenlose AWS-Beratung — wir sind spezialisiert auf den Aufbau zuverlässiger Container-Deployment-Pipelines auf ECS und EKS.

Brauchen Sie Hilfe mit Ihrer AWS-Infrastruktur?

Buchen Sie ein kostenloses 30-Minuten-Gespräch.

Kostenloses Erstgespräch buchen