Comment puis-je utiliser les journaux de SSM Agent pour résoudre les problèmes liés à SSM Agent dans mon instance gérée ?

Brève description

SSM Agent s’exécute sur votre instance Amazon Elastic Compute Cloud (Amazon EC2) gérée et traite les demandes provenant du service AWS Systems Manager. SSM Agent exige que les conditions suivantes soient remplies :

• SSM Agent doit se connecter aux points de terminaison de service requis.
• SSM Agent nécessite des autorisations AWS Identity and Access Management (IAM) pour effectuer les appels d’API Systems Manager.
• Amazon EC2 doit endosser des informations d’identification valides issues du profil d’instance IAM.

Si l’une de ces conditions n’est pas remplie, SSM Agent ne s’exécute pas correctement.

Pour identifier la cause racine de la défaillance de SSM Agent, consultez les journaux de SSM Agent aux emplacements suivants :

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

Remarque : SSM Agent fait fréquemment l’objet de mises à jour pour l’ajout de nouvelles fonctionnalités. Il est donc recommandé de configurer des mises à jour automatisées pour SSM Agent.

Résolution

Commencez par consulter les journaux pour savoir si le problème est dû à l’absence de connexions de point de terminaison, d’autorisations ou d’informations d’identification. Puis, suivez les étapes de dépannage correspondant à votre problème.

SSM Agent ne parvient pas à communiquer avec les points de terminaison requis

SSM Agent ne parvient pas à accéder au service de métadonnées

Lorsque SSM Agent ne parvient pas à accéder au service de métadonnées, il ne peut pas non plus localiser les informations de région AWS, le rôle IAM ou l’ID d’instance de ce service. Si c’est le cas, un message d’erreur similaire au suivant s’affiche dans les journaux 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 »

La plupart du temps, cette erreur provient de l’utilisation d’un proxy pour les connexions Internet sortantes depuis votre instance sans configuration de SSM Agent pour un proxy. Veillez à configurer SSM Agent pour utiliser un proxy.

Sur les instances Windows, cette erreur peut également survenir lorsque vous utilisez une AMI personnalisée pour lancer votre instance, si une route réseau persistante est mal configurée. Vous devez vérifier que la route de l’adresse IP du service de métadonnées pointe vers la bonne passerelle par défaut.

Pour vérifier si les métadonnées sont activées pour votre instance, exécutez la commande suivante dans l’interface de la ligne de commande AWS (AWS CLI). Veillez à remplacer i-1234567898abcdef0 par l’ID de votre instance :

Remarque : si des erreurs surviennent lors de l’exécution des commandes AWS CLI, vérifiez que vous utilisez bien la version la plus récente d’AWS CLI.

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

Vous recevez un résultat similaire à l'exemple suivant :

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

Dans ce résultat, ** « HttpEnpoint » : « enabled » ** indique que les métadonnées sont activées pour votre instance.

Si les métadonnées ne sont pas activées, vous pouvez les activer à l’aide de la commande aws ec2 modify-instance-metadata-options. Pour en savoir plus, consultez la section Configurer les options de métadonnées d’instance pour les instances existantes.

SSM Agent ne parvient pas à atteindre les points de terminaison du service Systems Manager

Si SSM Agent ne parvient pas à se connecter aux points de terminaison du service, SSM Agent échoue. SSM Agent doit établir une connexion sortante avec les appels d’API du service Systems Manager suivants sur le port 443 :

• Point de terminaison SSM : ssm.REGION.amazonaws.com
• Point de terminaison de messagerie EC2 : ec2messages.REGION.amazonaws.com
• Point de terminaison de messagerie SSM : ssmmessages.REGION.amazonaws.com

Remarque : SSM Agent utilise les informations de région que le service de métadonnées d’instance récupère pour remplacer la valeur REGION sur ces points de terminaison.

Lorsque SSM Agent ne parvient pas à se connecter aux points de terminaison de Systems Manager, des messages d’erreur similaires aux suivants s’affichent dans les journaux 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) »

Voici quelques raisons courantes qui empêchent SSM Agent de se connecter aux points de terminaison de l’API Systems Manager sur le port 443 :

• Les règles du groupe de sécurité de sortie d’instance n’autorisent pas les connexions sortantes sur le port 443.
• Les règles du groupe de sécurité d’entrée et de sortie du cloud privé virtuel (VPC) n’autorisent pas les connexions entrantes ni sortantes vers le point de terminaison de l’interface VPC sur le port 443.
• Lorsque l’instance se trouve dans un sous-réseau public, les règles de la table de routage ne sont pas configurées pour diriger le trafic vers une passerelle Internet.
• Lorsque l’instance se trouve dans un sous-réseau privé, les règles de la table de routage ne sont pas configurées pour diriger le trafic vers une passerelle NAT ni un point de terminaison d’un VPC.
• Si les règles de la table de routage sont configurées pour utiliser un proxy pour toutes les connexions sortantes, alors SSM Agent n’est pas configuré pour utiliser un proxy.

SSM Agent n’est pas autorisé à effectuer les appels d’API Systems Manager requis

SSM Agent n’a pas réussi à s’enregistrer comme étant en ligne sur Systems Manager, car SSM Agent n’est pas autorisé à effectuer des appels d’API UpdateInstanceInformation vers le service.

L’appel d’API UpdateInstanceInformation doit maintenir une connexion avec SSM Agent afin que le service sache que SSM Agent fonctionne comme prévu. SSM Agent appelle le service Systems Manager dans le cloud toutes les cinq minutes pour fournir des informations de surveillance de l’état. Si SSM Agent ne dispose pas des autorisations IAM appropriées, un message d’erreur s’affiche dans les journaux de SSM Agent.

Si SSM Agent utilise des autorisations IAM incorrectes, un message d’erreur similaire au suivant s’affiche :

« 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 ne dispose d’aucune autorisation IAM, un message d’erreur similaire au suivante s’affiche :

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

Vérifiez que le rôle IAM associé à l’instance contient bien les autorisations requises pour permettre à une instance d’utiliser les fonctionnalités principales du service Systems Manager. Sinon, s’il n’y a encore aucun rôle de profil d’instance associé, associez un rôle de profil d’instance en intégrant les autorisations AmazonSSMManagedInstanceCore.

Pour en savoir plus sur les autorisations IAM requises pour Systems Manager, consultez la section Considérations supplémentaires en matière de politique pour les instances gérées.

Limitation des appels d’API Systems Manager

Si un grand nombre d’instances gérées qui exécutent SSM Agent effectuent simultanément des appels d’API UpdateInstanceInformation, des limites peuvent s’appliquer sur ces appels.

Si l’appel d’API UpdateInstanceInformation pour votre instance est limité, des messages d’erreur similaires aux suivants s’affichent dans les journaux 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 »

Suivez les étapes de dépannage suivantes afin d’éviter les erreurs ThrottlingException :

• Réduisez la fréquence des appels d’API.
• Mettez en œuvre les nouvelles tentatives après erreur et le backoff exponentiel lorsque vous effectuez des appels d’API.
• Augmentez les intervalles entre les appels d’API afin qu’ils ne s’exécutent pas tous en même temps.
• Demandez une hausse du seuil de limitation pour les appels d’API UpdateInstanceInformation.

Amazon EC2 ne peut pas endosser des informations d’identification valides issues du profil d’instance IAM.

Si Amazon EC2 ne peut pas endosser le rôle IAM, un message similaire à l’exemple suivant s’affiche dans les journaux 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 vous essayez de récupérer les métadonnées de l’instance EC2, un message d’erreur similaire à l’exemple suivant s’affiche également :

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

Remarque : dans cet exemple, profile-name est le nom du profil d’instance.

Pour résoudre cette erreur, vérifiez la politique de confiance associée au rôle IAM. Dans la politique, vous devez préciser qu’Amazon EC2 est un service autorisé à endosser le rôle IAM. Mettez à jour votre politique IAM à l’aide de l’API UpdateAssumeRolePolicy afin qu’elle ressemble à l’exemple suivant :

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

Pour en savoir plus, consultez Le document iam/security-credentials/[role-name] indique « Code »:« AssumeRoleUnauthorizedAccess ».

---