Come faccio a 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 per l'Agente SSM.

Risoluzione

Innanzitutto, esamina i log e identifica se il problema è causato da connessioni endpoint mancanti, autorizzazioni mancanti o credenziali mancanti. Quindi, segui i passaggi corrispondenti per la risoluzione del tuo problema.

L'Agente SSM non può parlare con gli endpoint richiesti

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"

Il motivo più comune di questo errore è l'utilizzo di un proxy per le connessioni Internet in uscita dall'istanza senza configurare l'Agente SSM per un proxy. Assicurati di configurare 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 verificare se i metadati sono attivati per la tua istanza, esegui il seguente comando nell'interfaccia della linea di comando AWS (AWS CLI). Assicurati di sostituire i-1234567898abcdef0 con il tuo ID istanza:

Nota: se ricevi errori durante l'esecuzione dei comandi AWS CLI, assicurati di utilizzare la versione più recente di AWS CLI.

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

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 Modify instance metadata options for existing instances.

L'Agente SSM non può raggiungere gli endpoint del servizio Systems Manager

Se l'Agente SSM 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 le seguenti chiamate API del servizio Systems Manager sulla porta 443:

• Endpoint SSM: ssm.REGION.amazonaws.com
• Endpoint di messaggistica EC2: ec2messages.REGION.amazonaws.com
• Endpoint di messaggistica SSM: ssmmessages.REGION.amazonaws.com

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, vengono visualizzati messaggi di errore simili ai seguenti nei log dell'Agente SSM:

"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 alcuni motivi comuni per cui l'Agente SSM non riesce a connettersi agli endpoint dell'API 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 log dell'Agente SSM.

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 Additional policy considerations for managed instances.

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 la tua 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 di 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 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

Se provi a 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: in questo esempio, profile-name è il nome del profilo dell'istanza.

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 The iam/security-credentials/[role-name] document indicates "Code":"AssumeRoleUnauthorizedAccess".

---