Como usar os logs do SSM Agent para solucionar problemas com o SSM Agent na minha instância gerenciada?

Breve descrição

Observação: se você receber mensagens de erro ao executar comandos da AWS Command Line Interface (AWS CLI), consulte Solução de problemas da AWS CLI. Além disso, verifique se você está usando a versão mais recente da AWS CLI.

O SSM Agent é executado em sua instância gerenciada do Amazon Elastic Compute Cloud (Amazon EC2) e processa solicitações do serviço AWS Systems Manager. Você deve atender às seguintes condições para usar o SSM Agent. Se você não atender a nenhuma dessas condições, o SSM Agent falhará ao ser executado:

• O SSM Agent deve se conectar aos endpoints de serviço necessários.
• O SSM Agent deve ter permissões do AWS Identity and Access Management (AWS IAM) para chamar as operações da API do Systems Manager.
• O Amazon EC2 deve recuperar credenciais válidas do perfil de instância do IAM. Ou, se você configurou a Configuração padrão de gerenciamento de host, o Amazon EC2 deve recuperar as credenciais do perfil padrão que ele fornece.

Para identificar a causa raiz da falha do SSM Agent, analise os Logs do SSM Agent nos seguintes locais:

• No Linux:
  /var/log/amazon/ssm/amazon-ssm-agent.log
  /var/log/amazon/ssm/errors.log
• No Windows:
  %PROGRAMDATA%\Amazon\SSM\Logs\amazon-ssm-agent.log
  %PROGRAMDATA%\Amazon\SSM\Logs\errors.log

Observação: é uma prática recomendada configurar atualizações automatizadas no SSM Agent.

Resolução

Para usar os logs do SSM Agent para solucionar problemas, execute o comando ssm-cli que corresponde ao seu sistema operacional (SO). Em seguida, conclua as etapas de solução de problemas a seguir com base na sua saída.

O SSM Agent não consegue acessar o serviço de metadados

O Systems Manager depende dos metadados da instância para funcionar corretamente. O Systems Manager pode usar a versão 1 ou a versão 2 do Instance Metadata Service (IMDSv1 e IMDSv2) para acessar os metadados da instância. Sua instância deve ser capaz de acessar 169.254.169.254, que é o endereço IPv4 do serviço de metadados da instância.

Quando o SSM Agent não consegue acessar o serviço de metadados, ele também não consegue recuperar a região da AWS, o perfil do IAM ou o ID da instância. Mensagens de erro semelhantes ao exemplo a seguir indicam que o SSM Agent não consegue acessar o serviço de metadados:

"INFO- Failed to fetch instance ID. Data from vault is empty. RequestError: send request failed caused by: Get http://169.254.169.254/latest/meta-data/instance-id"

Esse erro ocorre quando você usa um proxy em conexões de internet de saída a partir da sua instância antes de configurar o SSM Agent para usar um proxy. Para resolver esse problema, configure o SSM Agent para usar um proxy.

Esse erro também ocorre quando você usa uma imagem de máquina da Amazon (AMI) personalizada para executar instâncias Windows com rotas de rede estáticas incorretas. Verifique se a rota para o IP do serviço de metadados aponta para o gateway padrão correto. Para obter mais informações, consulte Como soluciono o erro "Waiting for the metadata service" na minha instância Windows do Amazon EC2?

Para verificar se os metadados estão ativados em sua instância, execute o seguinte comando describe-instances da AWS CLI:

aws ec2 describe-instances --instance-ids example-id --query 'Reservations[*].Instances[*].MetadataOptions'

Observação: substitua example-id pelo ID da sua instância.

No exemplo de saída a seguir, "HttpEndpoint": "enabled" indica que você não ativou os metadados em sua instância:

"[ [{ "State": "applied", "HttpTokens": "optional", "HttpPutResponseHopLimit": 1, "HttpEndpoint": "enabled", "HttpProtocolIpv6": "disabled", "InstanceMetadataTags": "disabled" }] ]”

Se você não ativou os metadados, modifique as opções de metadados da sua instância para ativá-los.

O SSM Agent não consegue acessar os endpoints de serviço do Systems Manager

Se o SSM Agent não conseguir se conectar aos endpoints de serviço, o SSM Agent não poderá se comunicar com o Systems Manager. O SSM Agent deve fazer conexões de saída com o endpoint do SSM ssm.region.amazonaws.com na porta 443 para realizar operações da API do Systems Manager. Se você precisar usar o Gerenciador de Sessões ou o Run Command, recursos do AWS Systems Manager, o SSM Agent também deve fazer conexões com o endpoint ssmmessages.region.amazonaws.com. Para obter mais informações sobre os requisitos de configuração da Amazon Virtual Private Cloud (Amazon VPC) no SSM Agent, consulte Melhorar a segurança das instâncias do EC2 usando endpoints da VPC para o Systems Manager.

Observação: o SSM Agent recupera sua região do serviço de metadados da instância e a usa para criar o URL do endpoint.

Quando o SSM Agent não consegue se conectar aos endpoints do Systems Manager, você vê mensagens de erro semelhantes às seguintes nos logs do SSM Agent:

"ERROR [HealthCheck] error when calling AWS APIs. error details - RequestError: send request failed caused by: Post https://ssm.ap-southeast-2.amazonaws.com/: dial tcp [IP_ADDRESS]: i/o timeout"

Para obter instruções sobre como resolver esse erro, consulte Como resolvo o erro de log "RequestError: send request failed caused by:" do SSM Agent?

Se o problema persistir, siga as instruções em: Por que o Systems Manager não está mostrando minha instância do Amazon EC2 como uma instância gerenciada?

O SSM Agent não tem permissões para chamar as chamadas de API do Systems Manager necessárias

Como o SSM Agent não está autorizado a fazer chamadas da API UpdateInstanceInformation para o serviço, o SSM Agent não consegue se registrar como on-line no Systems Manager. Para obter mais informações, consulte Operações de API relacionadas à instância do namespace ssm:*.

A chamada de API UpdateInstanceInformation deve manter uma conexão com o SSM Agent para que o serviço saiba que o SSM Agent está funcionando corretamente. O SSM Agent chama o serviço Systems Manager na nuvem a cada cinco minutos para fornecer informações de verificação de integridade.

Se o SSM Agent usar as permissões do IAM incorretas, você verá um erro semelhante ao seguinte exemplo de mensagem:

"ERROR [instanceID=i-12345] [HealthCheck] error when calling AWS APIs. error details - AccessDeniedException: User: arn:aws:sts::123:assumed-role/123 /i-123456 is not authorized to perform: ssm:UpdateInstanceInformation on resource: arn:aws:ec2:ap-southeast-2:1234567:instance/i-123456 status code: 400, request id: 12345678-1234-1234567 INFO [instanceID=i-1234] [HealthCheck] increasing error count by 1"

Se o SSM Agent não tiver nenhuma permissão do IAM, você verá um erro semelhante ao seguinte exemplo de mensagem:

"ERROR [instanceID=i-1234567] [HealthCheck] error when calling AWS APIs. error details - NoCredentialProviders: no valid providers in chain. Deprecated. For verbose messaging see aws.Config.CredentialsChainVerboseErrors 2018-05-08 10:58:39 INFO [instanceID=i-1234567] [HealthCheck] increasing error count by 1"

Verifique se o perfil do IAM anexado à instância possui permissões AmazonSSMManagedInstanceCore de política gerenciada pela AWS. Se o campo estiver em branco, anexe um perfil de instância e inclua as permissões AmazonSSMManagedInstanceCore.

Para obter mais informações sobre as permissões do IAM necessárias para o Systems Manager, consulte Considerações de política adicionais para instâncias gerenciadas.

Controle de utilização de chamadas de API do Systems Manager

Se várias instâncias gerenciadas chamarem a operação da API UpdateInstanceInformation ao mesmo tempo, o Systems Manager pode limitar essas chamadas.

Mensagens de erro semelhantes ao exemplo a seguir indicam que o Systems Manager limitou as operações da API UpdateInstanceInformation em sua instância:

"INFO [HealthCheck] HealthCheck reporting agent health. ERROR [HealthCheck] error when calling AWS APIs. error details - ThrottlingException: Rate exceeded status code: 400, request id: 12345-12345-1234 INFO [HealthCheck] increasing error count by 1"

Use as seguintes etapas de solução de problemas para evitar erros de "ThrottlingException":

• Reduza a frequência das chamadas de API.
• Se você personalizou o parâmetro HealthFrequencyMinutes, reverta o parâmetro para o intervalo padrão de cinco minutos.
• Espalhe os intervalos das chamadas de API para que elas não sejam executadas todas ao mesmo tempo.

Se você ainda receber erros de "ThrottlingException" depois de realizar as ações de solução de problemas anteriores, solicite um aumento na cota de utilização dos seus nós gerenciados. Para obter instruções, consulte AWS service quotas. Para obter mais informações, consulte Cotas de serviço para nós gerenciados.

Importante: quando você aumenta uma cota de serviço, uma cobrança em sua conta é gerada. Para obter mais informações, consulte Preços do AWS Systems Manager.

O Amazon EC2 não pode assumir credenciais válidas do perfil de instância do IAM

Se o Amazon EC2 não puder assumir o perfil do IAM, você verá várias mensagens semelhantes aos exemplos a seguir nos logs do SSM Agent:

"2023-01-25 09:56:19 ERROR [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity"

"2023-01-25 09:56:19 INFO [CredentialRefresher] Sleeping for 1s before retrying retrieve credentials"

Se você usar o IMDSv1 para recuperar metadados da instância, verá uma mensagem que inclui o seguinte exemplo de erro:

"EC2 cannot assume the role example-instance-profile-name. Please see documentation at https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_iam-ec2.html#troubleshoot_iam-ec2_errors-info-doc."

É uma prática recomendada usar IMDSv2. No entanto, se você usar o IMDSv2, o comando a seguir não funcionará:

# curl http://169.254.169.254/latest/meta-data/iam/security-credentials/example=instanceprofile-name

Observação: no comando anterior, example-instance-profile-name é o nome do perfil de instância.

Para obter mais informações sobre como acessar os metadados da instância, consulte Acessar metadados de instância para uma instância do EC2.

Para solucionar esses erros, verifique a política de confiança anexada ao seu perfil do IAM. Na política, especifique o Amazon EC2 como um serviço que pode assumir o perfil do IAM. A política atualizada deve ser semelhante ao exemplo a seguir:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": ["ec2.amazonaws.com"] }, "Action": ["sts:AssumeRole"] } ] }

Depois de atualizar a política de confiança, aguarde a próxima atualização de credencial agendada automaticamente. Para implementar a alteração imediatamente, desassocie e, em seguida, reassocie o perfil de instância ou interrompa e reinicie a instância.

Para atualizar a política de confiança de forma programática, use a API UpdateAssumeRolePolicy. Para obter mais informações, consulte The iam/security-credentials/[role-name] document indicates "Code":"AssumeRoleUnauthorizedAccess".