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

Descripción corta

Los siguientes errores pueden provocar un error en una llamada a la API de Amazon ECS:

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

Las aplicaciones que se ejecutan dentro de tus tareas de Amazon ECS también pueden provocar un error en la llamada a la API de Amazon ECS.

Resolución

Nota: Si se muestran errores al ejecutar comandos de la Interfaz de la línea de comandos de AWS (AWS CLI), consulta Solución de errores de la AWS CLI. Además, asegúrate de utilizar la versión más reciente de la AWS CLI.

Localizar un error de llamada a la API

Cuando se produce actividad en Amazon ECS, AWS CloudTrail registra tu solicitud de API como un evento en el historial de eventos.

Para ver el historial de eventos de AWS CloudTrail y localizar el error de la API, sigue estos pasos:

1. Abre la consola de CloudTrail.
2. En el panel de navegación, selecciona Historial de eventos.
3. Selecciona el icono con forma de engranaje.
4. En Seleccionar columnas visibles, elige Código de error. A continuación, selecciona Confirmar.
5. En la página Historial de eventos, en Atributos de búsqueda, elige Nombre del evento.
6. En Introducir un nombre de evento, introduce la acción que ha fallado.
   Nota: Si no sabes el nombre del evento, ve a la página Historial de eventos. En Atributos de búsqueda, elige Origen del evento. En Introducir un origen de eventos, selecciona ecs.amazonaws.com para filtrar todos los eventos relacionados con tu servicio de ECS.
7. En la lista de resultados, selecciona los eventos con códigos de error sobre los que desees obtener más información.

Nota: También puedes usar Amazon Athena para consultar los registros de CloudTrail en busca de eventos por código de error.

Resolución de un error de llamada a la API

Realiza las siguientes acciones en función del código de error que recibas.

AccessDeniedException

Si tu usuario o rol de AWS Identity and Access Management (IAM) no tiene los permisos necesarios, recibirás el error "AccessDeniedException". El siguiente ejemplo de error indica que el usuario arn:aws:sts::123456789012:assumed-role/test-role/test-session no tiene los permisos necesarios para realizar la acción 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"

Para agregar el permiso correspondiente a la política de permisos de la identidad de IAM, sigue estos pasos:

1. Abre la consola de IAM.
2. En el panel de navegación, elige Roles, Grupos de usuarios o Usuarios en función de tu identidad de IAM.
3. Usa el filtro de búsqueda para filtrar las opciones de rol o usuario. A continuación, selecciona la identidad de IAM que deseas ver.
4. Selecciona la pestaña Permisos.
5. Para ver los permisos asociados a la identidad de IAM, amplía la política de permisos.
6. En la política de permisos, agrega ecs:your-event-name a la lista Acciones. A continuación, selecciona Permitir para Efecto. O bien, crea una nueva política que permita ecs:your-event-name y asocia la política al rol o usuario de IAM. Para obtener más información, consulta Edición de políticas administradas por el cliente (consola).

Puedes usar el simulador de política de IAM para probar una política que no esté asociada a un usuario, grupo de usuarios o rol de IAM.

ClientException

Si tu cliente de ECS especifica un identificador o un recurso que no es válido o no existe, recibirás el error "ClientException". El siguiente ejemplo de error indica que el comando RunTask hace referencia a una TaskDefinition que no es válida:

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

Comprueba que haces referencia a los recursos correctos en el comando, las llamadas a la API y el código.

ClusterNotFoundException

Si Amazon ECS no encuentra el clúster que especificaste para una operación, recibirás el error "ClusterNotFoundException". El siguiente ejemplo de error indica que Amazon ECS no puede encontrar el clúster que especificaste para la operación StartTask:

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

Comprueba que haces referencia al nombre de clúster correcto en el comando, las llamadas a la API y el código.

Para enumerar todos los clústeres de ECS actuales, ejecuta el comando list-clusters de la AWS CLI:

aws ecs list-clusters --region example_region

Nota: Sustituye example_region por tu región de AWS.

A continuación, comprueba que existe el clúster al que haces referencia en la llamada a la API.

InvalidParameterException

Si un parámetro que escribes en un comando no es válido y la versión de la definición de la tarea no existe, recibirás el siguiente error:

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

El siguiente ejemplo del comando RunTask incluye que la definición de tarea CentOS:3 no existe:

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

Nota: En el ejemplo anterior, sustituye example_cluster por el nombre de tu clúster.

El siguiente ejemplo de error se corresponde con el comando RunTask anterior:

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

Comprueba que los parámetros del comando son válidos.

ServerException

Si un servidor está inactivo cuando realizas una llamada a la API, recibirás el error "ServerException". Si recibes este error en todas las llamadas a la API, significa que el servicio de AWS no está disponible.

Los errores ServerException suelen ser temporales. Espera y, a continuación, vuelve a realizar la llamada a la API. Si el problema persiste, ponte en contacto con AWS Support y proporciona la siguiente información:

• Proporciona la marca de tiempo que corresponde al error.
• Si usas la línea de comandos, proporciona el comando que devuelve el error.
• Si utilizas un lenguaje de programación o una infraestructura como herramientas de código que utilizan AWS SDK, proporciona el bloque de código que devuelve el error.
• Si usas la consola de administración de AWS, proporciona la URL de la página de la consola de administración de AWS y la acción que devuelve el error.

ServiceNotActiveException

Si actualizas un servicio de Amazon ECS que está inactivo, recibirás el error "ServiceNotActiveException". Verifica que el servicio de ECS que deseas actualizar esté en tu clúster de ECS y esté en estado ACTIVO.

Para enumerar todos los servicios de un clúster, ejecuta el comando list-clusters de la AWS CLI:

aws ecs list-services --cluster example_cluster

Nota: Sustituye example_cluster por el nombre de tu clúster.

Comprueba que la salida del comando contenga el servicio que deseas actualizar. A continuación, ejecuta el comando describe-services para comprobar que el servicio está en estado ACTIVO:

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

Nota: Sustituye example_service_name y example_cluster por tus valores.

El siguiente ejemplo de salida indica que el servicio de ejemplo está en estado ACTIVO:

{    "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 tu servicio no está en estado ACTIVO, comprueba que el valor del número de tareas del servicio de Amazon ECS sea superior a cero. También puedes ejecutar el comando update-service de la AWS CLI para actualizar el valor del número de tareas a 1:

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

Nota: Sustituye example_cluster_name y example_service_name por tus valores. Puedes establecer el valor de recuento deseado en un número mayor que cero.

A continuación, en la consola de ECS, comprueba que el estado de la definición de la tarea sea ACTIVO. También puedes ejecutar el comando describe-task-definition:

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

Nota: Sustituye example_taskdefinition por tu definición de tarea.

Comprueba los registros de CloudWatch para ver si hay errores de servicio o revisiones de red que se correspondan con el error ServiceNotActiveException.

PlatformTaskDefinitionIncompatibilityException

Si inicias una tarea en una plataforma que no cumple con las capacidades requeridas de la definición de tarea, recibirás el error "PlatformTaskDefinitionIncompatibilityException". En el siguiente ejemplo de error, la versión 1.3.0 de la plataforma no admite los requisitos del comando create-service de la AWS CLI:

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

El siguiente ejemplo de comando create-service crea un servicio con un volumen de Amazon Elastic File System (Amazon EFS) adjunto a la versión 1.3.0 de la plataforma:

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

Comprueba que la versión de la plataforma AWS Fargate sea compatible con las capacidades que requiere la definición de la tarea.

PlatformUnknownException

Si especificas una versión de la plataforma desconocida o incorrecta al iniciar una tarea, recibirás el error "PlatformUnknownException". El siguiente ejemplo de error indica que la versión de la plataforma que especificas en una operación de creación de servicio no es correcta:

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

El siguiente ejemplo de comando create-service contiene la versión de la plataforma 1.3 incorrecta, en lugar de la versión 1.3.0: correcta:

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

Comprueba que la versión de la plataforma que especificaste al iniciar una tarea sea correcta. Para obtener más información, consulta Versiones de la plataforma Fargate Linux para Amazon ECS y Versiones de la plataforma de Fargate Windows para Amazon ECS.

ServiceNotFoundException

El error "ServiceNotFoundException" se produce cuando el servicio de ECS especificado no existe en tu comando o código. Comprueba que el nombre del servicio del comando o código es correcto y, a continuación, confirma que el servicio está en el clúster. Para ver todos los servicios del clúster, ejecuta el comando list-clusters de la AWS CLI:

aws ecs list-services --cluster example_cluster

Nota: Sustituye example_cluster por tu clúster.

UnsupportedFeatureException

El error "UnsupportedFeatureException" se produce cuando inicias una tarea de Fargate en una región de AWS en la que Fargate no admite tu contenedor. Para obtener más información, consulta Regiones compatibles con Amazon ECS en AWS Fargate.

Solución de problemas de API en las aplicaciones

Puedes recibir las siguientes respuestas comunes de código de estado HTTP 5## al acceder a la aplicación alojada en una tarea de ECS:

• Se produce un error "HTTP 500 - Internal server" si una aplicación encuentra una condición inesperada, como un error. O bien, si configuras mal una aplicación, recibirás este error.
• Se produce el error "HTTP 503 - Service unavailable" si una tarea de ECS experimenta una gran carga de trabajo. O bien, si la aplicación incluida en tu tarea está inactiva por mantenimiento, recibirás este error.

Revisa los registros de la aplicación para tus tareas de ECS en Registros de Amazon CloudWatch. Cada definición de tarea se corresponde con un flujo de registro que contiene el registro de la aplicación de la tarea. Para ver información sobre el grupo de registros y el flujo de registros de la definición de tareas, ejecuta el comando describe-task-definition:

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

Nota: Sustituye example_task_definition por la definición de tarea.

Información relacionada

Motivos de error de la API de Amazon ECS