¿Cómo puedo utilizar los registros de SSM Agent para solucionar los problemas con SSM Agent en mi instancia administrada?

Breve descripción

SSM Agent se ejecuta en su instancia administrada de Amazon Elastic Compute Cloud (Amazon EC2) y procesa las solicitudes del servicio de AWS Systems Manager. SSM Agent requiere que se cumplan las siguientes condiciones:

• SSM Agent debe conectarse a los puntos de enlace de servicio requeridos.
• SSM Agent requiere permisos de AWS Identity and Access Management (IAM) para realizar llamadas a la API de Systems Manager.
• Amazon EC2 debe asumir credenciales válidas del perfil de instancia de IAM.

Si no se cumple alguna de estas condiciones, SSM Agent no se ejecutará correctamente.

Para averiguar cuál es la causa principal del error en SSM Agent, consulte los registros de SSM Agent en las siguientes ubicaciones:

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

Nota: Dado que SSM Agent se actualiza con frecuencia con nuevas funciones, se recomienda configurar actualizaciones automatizadas para SSM Agent.

Solución

En primer lugar, consulte los registros y averigüe si el problema se debe a la falta de conexiones de punto de enlace, permisos o credenciales. A continuación, siga los pasos pertinentes para solucionar su problema.

SSM Agent no puede comunicarse con los puntos de enlace requeridos

SSM Agent no puede acceder al servicio de metadatos

Si SSM Agent no puede acceder al servicio de metadatos, tampoco podrá encontrar la información de la región de AWS, el rol de IAM o el ID de instancia de ese servicio. En tal caso, se mostrará un mensaje de error como el siguiente en los registros de SSM Agent:

«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»

El motivo más habitual por el que se produce este error es que se utiliza un proxy para las conexiones a Internet de salida desde la instancia, pero no se ha configurado SSM Agent para un proxy. Asegúrese de configurar SSM Agent de modo que utilice un proxy.

En las instancias de Windows, este error también puede deberse a una ruta de red persistente mal configurada cuando se utiliza una AMI personalizada para lanzar la instancia. Debe comprobar si la ruta de la IP del servicio de metadatos señala a la puerta de enlace predeterminada correcta.

Para comprobar si se han activado los metadatos para su instancia, ejecute el siguiente comando en la Interfaz de la línea de comandos de AWS (AWS CLI). No olvide sustituir i-1234567898abcdef0 por el ID de su instancia:

Nota: Si se muestran errores al ejecutar comandos de la AWS CLI, asegúrese de utilizar la versión más reciente de la AWS CLI.

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

Se mostrará un resultado similar al siguiente:

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

En este resultado, «HttpEndpoint»: «enabled» indica que los metadatos están activados para la instancia.

Si los metadatos no estuvieran activados, puede activarlos con el comando aws ec2 modify-instance-metadata-options. Para obtener más información, consulte Configurar las opciones de metadatos para instancias existentes.

SSM Agent no puede alcanzar los puntos de enlace del servicio de Systems Manager

Si SSM Agent no se puede conectar a los puntos de enlace del servicio, se produce un error en SSM Agent. SSM Agent debe establecer una conexión de salida con las siguientes llamadas a la API del servicio de Systems Manager en el puerto 443:

• Punto de enlace de SSM: ssm.REGION.amazonaws.com
• Punto de enlace de mensajería de EC2: ec2messages.REGION.amazonaws.com
• Punto de enlace de mensajería de SSM: ssmmessages.REGION.amazonaws.com

Nota: SSM Agent utiliza la información de la región que el servicio de metadatos de la instancia recupera para reemplazar el valor REGION en estos puntos de enlace.

Si SSM Agent no se puede conectar a los puntos de enlace de Systems Manager, se mostrarán mensajes de error similares a los siguientes en los registros de 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 continuación se indican algunos de los motivos habituales por los que SSM Agent no se puede conectar a los puntos de enlace de la API de Systems Manager en el puerto 443:

• Las reglas del grupo de seguridad de salida de instancias no permiten las conexiones de salida en el puerto 443.
• Las reglas del grupo de seguridad de entrada y salida del punto de enlace de la nube virtual privada (VPC) no permiten las conexiones de entrada ni de salida con el punto de enlace de la interfaz de la VPC en el puerto 443.
• Si la instancia se encuentra en una subred pública, las reglas de la tabla de enrutamiento no están configuradas para dirigir el tráfico a través de una puerta de enlace de Internet.
• Si la instancia se encuentra en una subred privada, las reglas de la tabla de enrutamiento no están configuradas para dirigir el tráfico a través de una puerta de enlace de NAT o un punto de enlace de VPC.
• Si las reglas de la tabla de enrutamiento se han configurado de modo que utilicen un proxy para todas las conexiones de salida, entonces no se ha configurado SSM Agent para que utilice un proxy.

SSM Agent no tiene los permisos para realizar las llamadas a la API de Systems Manager requeridas

SSM Agent no se ha podido registrar como «en línea» en Systems Manager porque no tiene autorización para realizar llamadas a la API UpdateInstanceInformation para el servicio.

La llamada a la API UpdateInstanceInformation debe mantener una conexión con SSM Agent, de modo que el servicio sepa que SSM Agent funciona según lo previsto. SSM Agent llama el servicio de Systems Manager en la nube cada cinco minutos para proporcionar información de comprobación de estado. Si SSM Agent no tiene los permisos de IAM correctos, aparecerá un mensaje de error en los registros de SSM Agent.

Si SSM Agent usa permisos de IAM incorrectos, se mostrará un error similar al siguiente:

«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»

Si SSM Agent no tiene permisos de IAM, aparecerá un error similar al siguiente:

«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»

Compruebe si el rol de IAM asociado a la instancia contiene los permisos necesarios para permitir que una instancia utilice la funcionalidad principal del servicio de Systems Manager. Como alternativa, si aún no se ha asociado ningún rol de perfil de instancia, asocie un rol de perfil de instancia e incluya los permisos AmazonSSMManagedInstanceCore.

Para obtener más información sobre los permisos de IAM necesarios para Systems Manager, consulte Additional policy considerations for managed instances.

Limitación de las llamadas a la API de Systems Manager

Si un gran volumen de instancias administradas que ejecutan SSM Agent realizan llamadas a la API UpdateInstanceInformation simultáneamente, puede que se limiten esas llamadas.

Si la llamada a la API UpdateInstanceInformation de su instancia está limitada, se mostrarán mensajes de error similares al siguiente en los registros de 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»

Siga estos pasos para solucionar problemas con el fin de evitar los errores ThrottlingException:

• Reduzca la frecuencia de las llamadas a la API.
• Implemente reintentos de error y retrocesos exponenciales cuando realice llamadas a la API.
• Escalone los intervalos de las llamadas a la API para que no se ejecuten todas al mismo tiempo.
• Solicite un aumento del tope de limitación para las llamadas a la API UpdateInstanceInformation.

Amazon EC2 no puede asumir credenciales válidas del perfil de instancia de IAM

Si Amazon EC2 no puede asumir el rol de IAM, se mostrará un mensaje similar al siguiente ejemplo en los registros de 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

Si intenta recuperar los metadatos de la instancia de EC2, también se mostrará un error similar al siguiente ejemplo:

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

Nota: En este ejemplo, profile-name es el nombre del perfil de instancia.

Para solucionar este error, compruebe la política de confianza asociada al rol de IAM. En la política, debe especificar Amazon EC2 como un servicio autorizado a asumir el rol de IAM. Actualice la política de IAM mediante la API UpdateAssumeRolePolicy de modo que se parezca a la del siguiente ejemplo:

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

Para obtener más información, consulte El documento iam/security-credentials/[role-name] indica «Code»:«AssumeRoleUnauthorizedAccess».

---