AWS ECS Fargate containers

ECS Fargate task zatrzymany: diagnostyka awarii kontenerów

Naprawa tasków ECS Fargate, które się zatrzymują z Essential container exited, OutOfMemoryError lub CannotPullContainerError. Diagnostyka na podstawie metadanych i logów CloudWatch.

Jerzy Kopaczewski ·
Taski ECS ciągle się zatrzymują i restartują. Serwis wygląda na zdrowy w konsoli, ale użytkownicy doświadczają sporadycznych błędów. Ten runbook pokazuje jak zidentyfikować przyczynę i naprawić najczęstsze problemy.

Ten runbook opisuje najczęstsze awarie tasków ECS Fargate. Aby zapewnić bieżące utrzymanie kontenerów, zobacz CloudOps Maintenance. Przykład migracji do ECS znajdziesz w case study: EC2 do ECS z Fargate.

Objaw

Taski są ciągle zatrzymywane i zastępowane. Eventy serwisu ECS pokazują:

# Check stopped task reason
aws ecs describe-tasks \
  --cluster my-cluster \
  --tasks $(aws ecs list-tasks --cluster my-cluster \
    --service-name my-service --desired-status STOPPED \
    --query 'taskArns[0]' --output text) \
  --query 'tasks[0].{reason:stoppedReason,status:lastStatus,stopCode:stopCode}'

# Common outputs:
# "Essential container in task exited"
# "Task stopped by: OutOfMemoryError: Container killed due to memory usage"
# "CannotPullContainerError: pull image manifest has been retried 5 time(s)"

# Check service events for patterns
aws ecs describe-services \
  --cluster my-cluster \
  --services my-service \
  --query 'services[0].events[:10].[createdAt,message]' \
  --output table

Możesz też zaobserwować, że serwis oscyluje między żądaną liczbą tasków a zerem, lub wysoką liczbę zatrzymanych tasków w konsoli ECS.

Przyczyna

Taski ECS Fargate zatrzymują się z trzech głównych powodów:

1. Brak pamięci (OOMKill): Kontener przekracza skonfigurowany twardy limit pamięci. Fargate natychmiast ubija kontener bez graceful shutdown. Jest to częste, gdy limity pamięci są ustawione zbyt blisko rzeczywistego użycia lub gdy aplikacja ma wycieki pamięci.

2. Essential container exited: Główny proces kontenera uległ awarii (niezerowy exit code) lub zakończył się poprawnie (exit code 0, ale task definition oczekuje ciągłego działania). Częstą przyczyną są nieobsłużone wyjątki, brakujące zmienne środowiskowe lub nieudane health checki, które powodują zastąpienie kontenera.

3. CannotPullContainerError: Fargate nie może pobrać obrazu z rejestru. Dzieje się tak, gdy uprawnienia ECR są źle skonfigurowane, tag obrazu nie istnieje lub VPC nie ma NAT Gateway / VPC endpoint dla ECR.

Rozwiązanie

A) Brak pamięci: zwiększ limity:

# Check actual memory usage before the kill
aws logs filter-log-events \
  --log-group-name /ecs/my-service \
  --filter-pattern "memory" \
  --start-time $(date -d '1 hour ago' +%s000) \
  --query 'events[*].message'

# Check Container Insights for peak memory (if enabled)
aws cloudwatch get-metric-statistics \
  --namespace ECS/ContainerInsights \
  --metric-name MemoryUtilized \
  --dimensions Name=ServiceName,Value=my-service \
               Name=ClusterName,Value=my-cluster \
  --start-time $(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%S) \
  --end-time $(date -u +%Y-%m-%dT%H:%M:%S) \
  --period 60 --statistics Maximum \
  --query 'Datapoints | sort_by(@, &Timestamp) | [-5:]'

# Update task definition with higher memory
# Rule of thumb: set hard limit to 1.5x observed peak
aws ecs register-task-definition \
  --cli-input-json file://task-definition.json
# Then update the service to use the new task definition revision
aws ecs update-service \
  --cluster my-cluster \
  --service my-service \
  --task-definition my-service:NEW_REVISION

B) Essential container exited: sprawdź logi i health checki:

# Get the exit code of the stopped container
aws ecs describe-tasks \
  --cluster my-cluster \
  --tasks <TASK_ARN> \
  --query 'tasks[0].containers[*].{name:name,exitCode:exitCode,reason:reason}'

# Check CloudWatch logs for crash reason
aws logs tail /ecs/my-service --since 30m --format short | tail -50

# If health check is killing the container, review the health check config:
# - Ensure the health check endpoint returns 200 within the timeout
# - Increase startPeriod for slow-starting applications (default: 0s)
# - Common fix: set startPeriod to 60-120s for Java/Spring apps

# Check environment variables are properly set
aws ecs describe-task-definition \
  --task-definition my-service \
  --query 'taskDefinition.containerDefinitions[0].environment'

C) CannotPullContainerError: napraw dostęp do obrazu:

# Verify the image exists in ECR
aws ecr describe-images \
  --repository-name my-service \
  --image-ids imageTag=latest \
  --query 'imageDetails[0].imagePushedAt'

# Check task execution role has ECR permissions
aws iam simulate-principal-policy \
  --policy-source-arn arn:aws:iam::123456789012:role/ecsTaskExecutionRole \
  --action-names ecr:GetDownloadUrlForLayer ecr:BatchGetImage \
  --query 'EvaluationResults[*].{Action:EvalActionName,Decision:EvalDecision}'

# If using private subnets, verify VPC endpoints or NAT Gateway exist
aws ec2 describe-vpc-endpoints \
  --filters "Name=service-name,Values=com.amazonaws.eu-west-1.ecr.dkr" \
  --query 'VpcEndpoints[*].{VpcId:VpcId,State:State}'

Prewencja: Ustaw soft limit pamięci (memoryReservation) na rzeczywiste oczekiwane zużycie, a hard limit na 1.5x szczytu. Skonfiguruj startPeriod health checka z zapasem dla wolno startujących aplikacji. W produkcji przypinaj tagi obrazów do konkretnych digestów zamiast używać latest.

Walidacja

# 1. Check tasks are running and stable
aws ecs describe-services \
  --cluster my-cluster \
  --services my-service \
  --query 'services[0].{running:runningCount,desired:desiredCount,pending:pendingCount}'
# Expected: running == desired, pending == 0

# 2. Verify no recent task stops
aws ecs list-tasks --cluster my-cluster \
  --service-name my-service --desired-status STOPPED \
  --query 'taskArns | length(@)'
# Expected: 0 or only old tasks

# 3. Check service events for stability (no recent restarts)
aws ecs describe-services \
  --cluster my-cluster \
  --services my-service \
  --query 'services[0].events[:5].message'
# Expected: "has reached a steady state" message

# 4. Verify health check passing
aws elbv2 describe-target-health \
  --target-group-arn <TARGET_GROUP_ARN> \
  --query 'TargetHealthDescriptions[*].{Target:Target.Id,Health:TargetHealth.State}'
# Expected: all targets "healthy"

Jeśli serwis utrzymuje steady state przez 10+ minut bez zatrzymanych tasków, problem jest rozwiązany. Monitoruj alarmy CloudWatch dotyczące spadku liczby tasków przez następne 24 godziny.

Najczęstsze pytania o zatrzymania tasków ECS Fargate

Co oznacza „Essential container in task exited" na ECS Fargate?

Oznacza to, że kontener oznaczony jako essential w task definition przestał działać, więc ECS zatrzymał cały task. Każdy task ma przynajmniej jeden kontener essential i kiedy którykolwiek z nich się zakończy - czy to awaryjnie z niezerowym exit code, czy poprawnie z kodem 0 - ECS traktuje cały task jako nieudany i go zastępuje. Sam komunikat nie mówi, dlaczego kontener się zakończył; wskazuje jedynie, które zdarzenie zatrzymało task. Aby znaleźć przyczynę, pobierz exit code kontenera poleceniem aws ecs describe-tasks --query 'tasks[0].containers[*].{name:name,exitCode:exitCode,reason:reason}' i przejrzyj logi CloudWatch z okna tuż przed zatrzymaniem.

Co oznacza „Essential container in task exited" z exit code 1?

Exit code 1 to ogólna awaria aplikacji: proces w kontenerze rzucił nieobsłużony wyjątek albo zwrócił niezerowy status przy starcie. Na ECS Fargate wskazuje to niemal zawsze na samą aplikację, a nie na platformę - brakującą lub błędną zmienną środowiskową, nieudane połączenie z bazą danych przy starcie, zły plik konfiguracyjny albo niewychwycony błąd w entrypoincie. Przejrzyj ostatnie 50 linii logu kontenera poleceniem aws logs tail /ecs/my-service --since 30m --format short, aby zobaczyć rzeczywisty stack trace, a potem sprawdź, czy wszystkie wymagane zmienne środowiskowe są obecne w task definition. Exit code 0 z tym samym komunikatem oznacza coś przeciwnego: proces dobiegł końca i zakończył się poprawnie, ale task definition oczekuje długo działającego serwisu, więc popraw polecenie tak, aby proces pozostał na pierwszym planie.

Jak odróżnić OOMKill od zwykłego zakończenia kontenera essential?

Przeczytaj pole stoppedReason na zatrzymanym tasku. Zabicie z powodu braku pamięci raportuje „OutOfMemoryError: Container killed due to memory usage", a exit code kontenera to zwykle 137 (128 + SIGKILL), bo Fargate natychmiast ubija proces bez graceful shutdown. Samo „Essential container in task exited" bez wzmianki o OOM to zakończenie na poziomie aplikacji, a o jego rodzaju mówi exit code - 1 przy awarii, 0 przy czystym zakończeniu, którego task nie oczekiwał. Jeśli widzisz 137, podnieś twardy limit pamięci do około 1.5x zaobserwowanego szczytu zamiast grzebać w kodzie aplikacji; jeśli widzisz 1, naprawa leży w aplikacji lub jej środowisku, a nie w limicie pamięci.

Dlaczego task ECS Fargate kończy się błędem CannotPullContainerError?

Fargate nie zdołał pobrać obrazu, zanim kontener w ogóle wystartował, więc task nigdy nie osiągnął stanu running. Trzy typowe przyczyny to task execution role bez uprawnień ecr:GetDownloadUrlForLayer i ecr:BatchGetImage, tag obrazu, który nie istnieje w rejestrze, albo task w prywatnych podsieciach bez trasy do ECR - bez NAT Gateway i bez VPC endpointów dla ecr.dkr, ecr.api oraz S3. Sprawdź, czy obraz istnieje, poleceniem aws ecr describe-images, zasymuluj uprawnienia roli przez aws iam simulate-principal-policy i potwierdź ścieżkę sieciową poleceniem aws ec2 describe-vpc-endpoints. W odróżnieniu od zakończenia kontenera essential, ta awaria zdarza się na etapie pobierania obrazu, a nie w trakcie działania.
Każdy zatrzymany task oznacza degradację usługi dla użytkowników. ECS w ciszy zastępuje wadliwe taski, co maskuje problem: serwis wygląda na „działający", podczas gdy użytkownicy doświadczają sporadycznych błędów 502 i timeoutów. Bez prawidłowych health checków i alertów na zdarzenia zatrzymania tasków, takie awarie mogą trwać dniami, zanim ktokolwiek zauważy wzorzec.

 

Jerzy Kopaczewski

Taski ECS padają na produkcji?

Umów bezpłatną 30-minutową rozmowę. Przejrzymy task definitions i konfigurację health checków, aby ustabilizować Twoje serwisy.

Umów rozmowę