Pré-requisitos Cenários comuns de solução de problemas Análise de log em instâncias gerenciadas do Amazon ECS Usar a AWS CLI do EC2 para obter a saída do console de uma instância gerenciada do Amazon ECS Limpeza Recursos adicionais

Solucionar problemas nas instâncias gerenciadas do Amazon ECS

Use os procedimentos a seguir para solucionar problemas de instâncias gerenciadas do Amazon ECS, incluindo problemas comuns, técnicas de diagnóstico e etapas de resolução.

Pré-requisitos

Antes de solucionar problemas de instâncias gerenciadas do Amazon ECS, verifique se você tem os requisitos em vigor. a seguir.

A AWS CLI está instalada e configurada com as permissões corretas

Para obter mais informações, consulte Instalar ou atualizar para a versão mais recente da AWS Command Line Interface no Guia do usuário do AWS Command Line Interface.
Acesso a um cluster com o provedor de capacidade de instâncias gerenciadas do Amazon ECS. Para obter mais informações, consulte Criar um cluster para instâncias gerenciadas do Amazon ECS.

Cenários comuns de solução de problemas

Visualizar logs do agente de contêiner de instâncias gerenciadas do Amazon ECS

Você pode visualizar esses arquivos de log do Amazon ECS nas instâncias gerenciadas do Amazon ECS conectando-se a um contêiner privilegiado em execução na instância.

Etapas de diagnóstico

Implante um contêiner de depuração com privilégios e recursos do Linux como tarefa do Amazon ECS:

Defina as seguintes variáveis de ambiente.

Substitua os valores das user-input pelos seus.


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

Crie uma definição de tarefa usando um arquivo JSON da CLI chamado 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

Registre-se e, em seguida, execute a tarefa. Execute os seguintes 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

Conectar-se ao contêiner. Execute o comando a seguir.


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

Verifique os logs do agente do Amazon ECS:

Na sessão interativa do contêiner, execute os seguintes 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

Verifique as métricas do agente:

Execute o comando a seguir para visualizar os logs.


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

Problemas de posicionamento de tarefa

Veja a seguir os sintomas de problemas de posicionamento de tarefa:

Tarefas paradas no estado PENDING
Falha ao iniciar tarefas nas instâncias gerenciadas do Amazon ECS
Erros de recursos insuficientes

Etapas de diagnóstico

Execute os comandos a seguir para diagnosticar problemas de posicionamento de tarefa e coletar informações sobre capacidade do cluster, instâncias de contêiner e serviços do 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

Monitoramento de serviços do 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

Resolução

Para resolver problemas de posicionamento de tarefa, siga estas etapas para garantir a configuração e a capacidade adequadas:

Verifique os requisitos de recursos da tarefa em relação à capacidade disponível
Verifique as restrições e estratégias de posicionamento
Certifique-se de que o provedor de capacidade de instâncias gerenciadas do Amazon ECS esteja configurado
Certifique-se de que o grupo de segurança da instância de contêiner e tarefa tenha uma regra de saída que permita tráfego para os endpoints de gerenciamento do agente do Amazon ECS

Problemas de rede

Veja a seguir os sintomas de problemas de rede:

Tarefas incapazes de acessar serviços externos
Problemas de resolução de DNS

Etapas de diagnóstico

Testes de conectividade de rede:

No contêiner de depuração, execute os seguintes comandos:

nota

Confirme se o grupo de segurança anexado ao provedor de capacidade ou à tarefa do Amazon ECS está permitindo o tráfego.


# Install DNS Utility
yum install bind-utils -y

# Test DNS resolution
nslookup amazon.com

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

Restrições de recursos

Veja a seguir os sintomas de problemas de rede:

Tarefas eliminadas por causa de limites de memória
Controle de utilização de CPU
Problemas de espaço em disco

Etapas de diagnóstico

Execute comandos para monitorar os recursos e os limites de contêineres.

Monitoramento 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

Limites de contêineres:


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

Problema de desconexão do agente de instância de contêiner

Veja a seguir os sintomas de problemas de desconexão do agente de instância de contêiner:

Instâncias de contêiner exibidas como desconectadas no console do Amazon ECS
Falha no posicionamento de tarefas em instâncias específicas
Falhas no registro do agente nos logs

Etapas de diagnóstico

Se houver uma tarefa de privilégio existente em execução no host que o ECS Exec possa acessar, execute os seguintes comandos para diagnosticar problemas de conectividade do 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

Caso contrário, force o cancelamento do registro das instâncias gerenciadas do Amazon ECS. Execute o seguinte 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

Resolução

Para resolver problemas de desconexão do agente, siga estas etapas:

Verifique as permissões do perfil do IAM para a instância de contêiner
Verifique se as regras do grupo de segurança permitem tráfego HTTPS de saída para endpoints do ECS
Certifique-se da conectividade da rede com os serviços da AWS
Reinicie o serviço do agente do ECS, se necessário: nsenter -t 1 -m -p systemctl restart ecs
Verifique se a configuração ECS_CLUSTER em /etc/ecs/ecs.config corresponde ao nome do cluster

Análise de log em instâncias gerenciadas do Amazon ECS

Logs do sistema.

Use os comandos a seguir para examinar os logs do sistema e identificar possíveis problemas com a instância gerenciada:


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

Usar a AWS CLI do EC2 para obter a saída do console de uma instância gerenciada do Amazon ECS

Use o ID da instância do Amazon EC2 para recuperar a saída do console.

Substitua os valores das user-input pelos seus.


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

Limpeza

Execute o seguinte para interromper a tarefa de depuração e cancelar o registro da definição de tarefa:


# 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 adicionais

Para obter mais informações sobre a solução de problemas de instâncias gerenciadas do Amazon ECS, consulte os seguintes recursos:

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Cotas de controle de utilização do AWS Fargate

Solucionar problemas nas instâncias gerenciadas do Amazon ECS