Requisitos previos Situaciones comunes de solución de problemas Análisis de registros en instancias administradas de Amazon ECS Uso de la AWS CLI de EC2 para obtener la salida de la consola desde una instancia administrada de Amazon ECS Eliminación Recursos adicionales

Solución de problemas de instancias administradas de Amazon ECS

Use los siguientes procedimientos para solucionar los problemas de instancias administradas de Amazon ECS, que incluyen problemas comunes, técnicas de diagnóstico y pasos de resolución.

Requisitos previos

Antes de solucionar problemas de instancias administradas de Amazon ECS, asegúrese de cumplir los siguientes requisitos.

La AWS CLI está instalada y configurada con los permisos adecuados.

Para obtener más información, consulte Instalación o actualización de la versión más reciente de la AWS Command Line Interface en la Guía del usuario de AWS Command Line Interface.
Acceso a un clúster con el proveedor de capacidad de instancias administradas de Amazon ECS. Para obtener más información, consulte Creación de un clúster para instancias administradas de Amazon ECS.

Situaciones comunes de solución de problemas

Visualización de los registros del agente de contenedor de instancias administradas de Amazon ECS

Para ver estos archivos de registro de Amazon ECS en instancias administradas de Amazon ECS, conéctese a un contenedor privilegiado que esté en marcha en la instancia.

Pasos de diagnóstico

Implemente un contenedor de depuración con privilegios y capacidades de Linux como una tarea de Amazon ECS:

Configure las siguientes variables de entorno.

Sustituya las entradas del usuario por sus valores.


export ECS_CLUSTER_NAME="your-cluster-name"
export AWS_REGION="your-region"
export ACCOUNT_ID="your-account-id"

Cree una definición de tarea mediante un archivo JSON de CLI denominado node-debugger.json.


cat << EOF > node-debugger.json
{
  "family": "node-debugger",
  "taskRoleArn": "arn:aws:iam::${ACCOUNT_ID}:role/ecsTaskExecutionRole",
  "executionRoleArn": "arn:aws:iam::${ACCOUNT_ID}:role/ecsTaskExecutionRole",
  "cpu": "256",
  "memory": "1024",
  "networkMode": "host",
  "pidMode": "host",
  "requiresCompatibilities": ["MANAGED_INSTANCES", "EC2"],
  "containerDefinitions": [
    {
      "name": "node-debugger",
      "image": "public.ecr.aws/amazonlinux/amazonlinux:2023",
      "essential": true,
      "privileged": true,
      "command": ["sleep", "infinity"],
      "healthCheck": {
          "command": ["CMD-SHELL", "echo debugger || exit 1"],
          "interval": 30,
          "retries": 3,
          "timeout": 5
      },
      "linuxParameters": {
        "initProcessEnabled": true
      },
      "mountPoints": [
        {
          "sourceVolume": "host-root",
          "containerPath": "/host",
          "readOnly": false
        }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/aws/ecs/node-debugger",
          "awslogs-create-group": "true",
          "awslogs-region": "${AWS_REGION}",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ],
  "volumes": [
    {
      "name": "host-root",
      "host": {
        "sourcePath": "/"
      }
    }
  ]
}
EOF

Realice el registro y, a continuación, ponga en marcha la tarea. Use los siguientes comandos.


aws ecs register-task-definition --cli-input-json file://node-debugger.json

TASK_ARN=$(aws ecs run-task \
  --cluster $ECS_CLUSTER_NAME \
  --task-definition node-debugger \
  --enable-execute-command \
  --capacity-provider-strategy capacityProvider=managed-instances-default,weight=1 \
  --query 'tasks[0].taskArn' --output text)

# Wait for task to be running
aws ecs wait tasks-running --cluster $ECS_CLUSTER_NAME --tasks $TASK_ARN

Conéctese al contenedor. Ejecute el siguiente comando.


aws ecs execute-command \
  --cluster $ECS_CLUSTER_NAME \
  --task $TASK_ARN \
  --container node-debugger \
  --interactive \
  --command "/bin/sh"

Compruebe los registros de los agentes de Amazon ECS:

En la sesión interactiva del contenedor, use los siguientes comandos:


# Install required tools
yum install -y util-linux-core

# View ECS agent logs
nsenter -t 1 -m -p cat /var/log/ecs/ecs-agent.log | tail -50

# Check agent registration
nsenter -t 1 -m -p grep "Registered container instance" /var/log/ecs/ecs-agent.log

Example Output:

{"level":"info","time":"2025-10-16T12:39:37.665","msg":"Registered container instance with cluster!"}

# Verify capabilities
nsenter -t 1 -m -p grep "Response contained expected value for attribute" /var/log/ecs/ecs-agent.log

Compruebe las métricas de los agentes:

Use el siguiente comando para ver los registros.


# View metrics logs
nsenter -t 1 -m -p cat /var/log/ecs/metrics.log | tail -20

Problemas de ubicación de tareas

Los siguientes son síntomas de problemas de ubicación de tareas:

Tareas bloqueadas en estado PENDIENTE
Las tareas no se inician en instancias administradas de Amazon ECS
Errores de recursos insuficientes

Pasos de diagnóstico

Use los siguientes comandos para diagnosticar problemas de ubicación de tareas y recopilar información sobre la capacidad del clúster, las instancias de contenedor y los servicios del sistema:


# Check cluster capacity
aws ecs describe-clusters --clusters cluster-name --include STATISTICS

# Check cluster capacity providers
aws ecs describe-clusters --clusters cluster-name --include STATISTICS --query 'clusters[].capacityProviders'

# List container instances
aws ecs list-container-instances --cluster cluster-name

# Check container instance details
aws ecs describe-container-instances --cluster cluster-name --container-instances container-instance-arn

# Check container instance remaining resources CPU/Mem
aws ecs describe-container-instances --cluster $ECS_CLUSTER_NAME --container-instances container-instance-arn --query 'containerInstances[].remainingResources'

# Check container instance Security Group
aws ecs describe-container-instances --cluster $ECS_CLUSTER_NAME --container-instances container-instance-arn --query 'containerInstances[].ec2InstanceId' --output text
aws ec2 describe-instances --instance-ids instance-id --query 'Reservations[0].Instances[0].SecurityGroups'
aws ec2 describe-security-groups --group-ids security-group-id

Supervisión del servicio del sistema:


# Check Containerd status
nsenter -t 1 -m -p systemctl status containerd.service

# Check Amazon ECS container agent status
nsenter -t 1 -m -p systemctl status ecs

Resolución

Para resolver los problemas de ubicación de las tareas, siga estos pasos para garantizar la configuración y la capacidad adecuadas:

Verifique los requisitos de recursos de la tarea en comparación con la capacidad disponible.
Compruebe las limitaciones y estrategias de ubicación.
Asegúrese de que el proveedor de capacidad de instancias administradas de Amazon ECS esté configurado.
Asegúrese de que la tarea y el grupo de seguridad de la instancia de contenedor tengan una regla de salida que permita el tráfico hacia los puntos de conexión de administración de agentes de Amazon ECS.

Problemas de red

Los siguientes son síntomas de problemas de red:

Las tareas no pueden llegar a los servicios externos
Problemas de resolución de DNS

Pasos de diagnóstico

Pruebas de la conectividad de red:

En el contenedor de depuración, use los siguientes comandos:

nota

Confirme que el grupo de seguridad asociado a su proveedor de capacidad o a la tarea de Amazon ECS permita el tráfico.


# Install DNS Utility
yum install bind-utils -y

# Test DNS resolution
nslookup amazon.com

# Test external connectivity
curl -I https://amazon.com

Limitaciones de recursos

Los siguientes son síntomas de problemas de red:

Tareas canceladas debido a límites de memoria
Limitación de la CPU
Problemas de espacio en el disco

Pasos de diagnóstico

Use comandos para supervisar los recursos y los límites de los contenedores.

Supervisión de recursos:


# Check memory usage
nsenter -t 1 -m -p free -h

# Check disk usage
nsenter -t 1 -m -p lsblk

# Check disk usage
nsenter -t 1 -m -p df -h

Límites de contenedores:


# Check OOM kills
nsenter -t 1 -m -p dmesg | grep -i "killed process"

Problema de desconexión del agente de instancia de contenedor

Los siguientes son síntomas de los problemas de desconexión del agente de instancias de contenedor:

Instancias de contenedor que se muestran como desconectadas en la consola de Amazon ECS
Las tareas no se pueden colocar en instancias específicas
Fallos en el registro del agente en los registros

Pasos de diagnóstico

Si hay una tarea de privilegios en marcha en el host a la que ECS Exec pueda acceder, use los siguientes comandos para diagnosticar los problemas de conectividad del agente:


# check service status 
nsenter -t 1 -m -p systemctl restart ecs 
nsenter -t 1 -m -p systemctl restart containerd 

# restart stopped services 
nsenter -t 1 -m -p systemctl restart ecs 
nsenter -t 1 -m -p systemctl restart containerd

De lo contrario, fuerce la anulación del registro de las instancias de instancias administradas de Amazon ECS. Use el siguiente comando:


# list ECS Managed Instance container
aws ecs list-container-instances --cluster managed-instances-cluster --query 'containerInstanceArns' --output text

# deregister the specific container instance
aws ecs deregister-container-instance \
    --cluster $ECS_CLUSTER_NAME \
    --container-instance container-instance-arn \
    --force

Resolución

Para resolver problemas de desconexión del agente, siga estos pasos:

Compruebe los permisos del rol de IAM para la instancia de contenedor.
Compruebe que las reglas del grupo de seguridad permiten el tráfico HTTPS saliente a los puntos de conexión de ECS.
Garantice la conectividad de red a los servicios de AWS.
Reinicie el servicio del agente de ECS si es necesario: nsenter -t 1 -m -p systemctl restart ecs.
Compruebe que la configuración de ECS_CLUSTER en /etc/ecs/ecs.config coincide con el nombre de su clúster.

Análisis de registros en instancias administradas de Amazon ECS

Registros del sistema

Utilice los siguientes comandos para examinar los registros del sistema e identificar posibles problemas con la instancia administrada:


# Check system messages
nsenter -t 1 -m -p journalctl --no-pager -n 50

# Check kernel logs
nsenter -t 1 -m -p dmesg | tail -20

# Check for disk space errors
nsenter -t 1 -m -p journalctl --no-pager | grep -i "no space\|disk full\|enospc"

Uso de la AWS CLI de EC2 para obtener la salida de la consola desde una instancia administrada de Amazon ECS

Utilice el ID de instancia de Amazon EC2 para recuperar la salida de la consola.

Sustituya las entradas del usuario por sus valores.


aws ec2 get-console-output --instance-id instance-id --latest --output text

Eliminación

Use lo siguiente para detener la tarea de depuración y anular el registro de la definición de la tarea.


# Stop debug task
aws ecs stop-task --cluster $ECS_CLUSTER_NAME --task $TASK_ARN

# Deregister task definition (optional)
aws ecs deregister-task-definition --task-definition node-debugger

Recursos adicionales

Para obtener más información sobre la solución de problemas de instancias administradas de Amazon ECS, consulte los siguientes recursos:

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

AWS FargateCuotas de limitación de

Solución de problemas de instancias administradas de Amazon ECS