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 doit disposer d’autorisations AWS Identity and Access Management (IAM) pour appeler l’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 l’échec 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

Fenêtres

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

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

Remarque : SSM Agent est régulièrement mis à jour avec de nouvelles fonctionnalités. Il est donc recommandé de configurer des mises à jour automatisées pour SSM Agent.

Résolution

Remarque : si des erreurs surviennent lorsque vous exécutez des commandes de l’interface de la ligne de commande AWS (AWS CLI), consultez la page Résoudre les erreurs liées à AWS CLI. Vérifiez également que vous utilisez bien la version la plus récente de l’AWS CLI.

Pour utiliser les journaux de l'agent SSM afin de résoudre les problèmes, exécutez la commande ssm-cli. Puis, suivez les étapes de dépannage en fonction de votre problème.

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

En fonction de votre cas d’utilisation, effectuez les tâches suivantes.

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 »

Cette erreur se produit fréquemment lorsque vous utilisez un proxy pour les connexions Internet sortantes depuis votre instance avant de configurer l'agent SSM pour un proxy. Pour résoudre ce problème, configurez SSM Agent afin qu'il utilise 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 plus d’informations, consultez la section Pourquoi mon instance Amazon EC2 Windows génère-t-elle une erreur « Waiting for the metadata service » ?

Pour vérifier si les métadonnées sont activées pour votre instance, exécutez la commande suivante dans l'AWS CLI :

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

Remarque : Remplacez i-1234567898abcdef0 par l’ID de votre instance.

Vous recevez une sortie 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, il échoue. SSM Agent doit établir une connexion sortante avec le point de terminaison SSM : ssm.REGION.amazonaws.com à la suite des appels d'API du service Systems Manager sur le port 443.

Remarque : SSM Agent utilise les informations sur la 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 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 les 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 de sortie du groupe de sécurité 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 de VPC.
• Si les règles de la table de routage sont configurées pour utiliser un proxy pour toutes les connexions sortantes, SSM Agent n’est pas configuré pour utiliser un proxy.

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

Dans la mesure où SSM Agent n’est pas autorisé à effectuer des appels d’API UpdateInstanceInformation vers le service, il ne réussit pas à s’enregistrer comme étant en ligne sur Systems Manager.

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 vérification 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, ces appels peuvent être limités.

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

Si vous utilisez IMDSv1 pour 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 l’exemple précédent, profile-name est le nom du profil d’instance. Si vous utilisez IMDSv2, la commande précédente ne fonctionne pas. Pour plus d'informations sur la récupération de métadonnées, consultez la section Récupérer les métadonnées d'instance pour Linux et Windows.

Pour résoudre cette erreur, vérifiez la stratégie d’approbation 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 ».