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

Brève description

Les erreurs suivantes peuvent entraîner l'échec d'un appel d'API Amazon ECS :

• « AccessDeniedException »
• « ClientException »
• « ExceptionClusterNotFound »
• « InvalidParameterException »
• « ServerException »
• « ServiceNotActiveException »
• « PlatformTaskDefinitionIncompatibilityException »
• « PlatformUnknownException »
• « ServiceNotFoundException »
• « UnsupportedFeatureException »

Les applications qui s'exécutent dans vos tâches Amazon ECS peuvent également entraîner l'échec de votre appel d'API Amazon ECS.

Résolution

Remarque : si des erreurs surviennent lorsque vous exécutez des commandes de l’interface de la ligne de commande AWS (AWS CLI), consultez la page Résoudre les erreurs liées à AWS CLI. Vérifiez également que vous utilisez bien la version la plus récente de l'AWS CLI.

Localiser une erreur d'appel d'API

Lorsqu'une activité se produit dans Amazon ECS, AWS CloudTrail enregistre votre demande d'API en tant qu'événement dans l'historique des événements.

Pour consulter l'historique des événements AWS CloudTrail et localiser l'erreur d'API, procédez comme suit :

1. Ouvrez la console CloudTrail.
2. Dans le volet de navigation, choisissez Historique des événements.
3. Sélectionnez l'icône d’engrenage.
4. Sous Sélectionner les colonnes visibles, choisissez Code d'erreur. Puis, choisissez Confirmer.
5. Sur la page Historique des événements, dans Attributs de recherche, choisissez Nom de l'événement.
6. Dans Saisissez un nom d'événement, saisissez l'action qui a échoué.
   Remarque : si vous ne connaissez pas le nom de l'événement, rendez-vous sur la page Historique de l'événement. Dans Attributs de recherche, choisissez Source de l'événement. Dans Entrer une source d'événement, sélectionnez ecs.amazonaws.com pour filtrer tous les événements liés à votre service ECS.
7. Dans la liste des résultats, sélectionnez les événements comportant des codes d'erreur sur lesquels vous souhaitez en savoir plus.

Remarque : vous pouvez également utiliser Amazon Athena pour interroger les journaux CloudTrail à la recherche d'événements par code d'erreur.

Résoudre une erreur d'appel d'API

Effectuez les actions suivantes en fonction du code d'erreur que vous recevez.

AccessDeniedException

Si votre utilisateur ou votre rôle Gestion des identités et des accès AWS (AWS IAM) ne dispose pas des autorisations requises, le message d'erreur « AccessDeniedException » s'affiche. L'exemple d'erreur suivant indique que l'utilisateur arn:aws:sts::123456789012:assumed-role/test-role/test-session ne dispose pas des autorisations nécessaires pour exécuter l'action CreateCluster.

« 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: CreateCluster on resource: * because no identity-based policy allows the ecs:CreateCluster action »

Pour ajouter l'autorisation appropriée à la politique d'autorisation de l'identité IAM, procédez comme suit :

1. Ouvrez la console IAM.
2. Dans le volet de navigation, choisissez Rôles, Groupes d'utilisateurs ou Utilisateurs en fonction de l'identité IAM.
3. Utilisez le filtre de recherche pour filtrer les options de rôle ou d'utilisateur. Puis, sélectionnez l'identité IAM que vous souhaitez afficher.
4. Choisissez l’onglet Autorisations.
5. Pour afficher les autorisations associées à l'identité IAM, développez la politique d'autorisations.
6. Dans la politique d'autorisations, ajoutez ecs:your-event-name à la liste Actions. Puis, sélectionnez Autoriser dans Effet. Vous pouvez également créer une nouvelle politique qui autorise ecs:your-event-name et associer la politique au rôle ou à l'utilisateur IAM. Pour plus d'informations, consultez la section Modification des politiques gérées par le client (console).

Vous pouvez utiliser le simulateur de politique IAM pour tester une politique qui n'est pas associée à un utilisateur, un groupe d'utilisateurs ou un rôle IAM.

ClientException

Si votre client ECS spécifie un identifiant ou une ressource qui n'est pas valide ou n'existe pas, une erreur « ClientException » s’affiche. L'exemple d'erreur suivant indique que la commande RunTask fait référence à une TaskDefinition non valide :

« An error occurred (ClientException) when calling the RunTask operation: TaskDefinition not found. »

Vérifiez que vous faites référence aux ressources appropriées dans la commande, les appels d'API et votre code.

ClusterNotFoundException

Si Amazon ECS ne trouve pas le cluster que vous avez spécifié pour une opération, le message d'erreur « ClusterNotFoundException » s'affiche. L'exemple d'erreur suivant indique qu'Amazon ECS ne trouve pas le cluster que vous avez spécifié pour l'opération StartTask :

« An error occurred (ClusterNotFoundException) when calling the StartTask operation: Cluster not found. »

Vérifiez que vous faites référence au nom de cluster correct dans la commande, les appels d'API et votre code.

Pour répertorier tous vos clusters ECS actuels, exécutez la commande list-clusters de l’AWS CLI :

aws ecs list-clusters --region example_region

Remarque : remplacez example_region par votre région AWS.

Puis, vérifiez que le cluster auquel vous faites référence dans l'appel d'API existe.

InvalidParameterException

Si un paramètre que vous entrez dans une commande n'est pas valide et que la version de la définition de tâche n'existe pas, le message d'erreur suivant s'affiche :

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

L'exemple de commande RunTask suivant indique que la définition de tâche CentOS:3 n'existe pas :

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

Remarque : Dans l'exemple précédent, remplacez example_cluster par le nom de votre cluster.

L'exemple d'erreur suivant correspond à la commande RunTask précédente :

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

Vérifiez que les paramètres de votre commande sont valides.

ServerException

Si un serveur est en panne lorsque vous effectuez un appel d'API, le message d'erreur « ServerException » s'affiche. Si vous recevez cette erreur pour tous les appels d'API, cela signifie que le service AWS n'est pas disponible.

Les erreurs ServerException Sont souvent temporaires. Patientez, puis relancez l'appel d'API. Si le problème persiste, contactez AWS Support et fournissez les informations suivantes :

• Indiquez l'horodatage qui correspond à l'erreur.
• Si vous utilisez la ligne de commande, saisissez la commande qui renvoie l'erreur.
• Si vous utilisez un langage de programmation ou une infrastructure comme outils de code utilisant le SDK AWS, indiquez le bloc de code qui renvoie l'erreur.
• Si vous utilisez la console de gestion AWS, indiquez l'URL de la page Console de gestion AWS et l'action qui renvoie l'erreur.

ServiceNotActiveException

Si vous mettez à jour un service Amazon ECS inactif, le message d'erreur « ServiceNotActiveException » s'affiche. Vérifiez que le service ECS que vous souhaitez mettre à jour se trouve dans votre cluster ECS et qu'il est à l'état ACTIF.

Pour répertorier tous les services d'un cluster, exécutez la commande list-clusters de l'AWS CLI :

aws ecs list-services --cluster example_cluster

Remarque : remplacez example_cluster par le nom de votre cluster.

Vérifiez que la sortie de la commande contient le service que vous souhaitez mettre à jour. Exécutez ensuite la commande describe-services pour vérifier que le service est à l'état ACTIF :

aws ecs describe-services --services example_service_name --cluster example_cluster

Remarque : remplacez example_service_name et example_cluster par vos valeurs.

L'exemple de sortie suivant indique que le example-service est à l'état ACTIF :

{    "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",  
        ......  
    }]  
}

Si votre service n'est pas à l'état ACTIF, vérifiez que la valeur Nombre de tâches de votre service Amazon ECS est supérieure à zéro. Vous pouvez également exécuter la commande update-service de l’’AWS CLI pour mettre à jour la valeur de votre Nombre de tâches à 1 :

aws ecs update-service --cluster example_cluster_name --service example_service_name --desired-count 1

Remarque : remplacez les example_cluster_name et example_service_name par vos valeurs. Vous pouvez définir la valeur de comptage souhaitée sur un nombre supérieur à zéro.

Puis, dans la console ECS, vérifiez que l'état de votre définition de tâche est ACTIF. Vous pouvez également exécuter la commande describe-task-definition :

aws ecs describe-task-definition --task-definition example_taskdefinition

Remarque : remplacez example_taskdefinition par votre définition de tâche.

Consultez vos journaux CloudWatch pour détecter les échecs de service ou les évaluations de réseau qui correspondent à votre erreur ServiceNotActiveException.

PlatformTaskDefinitionIncompatibilityException

Si vous lancez une tâche sur une plateforme qui ne répond pas aux fonctionnalités requises de la définition de tâche, le message d'erreur « PlatformTaskDefinitionIncompatibilityException » s'affiche. Dans l'exemple d'erreur suivant, la version 1.3.0 de la plateforme ne prend pas en charge les exigences de la commande create-service de l’AWS CLI :

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

L'exemple de commande create-service suivant crée un service avec un volume Amazon Elastic File System (Amazon EFS) attaché à la version de plateforme 1.3.0 :

aws ecs create-service \  
    --cluster example_cluster \  
    --task-definition  example_taskdefinition  \  
    --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

Vérifiez que la version de votre plateforme AWS Fargate prend en charge les fonctionnalités requises par votre définition de tâche.

PlatformUnknownException

Si vous spécifiez une version de plateforme inconnue ou incorrecte lorsque vous lancez une tâche, le message d'erreur « PlatformUnknownException » s'affiche. L'exemple d'erreur suivant indique que la version de plateforme que vous spécifiez lors d'une opération de création de service n'est pas correcte :

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

L'exemple de commande create-service suivant contient la version de plateforme incorrecte 1.3 au lieu de la version correcte 1.3.0 :

aws ecs create-service \    --cluster example_cluster\  
    --task-definition example_taskdefinition \  
    --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

Vérifiez que la version de plateforme spécifiée lorsque vous lancez une tâche est correcte. Pour plus d'informations, consultez les sections Versions de la plateforme Fargate Linux pour Amazon ECS et Versions de la plateforme Fargate Windows pour Amazon ECS.

ServiceNotFoundException

L'erreur « ServiceNotFoundException » se produit lorsque le service ECS spécifié n'existe pas dans votre commande ou votre code. Vérifiez que le nom du service dans votre commande ou votre code est correct, puis confirmez que le service se trouve dans le cluster. Pour afficher tous les services du cluster, exécutez la commande list-clusters de l'AWS CLI :

aws ecs list-services --cluster example_cluster

Remarque : remplacez example_cluster par le nom de votre cluster.

UnsupportedFeatureException

L'erreur « UnsupportedFeatureException » se produit lorsque vous lancez une tâche Fargate dans une région AWS où Fargate ne prend pas en charge votre conteneur. Pour plus d'informations, consultez la section Régions prises en charge pour Amazon ECS sur AWS Fargate.

Résoudre les problèmes d'API dans les applications

Vous pouvez recevoir les réponses de code d'état HTTP 5## courantes suivantes lorsque vous accédez à l'application hébergée dans une tâche ECS :

• Une erreur « HTTP 500 - Internal server » se produit si une application détecte une condition inattendue, telle qu'une erreur. Ou, si vous configurez incorrectement une application, cette erreur s'affiche.
• Une erreur « HTTP 503 - Service unavailable » se produit si une tâche ECS subit une charge de travail importante. Ou, si l'application de votre tâche est en panne pour cause de maintenance, cette erreur s'affiche.

Consultez les journaux d'application relatifs à vos tâches ECS dans Amazon CloudWatch Logs. Chaque définition de tâche correspond à un flux de journaux qui contient le journal d'application de la tâche. Pour afficher des informations sur le groupe de journaux et le flux de journaux de votre définition de tâche, exécutez la commande describe-task-definition :

aws ecs describe-task-definition --task-definition example_taskdefinition

Remarque : remplacez example_task_definition par votre définition de tâche.

Informations connexes

Motifs de l’échec de l'API Amazon ECS