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

Breve descrição

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. O SSM Agent exige que as seguintes condições sejam atendidas:

• O SSM Agent deve se conectar aos endpoints de serviço necessários.
• O SSM Agent deve exigir permissões do AWS Identity and Access Management (AWS IAM) para chamar a API do Systems Manager.
• O Amazon EC2 deve assumir credenciais válidas do perfil de instância do IAM.

Se alguma dessas condições não for atendida, o SSM Agent não será executado.

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

Linux

/var/log/amazon/ssm/amazon-ssm-agent.log

/var/log/amazon/ssm/errors.log

Windows

%PROGRAMDATA%\Amazon\SSM\Logs\amazon-ssm-agent.log

%PROGRAMDATA%\Amazon\SSM\Logs\errors.log

Observação: como o SSM Agent é atualizado frequentemente com novos recursos, é uma prática recomendada configurar atualizações automatizadas para o SSM Agent.

Resolução

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

Para usar os logs do SSM Agent para solucionar problemas, execute o comando ssm-cli. Em seguida, siga as etapas para resolver o problema.

O SSM Agent não consegue se comunicar com os endpoints necessários

Com base no seu caso de uso, conclua as seguintes tarefas.

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

Quando o SSM Agent não consegue acessar o serviço de metadados, ele também não consegue localizar as informações da região da AWS, a função do IAM ou o ID da instância desse serviço. Nesse caso, você vê uma mensagem de erro nos registros do SSM Agent semelhante à seguinte:

“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 geralmente ocorre quando você usa um proxy para conexões de saída à Internet a partir da sua instância antes de configurar o SSM Agent para um proxy. Para resolver esse problema, configure o SSM Agent para usar um proxy.

Em instâncias do Windows, esse erro também pode ocorrer devido a uma rota de rede persistente mal configurada quando você usa uma AMI personalizada para executar sua instância. Você deve verificar se a rota para o IP do serviço de metadados aponta para o gateway padrão correto. Para obter mais informações, consulte Por que minha instância Windows do Amazon EC2 gera um erro “Aguardando o serviço de metadados”?

Para verificar se os metadados estão ativados para sua instância, execute o seguinte comando na AWS CLI:

aws ec2 describe-instances --instance-ids i-1234567898abcdef0 --query 'Reservations[*].Instances[*].MetadataOptions'

Observação: substitua i-1234567898abcdef0 pelo ID da sua instância.

Você recebe uma saída semelhante ao exemplo a seguir:

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

Nesta saída, "HttpEndpoint": "enabled" indica que os metadados estão ativados para sua instância.

Se os metadados não estiverem ativados, será possível ativá-los com o comando aws ec2 modify-instance-metadata-options. Para obter mais informações, consulte Modificar as opções de metadados da instância para instâncias existentes.

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 do serviço, o SSM Agent falhará. O SSM Agent deve fazer uma conexão de saída com o endpoint do SSM: ssm.REGION.amazonaws.com após chamadas de API de serviço do Systems Manager na porta 443.

Observação: o SSM Agent usa as informações de região que o serviço de metadados da instância recupera para substituir o valor REGION nesses endpoints.

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 172.31.24.65:443: i/o timeout" "DEBUG [MessagingDeliveryService] RequestError: falha na solicitação de envio causada por: Post https://ec2messages.ap-southeast-2.amazonaws.com/: net/http: request cancelled while waiting for connection (Client.Timeout exceeded while awaiting headers)”

Confira a seguir alguns motivos comuns pelos quais o SSM Agent não consegue se conectar aos endpoints da API Systems Manager na porta 443:

• As regras do grupo de segurança de saída de instâncias não permitem conexões de saída na porta 443.
• As regras do grupo de segurança de entrada e saída de endpoints da nuvem privada virtual (VPC) não permitem conexões de entrada e saída com o endpoint da interface VPC na porta 443.
• Quando a instância está em uma sub-rede pública, as regras da tabela de roteamento não são configuradas para direcionar o tráfego usando um gateway da Internet.
• Quando a instância está em uma sub-rede privada, as regras da tabela de roteamento não são configuradas para direcionar o tráfego usando um gateway NAT ou um endpoint da VPC.
• Se as regras da tabela de roteamento estiverem configuradas para usar um proxy para todas as conexões de saída, o SSM Agent não estará configurado para usar um proxy.

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.

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 conforme o esperado. 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 não tiver as permissões corretas do IAM, ele publicará uma mensagem de erro nos logs do SSM Agent.

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

“ERROR [instanceID=i-XXXXX] [HealthCheck] error when calling AWS APIs. error details - AccessDeniedException: User: arn:aws:sts::XXX:assumed-role/XXX /i-XXXXXX is not authorized to perform: ssm:UpdateInstanceInformation on resource: arn:aws:ec2:ap-southeast-2:XXXXXXX:instance/i-XXXXXX
status code: 400, request id: XXXXXXXX-XXXX-XXXXXXX
INFO [instanceID=i-XXXX] [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:

“ERROR [instanceID=i-XXXXXXX] [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-XXXXXXX] [HealthCheck] increasing error count by 1”

Verifique se a função do IAM anexada à instância contém as permissões necessárias para permitir que uma instância use a funcionalidade principal de serviços do Systems Manager. Ou, se uma função de perfil de instância ainda não estiver anexada, anexe uma função de perfil de instância e inclua as permissões AmazonSSMManagedInstanceCore.

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

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

Se um grande volume de instâncias gerenciadas que executam o SSM Agent fizer chamadas da API UpdateInstanceInformation simultâneas, essas chamadas poderão ser limitadas.

Se a chamada de API UpdateInstanceInformation para sua instância for limitada, você verá mensagens de erro nos logs do SSM Agent semelhantes às seguintes:

“INFO [HealthCheck] HealthCheck reporting agent health.
ERROR [HealthCheck] error when calling AWS APIs. error details - ThrottlingException: Rate exceeded
status code: 400, request id: XXXXX-XXXXX-XXXX
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.
• Implemente novas tentativas de erro e recuos exponenciais ao fazer chamadas de API.
• Escalone os intervalos das chamadas de API para que elas não sejam executadas todas ao mesmo tempo.
• Solicite um aumento do limite de limitação para chamadas da API UpdateInstanceInformation.

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

Se o Amazon EC2 não puder assumir o perfil do IAM, você verá uma mensagem semelhante ao exemplo 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 identity2023-01-25 09:56:19 INFO [CredentialRefresher] Sleeping for 1s before retrying retrieve credentials
2023-01-25 09:56:20 ERROR [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity
2023-01-25 09:56:20 INFO [CredentialRefresher] Sleeping for 2s before retrying retrieve credentials
2023-01-25 09:56:22 ERROR [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity
2023-01-25 09:56:22 INFO [CredentialRefresher] Sleeping for 4s before retrying retrieve credentials
2023-01-25 09:56:26 ERROR [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity
2023-01-25 09:56:26 INFO [CredentialRefresher] Sleeping for 9s before retrying retrieve credentials
2023-01-25 09:56:35 ERROR [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity
2023-01-25 09:56:35 INFO [CredentialRefresher] Sleeping for 17s before retrying retrieve credentials
2023-01-25 09:56:52 ERROR [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity
2023-01-25 09:56:52 INFO [CredentialRefresher] Sleeping for 37s before retrying retrieve credentials

Se você usar o IMDSv1 para recuperar metadados da instância do EC2, também verá um erro semelhante ao exemplo a seguir:

# curl http://169.254.169.254/latest/meta-data/iam/security-credentials/profile-name{
  "Code" : "AssumeRoleUnauthorizedAccess",
  "Message" : "EC2 cannot assume the role profile-name. Please see documentation at https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_iam-ec2.html#troubleshoot_iam-ec2_errors-info-doc.",
  "LastUpdated" : "2023-01-25T09:57:56Z"
}

Observação: no exemplo anterior, profile-name é o nome do perfil de instância. Se você usar o IMDSv2, o comando anterior não funcionará. Para obter mais informações sobre como recuperar metadados, consulte Recuperar metadados de instâncias para Linux e Windows.

Para solucionar esse erro, verifique a política de confiança anexada ao perfil do IAM. Na política, você deve especificar o Amazon EC2 como um serviço que pode assumir a função do IAM. Atualize sua política do IAM por meio da API UpdateAssumeRolePolicy para que ela pareça semelhante ao exemplo a seguir:

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

Para mais informações, consulte O documento iam/security-credentials/[role-name] indica "Code":"AssumeRoleUnauthorizedAccess".