Come posso utilizzare i log dell’agente SSM per risolvere i problemi della mia istanza gestita utilizzandolo?

Breve descrizione

Nota: se ricevi errori quando esegui i comandi dell'Interfaccia della linea di comando AWS (AWS CLI), consulta Risoluzione degli errori relativi a AWS CLI. Inoltre, assicurati di utilizzare la versione più recente di AWS CLI.

L’Agente SSM viene eseguito nell'istanza gestita da Amazon Elastic Compute Cloud (Amazon EC2) ed elabora le richieste del servizio AWS Systems Manager. Devi soddisfare le seguenti condizioni per utilizzare l'Agente SSM. Se non soddisfi tutte, l'Agente SSM non viene eseguito:

• L’Agente SSM deve connettersi agli endpoint di servizio richiesti.
• L’Agente SSM richiede le autorizzazioni AWS Identity and Access Management (AWS IAM) per eseguire le operazioni API di Systems Manager.
• Amazon EC2 deve recuperare credenziali valide dal profilo dell'istanza IAM. Oppure, se hai impostato la Configurazione predefinita per la gestione degli host, Amazon EC2 deve recuperare le credenziali dal ruolo predefinito che viene fornito.

Per identificare la causa principale dell'errore dell’Agente SSM, esaminane i log nelle seguenti posizioni:

• Per Linux:
  /var/log/amazon/ssm/amazon-ssm-agent.log
  /var/log/amazon/ssm/errors.log
• Per Windows:
  %PROGRAMDATA%\Amazon\SSM\Logs\amazon-ssm-agent.log
  %PROGRAMDATA%\Amazon\SSM\Logs\errors.log

Nota: è consigliabile configurare gli aggiornamenti automatici per l'Agente SSM.

Risoluzione

Per risolvere i problemi utilizzando i log dell'Agente SSM, esegui il comando ssm-cli corrispondente al sistema operativo. Quindi completa i seguenti passaggi per risolvere i problemi in base all'output.

L’Agente SSM non riesce a raggiungere il servizio di metadati

Systems Manager si basa sui metadati dell'istanza per funzionare correttamente. e può utilizzare la versione 1 o la versione 2 del servizio di metadati di istanza (IMDSv1 e IMDSv2) per accedervi. L'istanza deve essere in grado di accedere a 169.254.169.254, che è l'indirizzo IPv4 del servizio di metadati di istanza.

Quando l'Agente SSM non riesce a raggiungere il servizio di metadati, non può nemmeno recuperare la Regione AWS, il ruolo IAM o l'ID dell'istanza. Messaggi di errore simili all'esempio di seguito indicano che l'Agente SSM non riesce a raggiungere il servizio di metadati:

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

L'errore si verifica quando utilizzi un proxy per le connessioni Internet in uscita dall'istanza prima di configurare l'Agente SSM per l'utilizzo di un proxy. Per risolverlo, configura l’Agente SSM per utilizzare un proxy.

Lo stesso errore si verifica inoltre quando utilizzi un'Amazon Machine Image (AMI) personalizzata per avviare istanze Windows con route di rete statiche errate. Verifica che il percorso per l'IP del servizio di metadati punti verso il gateway predefinito corretto. Per ulteriori informazioni, consulta Come posso risolvere l'errore "Waiting for the metadata service" della mia istanza Amazon EC2 per Windows?

Per verificare se i metadati sono attivati per l'istanza, esegui questo comando AWS CLI describe-instances:

aws ec2 describe-instances --instance-ids example-id --query 'Reservations[*].Instances[*].MetadataOptions'

Nota: sostituisci example-id con l'ID della tua istanza.

Nel seguente esempio di output, "HttpEndpoint": "enabled" indica che non hai attivato i metadati per l'istanza:

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

Se non hai attivato i metadati, modifica le opzioni dei metadati dell'istanza per attivarli.

L’Agente SSM non riesce a raggiungere gli endpoint del servizio Systems Manager

Se l'Agente SSM non riesce a connettersi con gli endpoint del servizio, non può comunicare con Systems Manager. L'Agente SSM deve stabilire connessioni in uscita con l'endpoint di SSM ssm.region.amazonaws.com sulla porta 443 per eseguire le operazioni API di Systems Manager. Se devi utilizzare Gestione sessione o Esegui comando, funzionalità di AWS Systems Manager, l'Agente SSM deve inoltre stabilire connessioni con l'endpoint ssmmessages.region.amazonaws.com. Per ulteriori informazioni sui requisiti di configurazione di Amazon Virtual Private Cloud (Amazon VPC) per l'Agente SSM, consulta Migliora la sicurezza delle istanze EC2 utilizzando gli endpoint VPC per Systems Manager.

Nota: l'Agente SSM recupera la Regione dal servizio di metadati di istanza e la utilizza per creare l'URL dell'endpoint.

Quando l'Agente SSM non riesce a connettersi con gli endpoint di Systems Manager, nei suoi log vedi messaggi di errore simili ai seguenti:

"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 [IP_ADDRESS]: i/o timeout"

Per istruzioni sulla risoluzione di questo errore, consulta Come posso risolvere l’errore "RequestError: send request failed caused by:" che compare nei log dell'Agente SSM?

Se il problema persiste, segui le istruzioni riportate in: Perché Systems Manager non mostra la mia istanza Amazon EC2 come istanza gestita?

L'Agente SSM non ha le autorizzazioni per eseguire le chiamate API di Systems Manager richieste

L'Agente SSM non è riuscito a registrarsi come online in Systems Manager perché non è autorizzato a effettuare chiamate API UpdateInstanceInformation al servizio. Per ulteriori informazioni, consulta Operazioni API relative all'istanza del namespace ssm:*.

La chiamata API UpdateInstanceInformation deve mantenere una connessione con l'Agente SSM in modo che il servizio sappia che l'agente funziona correttamente. L'Agente SSM chiama il servizio Systems Manager nel cloud ogni cinque minuti per fornire informazioni sul controllo dell’integrità.

Se utilizza le autorizzazioni IAM errate, ricevi un errore simile al seguente messaggio di esempio:

"ERROR [instanceID=i-12345] [HealthCheck] error when calling AWS APIs. error details - AccessDeniedException: User: arn:aws:sts::123:assumed-role/123 /i-123456 is not authorized to perform: ssm:UpdateInstanceInformation on resource: arn:aws:ec2:ap-southeast-2:1234567:instance/i-123456 status code: 400, request id: 12345678-1234-1234567 INFO [instanceID=i-1234] [HealthCheck] increasing error count by 1"

Se l'Agente SSM non ha le autorizzazioni IAM, ricevi un errore simile al seguente messaggio di esempio:

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

Verifica che il ruolo IAM collegato all'istanza includa le autorizzazioni della policy gestita da AWS AmazonSSMManagedInstanceCore. Se il campo è vuoto, collega un ruolo del profilo dell'istanza e includi le autorizzazioni AmazonSSMManagedInstanceCore.

Per ulteriori informazioni sulle autorizzazioni IAM richieste per Systems Manager, consulta Considerazioni aggiuntive sulle policy per le istanze gestite.

Limitazione (della larghezza di banda della rete) delle chiamate API di Systems Manager

Se più istanze gestite chiamano contemporaneamente l'operazione API UpdateInstanceInformation, Systems Manager potrebbe limitare la larghezza di banda della rete di tali chiamate.

Messaggi di errore simili all'esempio di seguito indicano che Systems Manager ha limitato la larghezza di banda della rete delle operazioni API UpdateInstanceInformation per l'istanza:

"INFO [HealthCheck] HealthCheck reporting agent health. ERROR [HealthCheck] error when calling AWS APIs. error details - ThrottlingException: Rate exceeded status code: 400, request id: 12345-12345-1234 INFO [HealthCheck] increasing error count by 1"

Utilizza i seguenti passaggi per prevenire gli errori "ThrottlingException":

• Riduci la frequenza delle chiamate API.
• Se hai personalizzato il parametro HealthFrequencyMinutes, ripristinalo all'intervallo predefinito di cinque minuti.
• Scagliona gli intervalli delle chiamate API in modo che non vengano eseguite tutte contemporaneamente.

Se continui a ricevere errori "ThrottlingException" dopo aver intrapreso le precedenti azioni di risoluzione dei problemi, richiedi un aumento della quota di utilizzo dei nodi gestiti. Per istruzioni, consulta Quote di servizio AWS. Per ulteriori informazioni, consulta Quote di servizio per i nodi gestiti.

Importante: quando aumenti la quota di servizio, all'account viene addebitato un costo. Per ulteriori informazioni, consulta Prezzi di AWS Systems Manager.

Amazon EC2 non può assumere credenziali valide dal profilo dell'istanza IAM

Se Amazon EC2 non può assumere il ruolo IAM, ricevi un messaggio simile al seguente esempio nei log dell'Agente SSM:

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

Se utilizzi IMDSv1 per recuperare i metadati dall'istanza, ricevi un messaggio che include il seguente esempio:

"EC2 cannot assume the role example-instance-profile-name. Please see documentation at https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_iam-ec2.html#troubleshoot_iam-ec2_errors-info-doc."

È consigliabile utilizzare IMDSv2. Tuttavia, se utilizzi IMDSv2, questo comando non funziona:

# curl http://169.254.169.254/latest/meta-data/iam/security-credentials/example=instanceprofile-name

Nota: nel comando precedente example-instance-profile-name è il nome del profilo dell'istanza.

Per ulteriori informazioni sull'accesso ai metadati dell'istanza, consulta Accesso ai metadati dell'istanza per un'istanza EC2.

Per risolvere questi errori, controlla la policy di attendibilità collegata al ruolo IAM. Nella policy specifica Amazon EC2 come servizio autorizzato ad assumere il ruolo IAM. La policy aggiornata dovrebbe essere simile al seguente esempio:

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

Dopo aver aggiornato la policy di attendibilità, attendi il successivo aggiornamento delle credenziali pianificato automaticamente. Per applicare immediatamente la modifica, dissocia e riassocia il profilo dell'istanza oppure interrompila e riavviala.

Per aggiornare la policy di attendibilità a livello di codice, utilizza l'API UpdateAssumeRolePolicy. Per ulteriori informazioni, consulta Il documento iam/security-credentials/[role-name] indica "Code":"AssumeRoleUnauthorizedAccess".