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

Breve descrizione

L’agente SSM viene eseguito sulla tua istanza gestita di Amazon Elastic Compute Cloud (Amazon EC2) ed elabora le richieste dal servizio AWS Systems Manager. L’agente SSM richiede che siano soddisfatte le seguenti condizioni:

• L’agente SSM deve connettersi agli endpoint di servizio richiesti.
• L’agente SSM richiede le autorizzazioni AWS Identity and Access Management (IAM) per eseguire le chiamate API di Systems Manager.
• Amazon EC2 deve assumere credenziali valide dal profilo dell'istanza IAM.

Se una di queste condizioni non viene soddisfatta, l’agente SSM non viene eseguito correttamente.

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

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: poiché l’agente SSM viene aggiornato frequentemente con nuove funzionalità, è consigliabile configurare gli aggiornamenti automatici.

Risoluzione

Nota: se ricevi messaggi di errore durante l'esecuzione dei comandi dell'interfaccia della linea di comando AWS (AWS CLI), consulta la sezione Risolvi gli errori di AWS CLI. Inoltre, assicurati di utilizzare la versione più recente di AWS CLI.

Per utilizzare i log dell’agente SSM per risolvere i problemi, esegui il comando ssm-cli. Quindi segui i passaggi per la risoluzione del problema.

L’agente SSM non può parlare con gli endpoint richiesti

In base al tuo caso d'uso, completa le seguenti attività.

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

Quando l’agente SSM non riesce a raggiungere il servizio di metadati, non è nemmeno in grado di individuare le informazioni sulla regione AWS, il ruolo IAM o l'ID dell'istanza di quel servizio. In questo caso, viene visualizzato un messaggio di errore nei log dell’agente SSM simile al seguente:

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

Questo errore si verifica in genere quando si utilizza un proxy per le connessioni Internet in uscita dall'istanza prima di configurare l’agente SSM per un proxy. Per risolvere questo problema, configura l’agente SSM per utilizzare un proxy.

Nelle istanze Windows, questo errore potrebbe verificarsi anche a causa di una route di rete persistente non configurata correttamente quando si utilizza un'AMI personalizzata per avviare l'istanza. È necessario verificare che il percorso per l'IP del servizio di metadati punti al gateway predefinito corretto. Per ulteriori informazioni, consulta la pagina Perché la mia istanza Amazon EC2 per Windows genera un errore del tipo “In attesa del servizio di metadati”?

Per verificare se i metadati sono attivati per la tua istanza, esegui il seguente comando nell'interfaccia a riga di comando di AWS:

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

Nota: sostituisci a i-1234567898abcdef0 il tuo ID istanza.

Riceverai un output simile al seguente esempio:

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

In questo output, “HttpEndpoint”: “enabled” indica che i metadati sono attivati per la tua istanza.

Se i metadati non sono attivati, puoi attivarli con il comando aws ec2 modify-instance-metadata-options. Per ulteriori informazioni, consulta Modifica le opzioni dei metadati delle istanze per le istanze esistenti.

L’agente SSM non può raggiungere gli endpoint del servizio Systems Manager

Se non è in grado di connettersi agli endpoint del servizio, l’agente SSM ha esito negativo. L'agente SSM deve stabilire una connessione in uscita con l'endpoint SSM: ** SSM.region.Amazonaws.com** dopo le chiamate API del servizio Systems Manager sulla porta 443.

Nota: l'agente SSM utilizza le informazioni sulla regione recuperate dal servizio di metadati dell'istanza per sostituire il valore REGION in questi endpoint.

Quando l'agente SSM non riesce a connettersi con gli endpoint di Systems Manager, nei suoi log vengono visualizzati 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 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)”

Di seguito sono riportati i motivi comuni per cui l'agente SSM non riesce a connettersi agli endpoint API di Systems Manager sulla porta 443:

• Le regole del gruppo di sicurezza in uscita dalle istanze non consentono connessioni in uscita sulla porta 443.
• Le regole del gruppo di sicurezza in ingresso e uscita degli endpoint del cloud privato virtuale (VPC) non consentono connessioni in entrata e in uscita all'endpoint dell'interfaccia VPC sulla porta 443.
• Quando l'istanza risiede in una sottorete pubblica, le regole della tabella di routing non sono configurate per indirizzare il traffico utilizzando un gateway Internet.
• Quando l'istanza risiede in una sottorete privata, le regole della tabella di routing non sono configurate per indirizzare il traffico utilizzando un gateway NAT o un endpoint VPC.
• Se le regole della tabella di routing sono configurate per utilizzare un proxy per tutte le connessioni in uscita, l'agente SSM non è configurato per utilizzare un proxy.

L'agente SSM non dispone delle autorizzazioni per eseguire le chiamate API di Systems Manager richieste

L'agente SSM non è riuscito a registrarsi come online su Systems Manager perché non è autorizzato a effettuare chiamate API UpdateInstanceInformation al servizio.

La chiamata API UpdateInstanceInformation deve mantenere una connessione con l'agente SSM in modo che il servizio sappia che l'agente SSM funziona come previsto. L'agente SSM chiama il servizio Systems Manager nel cloud ogni cinque minuti per fornire informazioni sul controllo dell’integrità. Se l'agente SSM non dispone delle autorizzazioni IAM corrette, viene visualizzato un messaggio di errore nei suoi log.

Se l'agente SSM utilizza le autorizzazioni IAM errate, viene visualizzato un errore simile al seguente:

“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 l'agente SSM non dispone di autorizzazioni IAM, viene visualizzato un errore simile al seguente:

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

Verifica che il ruolo IAM collegato all'istanza contenga le autorizzazioni necessarie per consentire a un'istanza di utilizzare le funzionalità principali del servizio Systems Manager. Oppure, se un ruolo del profilo dell'istanza non è già associato, associa 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 delle chiamate API di Systems Manager

Se un volume elevato di istanze gestite che eseguono l'agente SSM effettua chiamate API UpdateInstanceInformation simultanee, tali chiamate potrebbero essere limitate.

Se la chiamata API UpdateInstanceInformation per l’istanza è limitata, nei log dell'agente SSM vengono visualizzati messaggi di errore simili ai seguenti:

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

Utilizza i seguenti passaggi per prevenire gli errori ThrottlingException:

• Riduci la frequenza delle chiamate API.
• Ripeti i tentativi in caso di errore e implementa backoff esponenziali quando effettui le chiamate API.
• Scagliona gli intervalli delle chiamate API in modo che non vengano eseguite tutte contemporaneamente.
• Richiedi un aumento del limite in relazione alla limitazione per le chiamate API UpdateInstanceInformation.

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

Se Amazon EC2 non può assumere il ruolo IAM, viene visualizzato 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 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

Se utilizzi IMDSv1 per recuperare i metadati dall'istanza EC2, viene visualizzato anche un errore simile al seguente esempio:

# 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: nell'esempio precedente, profile-name è il nome del profilo dell'istanza. Se utilizzi IMDSv2, il comando precedente non funziona. Per ulteriori informazioni sul recupero dei metadati, consulta Recuperare i metadati delle istanze per Linux e Windows.

Per risolvere questo errore, controlla la policy di attendibilità associata al ruolo IAM. Nella policy, devi specificare Amazon EC2 come servizio autorizzato ad assumere il ruolo IAM. Aggiorna la tua policy IAM tramite l'API UpdateAssumeRolePolicy in modo che appaia simile all'esempio seguente:

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

Per ulteriori informazioni, consulta Il documento iam/security-credentials/[role-name] indica “Code”:”AssumeRoleUnauthorizedAccess”.