Come posso risolvere i problemi relativi a un agente Amazon ECS disconnesso?

Breve descrizione

È possibile che in fase di funzionamento l'agente di container Amazon ECS si disconnetta e si riconnetta più volte nell'arco di un'ora.Eventi di modifica che durano solo pochi minuti sono normali e non sono necessariamente indicativi di problemi dell'agente di container o dell'istanza di container.

Tuttavia, se l'agente di container rimane disconnesso più a lungo, l'istanza di container non può funzionare nell’ambito del cluster Amazon ECS. Questo problema potrebbe essere causato da uno dei seguenti motivi:

• Problemi di rete impediscono la comunicazione tra l'istanza e Amazon ECS.
• L'agente di container non ha le autorizzazioni AWS Identity and Access Management (AWS IAM) necessarie per comunicare con gli endpoint di Amazon ECS.
• Sono presenti problemi con l'host o il daemon Docker all'interno dell'istanza di container.
• È presente un conflitto di risorse nell'host sottostante.

È consigliabile utilizzare la versione più recente dell'agente di container Amazon ECS.

Risoluzione

Nota: la seguente risoluzione si applica alle AMI Amazon Linux 2023 ottimizzate per Amazon ECS.

Puoi utilizzare le chiavi SSH per collegarti alle istanze Amazon EC2. Se non hai generato le chiavi SSH, puoi utilizzare Gestione sessione, una funzionalità di AWS Systems Manager, per collegarti all'istanza. Per impostazione predefinita, l'Agente Systems Manager è installato nelle AMI Amazon Linux 2023 e nelle AMI Amazon Linux 2023 di base ottimizzate per ECS.

Verifica che l'agente di container sia in esecuzione nell'istanza di container

Per verificare lo stato e la connettività dell'agente di container Amazon ECS, esegui uno di questi comandi nell'istanza di container:

sudo systemctl status ecs

sudo docker ps -f name=ecs-agent

L'output specifica active (attivo) ed è simile al seguente:

ecs.service - Amazon Elastic Container Service - container agent
        Loaded: loaded (/usr/lib/systemd/system/ecs.service; enabled; preset: disabled)
        Active: active (running) since Thu 2026-02-19 08:42:39 UTC; 1min 17s ago
          Docs: https://aws.amazon.com/documentation/ecs/
     Main PID: 2578 (amazon-ecs-init)
        Tasks: 5 (limit: 9497)
       Memory: 136.5M
          CPU: 214ms
       CGroup: /system.slice/ecs.service
               └─2578 /usr/libexec/amazon-ecs-init start
CONTAINER ID  IMAGE                           COMMAND   CREATED         STATUS
8ab4e7c372d7  amazon/amazon-ecs-agent:latest  "/agent"  2 minutes ago   Up 2 minutes (healthy)

Se il problema è causato da un agente disconnesso, esegui questo comando per riavviare l'agente ECS:

sudo systemctl restart ecs

Nota: non viene restituito alcun output dopo aver eseguito il comando precedente.

Per verificare che l'agente sia in esecuzione, utilizza questo comando:

sudo systemctl status ecs

Verifica che il servizio Docker sia in esecuzione nell'istanza di container

Per verificare che il servizio Docker sia in esecuzione nell'istanza di container interessata, utilizza questo comando:

sudo systemctl status docker

L'output specifica active (attivo) ed è simile al seguente:

docker.service - Docker Application Container Engine
        Loaded: loaded (/usr/lib/systemd/system/docker.service; disabled; preset: disabled)
        Active: active (running) since Thu 2026-02-19 08:42:37 UTC; 3min 46s ago
   TriggeredBy: docker.socket
          Docs: https://docs.docker.com
     Main PID: 2314 (dockerd)
        Tasks: 13
       Memory: 485.3M
          CPU: 4.846s
       CGroup: /system.slice/docker.service
               └─2314 /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock --default-ulimit nofile=32768:65536

Se il servizio Docker è inattivo, esegui questo comando per riavviarlo:

sudo systemctl restart docker

Nota: non viene restituito alcun output dopo aver eseguito il comando precedente.

Per verificare che il servizio Docker sia stato riavviato, esegui questo comando:

sudo systemctl status docker

Esamina i file di log per l'agente di container e per Docker

Se l'istanza di container è ancora disconnessa, rivedi i file di log dell'host del container per l'agente di container e per Docker.

Controlla nei seguenti file di log la presenza di parole chiave come "error", "warn" o "agent transition state":

• Visualizza i log più recenti dell'agente di container Amazon ECS in /var/log/ecs/ecs-agent.log. Puoi visualizzare il log ruotato filtrando in /var/log/ecs/ecs-agent-log.timestamp
• Visualizza il log di avvio di Amazon ECS in /var/log/ecs/ecs-init.log
• Visualizza i log di esecuzione dei dati utente in /var/log/ecs/ecs-init.log
• Visualizza i log del daemon Docker con il comando sudo journalctl -u docker

Se utilizzi Linux, puoi anche rivedere il codice di uscita per ulteriori informazioni sul container dell'agente arrestato.

Per ottenere il codice di uscita, esegui questo comando:

docker inspect <your container ID>

Nota: sostituisci your container ID con l'ID del container arrestato.

Puoi utilizzare il programma di raccolta di log di Amazon ECS per raccogliere i log generali del sistema operativo, i log di Docker e i log dell'agente di container per Amazon ECS.

Verifica che il profilo dell'istanza IAM abbia le autorizzazioni necessarie

Se l'agente di container è ancora disconnesso, verifica che il profilo dell'istanza IAM associato all'istanza di container abbia le autorizzazioni IAM necessarie:

1. Utilizza SSH o Gestione sessione per connetterti all'istanza.

2. Per visualizzare i metadati dell'istanza nel profilo dell'istanza associato all'istanza, esegui questo comando:

   TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
   curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/iam/info

   L'output è simile al seguente:

   {
      "Code" : "Success",
      "LastUpdated" : "2026-02-19T08:42:14Z",
      "InstanceProfileArn" : "arn:aws:iam::1122334455:instance-profile/ecsInstanceRole",
      "InstanceProfileId" : "AIPA4VIZXOFF55F72XIZN"
   }

3. Verifica che il ruolo IAM abbia le autorizzazioni corrette per le istanze di container.

4. Per verificare errori di credenziali specifici, esegui questo comando per controllare il log dell'agente di container:

   cat /var/log/ecs/ecs-agent.log.YYYY-MM-DD-##

   Nota: sostituisci YYYY-MM-DD-## con il timestamp corrispondente.

   Il log dell'agente di container viene ruotato ogni ora. Il suffisso cambia automaticamente per riflettere la data e l'ora correnti. Aggiorna il comando per includere l'intervallo di date e l'ID del log relativi al momento in cui si è verificato il problema.

Verifica che l'istanza di container disponga di risorse sufficienti per eseguire l'agente ECS

Se le attività hanno un utilizzo elevato di memoria o CPU, l'istanza di container potrebbe non disporre di risorse sufficienti per eseguire l'agente ECS.

L'agente di container Amazon ECS utilizza la funzione ReadMemInfo() di Docker per eseguire query sulla quantità di memoria disponibile per il sistema operativo.

Esegui questo comando nell'istanza di container per visualizzare la memoria totale riconosciuta dal sistema operativo:

free -b

Esempio di output per un'istanza t2.large che esegue l'AMI Amazon Linux 2023 ottimizzata per Amazon ECS:

               total        used        free      shared  buff/cache   available
Mem:     8327938048   337494016  6402355200      557056  1588088832  7745118208
Swap:             0           0           0

Puoi scegliere di riservare memoria per l'agente di container Amazon ECS e altri processi di sistema critici nelle istanze di container. L'allocazione di memoria aiuta a garantire che i container dell'attività non si contendano la stessa memoria. Per ulteriori informazioni, consulta Allocazione della memoria di un'istanza di container Amazon ECS Linux.

Verifica che la variabile di ambiente ECS_CLUSTER abbia il nome del cluster corretto

Se il parametro di configurazione dell'agente di container Amazon ECS ECS_CLUSTER ha il nome del cluster errato, l'istanza di container non può unirsi al cluster. Per controllare il contenuto del file /etc/ecs/ecs.config e verificare il parametro, esegui questo comando:

cat /etc/ecs/ecs.config

Verifica che l'agente ECS sia in grado di comunicare con gli endpoint di ECS

Per connetterti con gli endpoint di ECS, le liste di controllo degli accessi alla rete e il gruppo di sicurezza delle istanze di container devono consentire le connessioni in uscita sulla porta 443 (HTTPS).

Se l'istanza di container si trova in una sottorete pubblica, verifica che l'istanza abbia un indirizzo IP pubblico e che la tabella di routing della sottorete abbia una route verso un gateway Internet.

Se l'istanza di container si trova in una sottorete privata, verifica che la tabella di routing della sottorete abbia una route verso un gateway NAT o che tu abbia configurato gli endpoint VPC per Amazon ECS.

Per controllare le connessioni in uscita agli endpoint di ECS (ACS/TCS), esegui uno di questi comandi nell'istanza di container:

sudo yum install telnet -y
telnet ecs.REGION.amazonaws.com 443

oppure

curl https://ecs.REGION.amazonaws.com

Nota: sostituisci REGION con la tua Regione AWS.

Applica le seguenti best practice:

• A meno che l'applicazione non richieda un sistema operativo specifico o una versione Docker non disponibile nell'AMI ottimizzata per Amazon ECS, utilizza le AMI Linux ottimizzate per Amazon ECS per eseguire i carichi di lavoro ECS.
• Utilizza la versione più recente dell'agente di container Amazon ECS. L'ultima versione include funzionalità avanzate e fornisce aggiornamenti importanti.
• Configura le attività con limiti di CPU e memoria.

Informazioni correlate

Risoluzione dei problemi legati ad Amazon ECS

Ruolo IAM delle istanze di container Amazon ECS

Visualizzare i log dell'agente di container Amazon ECS