Come posso risolvere gli errori comuni con le chiamate API in Amazon ECS?

Breve descrizione

Le API di Amazon ECS potrebbero riportare uno dei seguenti errori:

• AccessDeniedException
• ClientException
• ClusterNotFoundException
• InvalidParameterException
• ServerException
• ServiceNotActiveException
• PlatformTaskDefinitionIncompatibilityException
• PlatformUnknownException
• ServiceNotFoundException
• UnsupportedFeatureException

Potresti anche riscontrare problemi relative alle API con l'applicazione in esecuzione all'interno delle tue attività Amazon ECS

Risoluzione

Le tue richieste API vengono registrate in AWS CloudTrail come eventi. Quando si verifica un'attività in Amazon ECS, tale attività viene registrata in un evento CloudTrail insieme ad altri eventi del servizio AWS nella cronologia degli eventi. Puoi visualizzare, cercare e scaricare eventi recenti nel tuo account AWS.

Per visualizzare la cronologia degli eventi di CloudTrail e individuare gli errori delle API, procedi come segue:

1. Apri la console AWS CloudTrail.
2. Nel pennello di navigazione, scegli Event history (Cronologia eventi).
3. Scegli l'icona dell'ingranaggio.
4. In Select visible columns (Seleziona colonne visibili), seleziona Error code (Codice di errore).
5. Scegli Confirm (Conferma).
6. Nella pagina Event history (Cronologia eventi), per Lookup attributes (Attributi di ricerca), seleziona Event name (Nome evento).
7. Per Enter an event name (Inserisci il nome di un evento), inserisci l'azione non riuscita.
   Nota: se non conosci il nome dell'evento, procedi come segue:
   Per Lookup attributes (Attributi di ricerca), seleziona Event source (Origine evento).
   Per Enter an event source (Inserisci l'origine di un evento), seleziona ecs.amazonaws.com per filtrare tutti gli eventi correlati al servizio ECS.
8. Dall'elenco dei risultati, scegli gli eventi con codici di errore di tua scelta per visualizzare i dettagli dell'evento.

AccessDeniedException

Questo errore viene registrato quando l'utente o il ruolo di AWS Identity and Access Management (IAM) che effettua la chiamata API non dispone delle autorizzazioni necessarie per eseguire l'azione richiesta.

L'errore AccessDeniedException è simile al seguente:

An error occurred (AccessDeniedException) when calling the CreateCluster operation: User: arn:aws:sts::123456789012:assumed-role/test-role/test-session is not authorized to perform: ecs:CreateCluster on resource: * because no identity-based policy allows the ecs:CreateCluster action

Puoi visualizzare i seguenti dettagli nel relativo record di eventi di CloudTrail:

• Informazioni utente:

"type": "AssumedRole",
"principalId": "AROAZEPPWYLQU45ZDJY6V:test-session",
"arn": "arn:aws:sts::123456789012:assumed-role/test-role/test-session"

• Nome evento:

"eventName": "CreateCluster"

• Messaggio di errore:

"errorMessage": "User: arn:aws:sts::123456789012:assumed-role/test-role/test-session is not authorized to perform: ecs:CreateCluster on resource: * because no identity-based policy allows the ecs:CreateCluster action"

Per testare una policy che non è associata a un utente, a un gruppo di utenti o a un ruolo, utilizza il simulatore di policy IAM.

Per risolvere l'errore, procedi come segue:

1. Apri la console IAM.
2. Nel pannello di navigazione, scegli Roles (Ruoli) oUsers (Utenti) in base all'identità dell'utente.
3. Filtra il ruolo o l'utente utilizzando il filtro di ricerca.
4. Seleziona il ruolo o l'utente.
5. Scegli la scheda Permissions (Autorizzazioni).
6. Espandi la policy delle autorizzazioni per visualizzare le autorizzazioni associate all'utente.
7. Assicurati che la policy includa ecs:your-event-name nell'elenco Actions (Azioni) e Allow (Consenti) per Effect (Effetto). Se la policy non include questi parametri, aggiornala per includere queste modifiche. In alternativa, crea una nuova policy che consenta l'azione menzionata e allega la policy al ruolo o all'utente IAM. Per ulteriori informazioni, consulta Modifica delle policy gestite dal cliente (console).

ClientException

Questo errore viene registrato quando il client ECS specifica un identificatore o una risorsa che non è valida o non esiste. Ad esempio, se tenti di avviare un'attività utilizzando l'API RunTask o StartTask e fai riferimento a una definizione di attività errata, ricevi questo errore:

$ aws ecs run-task --cluster example-cluster --task-definition centos --region ap-southeast-2
An error occurred (ClientException) when calling the RunTask operation: TaskDefinition not found.

$ aws ecs start-task --cluster example-cluster --task-definition centos --container-instances 765936fadbdd46b5991a4bd70c2a43d4 --region ap-southeast-2
An error occurred (ClientException) when calling the StartTask operation: TaskDefinition not found.

Per evitare questo errore, assicurati che le risorse a cui fai riferimento nel comando, nel codice o nelle chiamate API esistano e siano valide.

ClusterNotFoundException

Questo errore viene registrato quando il cluster specificato non viene trovato.

Esempio:

$ aws ecs run-task --task-definition CentOS --cluster example-cluster --region ap-southeast-2
An error occurred (ClusterNotFoundException) when calling the StartTask operation: Cluster not found.

Per evitare questo errore, assicurati che il nome del cluster che passi nel comando, nel codice o nelle chiamate API sia corretto. Puoi eseguire il seguente comando per elencare i cluster ECS esistenti. Con l'elenco restituito, puoi verificare che il cluster menzionato nella chiamata API esista.

$ aws ecs list-clusters --region example-region
{
    "clusterArns": [
        "arn:aws:ecs:ap-southeast-2:123456789012:cluster/my-cluster",
        "arn:aws:ecs:ap-southeast-2:123456789012:cluster/my-private-cluster"
    ]
}

InvalidParameterException

Questo errore viene registrato quando il parametro passato nel comando non è valido. Supponiamo che tu abbia menzionato una versione della definizione dell'attività che non esiste:

$ aws ecs run-task --task-definition CentOS:3 --cluster example-cluster --region ap-southeast-2

Dovresti visualizzare un errore simile al seguente:

An error occurred (InvalidParameterException) when calling the RunTask operation: TaskDefinition not found.

Per evitare questo errore, assicurati che i parametri passati nel comando siano validi.

ServerException

Questo errore viene registrato quando si verifica un errore del server relativo alla chiamata API. ServerException è in genere causato dal codice di errore HTTP 500. Questa eccezione si presenta quando si verifica un problema con il servizio ECS nella Regione AWS. Questo errore è in genere temporaneo e i successivi tentativi di esecuzione dell'API dovrebbero avere esito positivo. Tuttavia, se il problema persiste per un lungo periodo di tempo, contatta AWS Support.

ServiceNotActiveException

Questo errore si verifica quando il servizio ECS che stai aggiornando non è attivo. Verifica che il servizio ECS che stai aggiornando sia presente nel cluster ECS e sia nello stato attivo.

Esegui il seguente comando AWS Command Line Interface (AWS CLI) per elencare tutti i servizi nel cluster:

$ aws ecs list-services --cluster example-cluster

Nell'output, verifica se viene visualizzato il servizio che stai aggiornando.

Nota: se ricevi un messaggio di errore durante l'esecuzione dei comandi AWS CLI, assicurati di utilizzare la versione più recente di AWS CLI.

Quindi, esegui il seguente comando per verificare che il servizio sia nello stato attivo.

$ aws ecs describe-services --services example-service-name --cluster example-cluster

L'output potrebbe essere simile al seguente:

{
    "services": [{
        "serviceArn": "arn:aws:ecs:ap-southeast-2:111122223333:service/my-cluster/example-service",
        "serviceName": "example-service",
        "clusterArn": "arn:aws:ecs:ap-southeast-2:111122223333:cluster/example-cluster",
        "loadBalancers": [],
        "serviceRegistries": [],
        "status": "ACTIVE",
        ......
    }]
}

PlatformTaskDefinitionIncompatibilityException

Questo errore si verifica quando un'attività viene avviata su una piattaforma che non soddisfa le funzionalità richieste nella definizione dell'attività. Supponiamo di provare a creare un servizio con un volume Amazon EFS collegato alla piattaforma versione 1.3.0:

$ aws ecs create-service \
    --cluster example-cluster \
    --task-definition Test-fargate-EFS \
    --launch-type FARGATE \
    --service-name example-service \
    --desired-count 1 \
    --network-configuration="awsvpcConfiguration={subnets=["subnet-ed7d31b5","subnet-833ef1cb"],securityGroups=["sg-eeb28aa1"]}" \
    --platform-version 1.3.0

Quindi, viene visualizzato il seguente errore:

An error occurred (PlatformTaskDefinitionIncompatibilityException) when calling the CreateService operation: One or more of the requested capabilities are not supported.

Per risolvere questo problema, assicurati di utilizzare la versione della piattaforma che supporta i requisiti di funzionalità nella definizione dell'attività. Per informazioni sulle funzionalità supportate nelle varie versioni della piattaforma, consulta Versioni della piattaforma AWS Fargate.

PlatformUnknownException

Questo errore si verifica se specifichi una versione della piattaforma sconosciuta o errata all'avvio di un'attività. Supponiamo di fornire una versione della piattaforma 1.3 errata anziché la versione 1.3.0:

$ aws ecs create-service \
    --cluster example-cluster\
    --task-definition example-task \
    --launch-type FARGATE\
    --enable-execute-command \
    --service-name example-service\
    --desired-count 1 \
    --network-configuration="awsvpcConfiguration={subnets=["subnet-ed7d31b5","subnet-833ef1cb"],securityGroups=["sg-eeb28aa1"]}"\
    --platform-version 1.3

Quindi, viene visualizzato il seguente errore:

An error occurred (PlatformUnknownException) when calling the CreateService operation: The specified platform does not exist.

Per maggiori informazioni, consulta Versioni della piattaforma Linux e Versioni della piattaforma Windows.

ServiceNotFoundException

Questo errore si verifica quando il servizio ECS specificato nel comando o nel codice non esiste. Verifica che il nome del servizio nel comando o nel codice sia corretto e che il servizio sia presente nel cluster.

Per visualizzare tutti i servizi nel cluster, esegui il seguente comando:

$ aws ecs list-services --cluster example-cluster

UnsupportedFeatureException

Questo errore si verifica quando una caratteristica di ECS non è disponibile in una Regione specifica. Ad esempio, la caratteristica AWS Fargate potrebbe non essere immediatamente disponibile in una Regione avviata di recente. Se in questa Regione viene avviata un'attività Fargate, viene visualizzato l'errore UnsupportedFeatureException.

Problemi relativi all'API dell'applicazione

Di seguito sono riportati alcuni degli errori HTTP 5xx più comuni che possono verificarsi quando accedi all'applicazione ospitata all'interno di un'attività ECS:

500 - Errore interno del server: questo errore viene visualizzato quando l'applicazione rileva una condizione imprevista. Questo errore può verificarsi a causa di un'errata configurazione dell'applicazione o di un errore nell'applicazione.

503 - Servizio non disponibile: questo errore viene visualizzato nelle seguenti condizioni:

• L'attività ECS sta gestendo un carico di lavoro pesante e non è in grado di soddisfare la richiesta.
• L'applicazione in esecuzione all'interno dell'attività è inattiva per manutenzione.

Per risolvere questi errori, completa le seguenti operazioni:

Analizza i log delle applicazioni per le attività ECS in Amazon CloudWatch Logs. Puoi trovare informazioni sul gruppo di log nella definizione dell'attività. Ogni attività è associata a un singolo flusso di log che contiene i log di applicazione dell'attività.

Per visualizzare il gruppo di log e il flusso di log per l'attività, esegui il seguente comando:

$ aws ecs describe-task-definition —task-definition example-taskdefinition

Dovresti visualizzare un output simile al seguente:

...
                "logConfiguration": {
                    "logDriver": "awslogs",
                    "options": {
                        "awslogs-group": "/ecs/example-task",
                        "awslogs-region": "ap-southeast-2",
                        "awslogs-stream-prefix": "ecs"
                    }
                }
...

---

Informazioni correlate

Motivi di errore dell'API