¿Cómo soluciono los errores comunes de las llamadas a la API en Amazon ECS?

Descripción corta

Las API de Amazon ECS pueden fallar con uno de los siguientes errores:

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

También puede experimentar problemas de API con la aplicación que se ejecuta dentro de sus tareas de Amazon ECS

Resolución

Sus solicitudes de API se registran en AWS CloudTrail como eventos. Cuando se produce una actividad en Amazon ECS, esa actividad se registra en un evento de CloudTrail junto con otros eventos de servicio de AWS en Event history (Historial de eventos). Puede ver, buscar y descargar eventos recientes en su cuenta de AWS.

Para ver el historial de eventos de CloudTrail y localizar los errores de la API, haga lo siguiente:

1. Abra la consola de AWS CloudTrail.
2. En el panel de navegación, elija Event history (Historial de eventos).
3. Elija el icono de engranaje.
4. En Select visible columns (Seleccionar columnas visibles), seleccione Error code (Código de error).
5. Seleccione Confirm (Confirmar).
6. En la página Event history (Historial de eventos), en Lookup attributes (Atributos de búsqueda), seleccione Event name (Nombre del evento).
7. En Enter an event name (Ingrese un nombre de evento), especifique la acción que falló.
   Nota: si no sabe el nombre del evento, haga lo siguiente:
   En Lookup attributes (Atributos de búsqueda), seleccione Event source (Origen del evento).
   En Enter an event source (Ingrese un origen de eventos), seleccione ecs.amazonaws.com para filtrar todos los eventos relacionados con su servicio ECS.
8. En la lista de resultados, elija los eventos con códigos de error de su elección para ver los detalles del evento.

AccessDeniedException

Este error se registra cuando el usuario o el rol de AWS Identity and Access Management (IAM) que realiza la llamada a la API no tiene los permisos necesarios para realizar la acción solicitada.

El error AccessDeniedException tiene un aspecto similar al siguiente:

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

Puede ver los siguientes detalles en el registro de eventos de CloudTrail relacionado:

• Información de usuario:

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

• Nombre del evento:

"eventName": "CreateCluster"

• Mensaje de error:

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

Para probar una política que no esté adjuntada a un usuario, grupo de usuarios o rol, use el simulador de políticas de IAM.

Para resolver este error, haga lo siguiente:

1. Abra la consola de IAM.
2. En el panel de navegación, elija Roles o Users (Usuarios) en función de la identidad del usuario.
3. Filtre el rol o el usuario mediante el filtro de búsqueda.
4. Elija el rol o el usuario.
5. Haga clic en la pestaña Permisos.
6. Amplíe la política de permisos para ver los permisos asociados al usuario.
7. Asegúrese de que la política incluya ecs:your-event-name en la lista Actions (Acciones) yAllow (Permitir) para Effect (Efecto). Si la política no incluye estos parámetros, actualice la política para que incluya estos cambios. O bien, cree una nueva política que permita la acción mencionada y adjunte la política al rol o al usuario de IAM. Para obtener más información, consulte Editing customer managed policies (console) (Edición de políticas administradas por el cliente [consola]).

ClientException

Este error se registra cuando el cliente de ECS especifica un identificador o recurso que no es válido o no existe. Por ejemplo, si intenta iniciar una tarea con la API RunTask o StartTask y hace referencia a una definición de tarea incorrecta, aparece este error:

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

Para evitar este error, asegúrese de que los recursos a los que se hace referencia en el comando, el código o las llamadas a la API existan y sean válidos.

ClusterNotFoundException

Este error se registra cuando no se encuentra el clúster especificado.

Ejemplo:

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

Para evitar este error, asegúrese de que el nombre del clúster que pasa en el comando, el código o las llamadas a la API sean correctos. Puede ejecutar el siguiente comando para enumerar los clústeres de ECS existentes. Con la lista que se devuelve, puede comprobar que existe el clúster mencionado en la llamada a la API.

$ 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

Este error se registra cuando el parámetro pasado en el comando no es válido. Supongamos que mencionó una versión de la definición de tarea que no existe:

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

Entonces, el error tendrá un aspecto similar al siguiente:

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

Para evitar este error, asegúrese de que los parámetros pasados en el comando sean válidos.

ServerException

Este error se registra cuando hay un error del servidor relacionado con la llamada a la API. ServerException suele deberse al código de error HTTP 500. Esta excepción se produce cuando hay un problema con el servicio ECS en la región de AWS. Este error suele ser temporal y los intentos posteriores de ejecutar la API deberían tener éxito. Sin embargo, si el problema persiste durante mucho tiempo, póngase en contacto con AWS Support.

ServiceNotActiveException

Este error se produce cuando el servicio ECS que se está actualizando no está activo. Compruebe que el servicio ECS que se está actualizando esté presente en el clúster de ECS y esté en estado activo.

Ejecute el siguiente comando de AWS Command Line Interface (AWS CLI) para enumerar todos los servicios del clúster:

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

En la salida, compruebe si se muestra el servicio que se está actualizando.

Nota: si recibe errores mientras ejecuta los comandos de AWS CLI, asegúrese de que está utilizando la versión más reciente de dicha interfaz.

A continuación, ejecute el siguiente comando para comprobar que el servicio se encuentra en estado activo.

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

El resultado puede ser similar al siguiente:

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

Este error se produce cuando se inicia una tarea en una plataforma que no cumple con las capacidades requeridas en la definición de la tarea. Supongamos que intenta crear un servicio con un volumen de Amazon EFS adjunto en la versión de plataforma 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

A continuación, aparece el siguiente error:

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

Para resolver este problema, asegúrese de utilizar la versión de plataforma que admita los requisitos de capacidad en la definición de la tarea. Para obtener información sobre las capacidades compatibles en las distintas versiones de la plataforma, consulte Versiones de la plataforma de AWS Fargate.

PlatformUnknownException

Este error se produce si especifica una versión de plataforma desconocida o incorrecta al iniciar una tarea. Supongamos que proporciona una versión de plataforma incorrecta 1.3 en lugar de la versión 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

A continuación, aparece el siguiente error:

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

Para obtener más información, consulte Versiones de la plataforma Linux y versiones de la plataforma Windows.

ServiceNotFoundException

Este error se produce cuando el servicio ECS que se especifica en el comando o el código no existe. Compruebe que el nombre del servicio en su comando o código sea correcto y que el servicio esté presente en el clúster.

Para ver todos los servicios del clúster, ejecute el siguiente comando:

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

UnsupportedFeatureException

Este error se produce cuando una característica de ECS no está disponible en una región específica. Por ejemplo, es posible que la característica de AWS Fargate no esté disponible de inmediato en una región recién lanzada. Si se inicia una tarea de Fargate en esta región, se obtiene el error UnsupportedFeatureException.

Problemas de API de aplicaciones

A continuación, se muestran algunos de los errores HTTP 5xx más comunes que puede obtener al acceder a la aplicación alojada dentro de una tarea de ECS:

500 - Internal Server Error (500 - Error de servidor interno): recibe este error cuando la aplicación encuentra una condición inesperada. Este error puede producirse debido a una configuración incorrecta de la aplicación o a un error con la aplicación.

503 - Service Unavailable (503 - Servicio no disponible): recibe este error en las siguientes condiciones:

• La tarea de ECS está experimentando una carga de trabajo pesada y no puede atender la solicitud.
• La aplicación que se ejecuta dentro de su tarea está fuera de servicio por mantenimiento.

Para solucionar estos errores, haga lo siguiente:

Analice los registros de aplicaciones para las tareas de ECS en Amazon CloudWatch Logs. Puede encontrar información sobre el grupo de registros en la definición de tareas. Cada tarea se asocia a una secuencia larga individual que contiene los registros de la aplicación de la tarea.

Para ver el grupo de registros y el flujo de registros de su tarea, ejecute el siguiente comando:

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

La salida es similar a la siguiente:

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

---

Información relacionada

Motivos de error de la API