Comment résoudre les erreurs courantes relatives aux appels d'API dans Amazon ECS ?

Brève description

Les API d'Amazon ECS peuvent échouer avec l'une des erreurs suivantes :

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

Vous pouvez également rencontrer des problèmes d'API avec l'application qui s'exécute à l'intérieur de vos tâches Amazon ECS.

Solution

Vos demandes d'API sont enregistrées dans AWS CloudTrail en tant qu'événements. Lorsqu'une activité se produit dans Amazon ECS, cette activité est enregistrée dans un événement CloudTrail avec d'autres événements de service AWS dans Event history (Historique des événements). Vous pouvez afficher, rechercher et télécharger les événements récents dans votre compte AWS.

Pour afficher l'historique des événements CloudTrail et localiser les erreurs d'API, procédez comme suit :

1. Ouvrez la console AWS CloudTrail.
2. Dans le panneau de navigation, sélectionnez Event history (Historique des événements).
3. Sélectionnez l'icône représentant une roue dentée.
4. Sous Select visible columns (Sélectionner les colonnes visibles), sélectionnez Error code (Code d'erreur).
5. Sélectionnez Confirm (Confirmer).
6. Dans la page Event history (Historique des événements), pour Lookup attributes (Attributs de recherche), sélectionnez Event name (Nom de l'événement).
7. Pour Enter an event name (Saisir le nom d'un événement), saisissez l'action qui a échoué
   Remarque : si vous ne connaissez pas le nom de l'événement, procédez comme suit :
   Pour Lookup attributes (Attributs de recherche), sélectionnez Event source (Source de l'événement).
   Pour Enter an event source (Saisir une source d'événement), sélectionnez ecs.amazonaws.com pour filtrer tous les événements relatifs à votre service ECS.
8. À partir de la liste des résultats, sélectionnez les événements avec les codes d'erreur de votre choix pour afficher les détails de l'événement.

AccessDeniedException

Cette erreur est journalisée lorsque l'utilisateur ou le rôle AWS Identity and Access Management (IAM) à l'origine de l'appel d'API ne dispose pas des autorisations requises pour effectuer l'action demandée.

L'erreur AccessDeniedException est similaire à ce qui suit :

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

Vous pouvez afficher les détails suivants dans l'historique des événements CloudTrail associé :

• Informations sur l'utilisateur :

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

• Nom de l'événement :

"eventName": "CreateCluster"

• Message d'erreur :

"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"

Pour tester une politique qui n'est pas attachée à un utilisateur, un groupe d'utilisateurs ou un rôle, utilisez le simulateur de politiques IAM.

Pour résoudre cette erreur, procédez comme suit :

1. Ouvrez la console IAM.
2. Dans le panneau de navigation, sélectionnez Roles (Rôles) ou Users (Utilisateurs) en fonction de l'identité de l'utilisateur.
3. Filtrez le rôle ou l'utilisateur à l'aide du filtre de recherche.
4. Sélectionnez le rôle ou l'utilisateur.
5. Sélectionnez l'onglet Permissions (Autorisations).
6. Développez la politique d'autorisation pour afficher les autorisations associées à l'utilisateur.
7. Assurez-vous que la politique inclut ecs:your-event-name dans la liste Actions et cochez Allow (Autoriser) for Effect (Effet). Si la politique n'inclut pas ces paramètres, mettez-la à jour afin d'inclure ces modifications. Vous pouvez également créer une nouvelle politique autorisant l'action mentionnée puis attacher la politique au rôle ou à l'utilisateur IAM. Pour plus d'informations, référez-vous à la section Editing customer managed policies (console) (Modification des politiques gérées par le client (console)).

ClientException

Cette erreur est journalisée lorsque le client ECS spécifie un identifiant ou une ressource qui n'est pas valide ou qui n'existe pas. Par exemple, si vous essayez de démarrer une tâche à l'aide de l'API RunTask ou StartTask et que vous vous référez à une définition de tâche incorrecte, vous obtenez l'erreur suivante :

$ 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.

Pour éviter cette erreur, assurez-vous que les ressources référencées dans la commande, votre code ou les appels d'API existent et sont valides.

ClusterNotFoundException

Cette erreur est journalisée lorsque le cluster spécifié est introuvable.

Exemple :

$ 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.

Pour éviter cette erreur, assurez-vous que le nom du cluster que vous transmettez à la commande, votre code ou les appels d'API sont corrects. Vous pouvez exécuter la commande suivante pour répertorier les clusters ECS existants. À l'aide de la liste renvoyée, vous pouvez vérifier que le cluster mentionné dans l'appel d'API existe.

$ 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

Cette erreur est journalisée lorsque le paramètre transmis à la commande n'est pas valide. Supposons que vous ayez mentionné une version de la définition de tâche qui n'existe pas :

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

Ensuite, l'erreur est similaire à ce qui suit :

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

Pour éviter cette erreur, assurez-vous que les paramètres transmis à la commande sont valides.

ServerException

Cette erreur est journalisée en cas d'erreur de serveur relative à l'appel d'API. L'erreur ServerException est généralement due au code d'erreur HTTP 500. Cette exception se produit en cas de problème avec le service ECS dans la région AWS. Cette erreur est généralement temporaire et les tentatives ultérieures d'exécution de l'API devraient réussir. Toutefois, si le problème persiste longtemps, contactez AWS Support.

ServiceNotActiveException

Cette erreur se produit lorsque le service ECS en cours de mise à jour n'est pas actif. Vérifiez que le service ECS en cours de mise à jour est présent dans le cluster ECS et qu'il est actif.

Exécutez la commande AWS Command Line Interface (AWS CLI) suivante pour répertorier tous les services du cluster :

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

Dans la sortie, vérifiez si le service en cours de mise à jour est affiché.

Remarque : si vous recevez des erreurs lors de l'exécution des commandes AWS CLI, assurez-vous que vous utilisez la version AWS CLI la plus récente.

Exécutez ensuite la commande suivante pour vérifier que le service est actif.

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

La sortie peut ressembler à ce qui suit :

{
    "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

Cette erreur se produit lorsqu'une tâche est lancée sur une plateforme qui ne répond pas aux fonctionnalités requises dans la définition de tâche. Supposons que vous essayez de créer un service avec un volume Amazon EFS attaché à la version 1.3.0 de la plateforme :

$ 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

Puis, vous obtenez l'erreur suivante :

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

Pour résoudre ce problème, assurez-vous d'utiliser la version de la plateforme qui prend en charge les exigences de capacité de la définition de tâche. Pour plus d'informations sur les fonctionnalités prises en charge par les différentes versions de plateforme, référez-vous à la section AWS Fargate platform versions (Versions de la plateforme AWS Fargate).

PlatformUnknownException

Cette erreur se produit si vous spécifiez une version de plateforme inconnue ou incorrecte lorsque vous lancez une tâche. Supposons que vous fournissiez une version de plateforme incorrecte : la version 1.3 au lieu de la version 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

Puis, vous obtenez l'erreur suivante :

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

Pour plus d'informations, référez-vous aux sections Linux platform versions (Versions de la plateforme Linux) et Windows platform versions (Versions de la plateforme Windows).

ServiceNotFoundException

Cette erreur se produit lorsque le service ECS spécifié dans votre commande ou votre code n'existe pas. Vérifiez que le nom du service dans votre commande ou votre code est correct et que le service est présent dans le cluster.

Pour afficher tous les services du cluster, exécutez la commande suivante :

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

UnsupportedFeatureException

Cette erreur se produit lorsqu'une fonction ECS n'est pas disponible dans une région spécifique. Par exemple, la fonction AWS Fargate peut ne pas être immédiatement disponible dans une région nouvellement lancée. Si une tâche Fargate est lancée dans cette région, l'erreur UnsupportedFeatureException s'affiche.

Problèmes d'API d'application

Voici quelques-unes des erreurs HTTP 5xx les plus courantes que vous pouvez rencontrer lorsque vous accédez à l'application hébergée dans une tâche ECS :

500 - Internal Server Error (Erreur interne du serveur) : cette erreur s'affiche lorsque l'application rencontre une situation inattendue. Cette erreur peut se produire en raison d'une mauvaise configuration de l'application ou d'une erreur au niveau de l'application.

503 - Service Unavailable (Service indisponible) : cette erreur s'affiche dans les conditions suivantes :

• La tâche ECS subit une charge de travail importante et ne peut pas répondre à la demande.
• L'application exécutée dans votre tâche est hors service pour cause de maintenance.

Pour résoudre ces erreurs, procédez comme suit :

Analysez les journaux d'application des tâches ECS dans Amazon CloudWatch Logs. Vous pouvez trouver des informations sur le groupe de journaux dans la définition de tâche. Chaque tâche est associée à un long flux individuel qui contient les journaux d'application de la tâche.

Pour afficher le groupe de journaux et le flux de journaux de votre tâche, exécutez la commande suivante :

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

La sortie doit être similaire à ce qui suit :

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

---

Informations connexes

Raisons de l'échec de l'API