Como usar os registros 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 exige permissões do AWS Identity and Access Management (IAM) para chamar as chamadas de API do Systems Manager.
• O Amazon EC2 deve assumir credenciais válidas do perfil da instância do IAM.

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

Para identificar a causa raiz da falha do SSM Agent, revise os registros 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

Primeiro, revise os registros e identifique se o problema é causado pela falta de conexões de endpoint, de permissões perdidas ou de credenciais. Em seguida, siga as etapas de solução de problemas relevantes para seu problema.

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

O agente SSM 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”

O motivo mais comum para esse erro é usar um proxy para conexões de saída à Internet a partir da sua instância sem configurar o SSM Agent como proxy. Certifique-se de configurar 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 iniciar 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 verificar se os metadados estão ativados para sua instância, execute o seguinte comando na AWS Command Line Interface (AWS CLI). Certifique-se de substituir i-1234567898abcdef0 pelo ID da sua instância:

Observação: se houver algum erro ao executar comandos da AWS CLI, verifique se você está usando a versão mais recente da AWS CLI.

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

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, você poderá ativá-los com o comando aws ec2 modify-instance-metadata-options. Para obter mais informações, consulte Modifique 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 Agente SSM deve fazer uma conexão de saída com as seguintes chamadas de API de serviço do Systems Manager na porta 443:

• Endpoint SSM: ssm.REGION.amazonaws.com
• Endpoint de mensagens do EC2: ec2messages.REGION.amazonaws.com
• Endpoint de mensagens SSM: ssmmessages.REGION.amazonaws.com

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 registros 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: send request failed caused by: Post https://ec2messages.ap-southeast-2.amazonaws.com/: net/http: request cancelled while waiting for connection (Client.Timeout exceeded while awaiting headers)”

A seguir estão 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 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

O SSM Agent não conseguiu se registrar como on-line no Systems Manager porque o SSM Agent não está autorizado a fazer chamadas da API UpdateInstanceInformation para o serviço.

A chamada da 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, você verá uma mensagem de erro nos registros 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.

Limitação de chamadas da API Systems Manager

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

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

“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 a função do IAM, você verá uma mensagem semelhante ao exemplo a seguir nos registros 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
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ê tentar 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: neste exemplo, profile-name é o nome do perfil da instância.

Para solucionar esse erro, verifique a política de confiança anexada à função 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".

---