Wie verwende ich SSM Agent-Protokolle, um Probleme mit SSM Agent in meiner verwalteten Instance zu beheben?

Kurzbeschreibung

SSM Agent wird auf deiner verwalteten Amazon Elastic Compute Cloud (Amazon EC2)-Instance ausgeführt und verarbeitet Anfragen vom AWS Systems Manager-Service. SSM Agent erfordert, dass die folgenden Bedingungen erfüllt sind:

• SSM Agent muss eine Verbindung zu den erforderlichen Service-Endpunkten herstellen.
• SSM Agent benötigt AWS Identity and Access Management (IAM, Identitäts- und Zugriffsmanagement)-Berechtigungen, um die Systems Manager-API aufzurufen.
• Amazon EC2 muss gültige Anmeldeinformationen aus dem IAM-Instance-Profil übernehmen.

Wenn eine dieser Bedingungen nicht erfüllt ist, kann SSM Agent nicht ausgeführt werden.

Um die Ursache des SSM Agent-Fehlers zu ermitteln, überprüfe die SSM Agent-Protokolle an den folgenden Stellen:

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

Hinweis: Da SSM Agent häufig mit neuen Funktionen aktualisiert wird, empfiehlt es sich, automatische Updates für SSM Agent zu konfigurieren.

Lösung

**Anmerkung:**Wenn bei der Ausführung von AWS Command Line Interface (AWS CLI)-Befehlen Fehler auftreten, findest du weitere Informationen dazu unter Troubleshoot AWS CLI errors. Stelle außerdem sicher, dass du die neueste Version der AWS CLI verwendest.

Um SSM Agent-Protokolle zur Problembehandlung zu verwenden, führe den Befehl ssm-cli aus. Befolge die Schritte zur Problembehebung für das Problem.

SSM Agent kann mit den erforderlichen Endpunkten nicht kommunizieren

Führe je nach Anwendungsfall die folgenden Aufgaben aus.

SSM Agent kann den Metadatenservice nicht erreichen

Wenn SSM Agent den Metadaten-Service nicht erreichen kann, kann er auch die AWS-Regionsinformationen, die IAM-Rolle oder die Instance-ID von diesem Service nicht finden. In diesem Fall wird in den SSM-Agent-Protokollen eine Fehlermeldung angezeigt, die der folgenden ähnelt:

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

Dieser Fehler tritt häufig auf, wenn du einen Proxy für ausgehende Internetverbindungen von der Instance verwendest, bevor du SSM Agent für einen Proxy konfigurierst. Um dieses Problem zu beheben, konfiguriere SSM Agent so, dass er einen Proxy verwendet.

Bei Windows-Instances kann dieser Fehler auch aufgrund einer falsch konfigurierten persistenten Netzwerkroute auftreten, wenn du ein benutzerdefiniertes AMI zum Starten der Instance verwendest. Du musst überprüfen, ob die Route für die Metadatenservice-IP auf das richtige Standard-Gateway verweist. Weiter Informationen findest du unter Warum generiert meine Amazon EC2-Windows-Instance den Fehler „Waiting for the metadata service“?

Führe den folgenden Befehl in der AWS CLI aus, um zu überprüfen, ob Metadaten für die Instance aktiviert sind:

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

Hinweis: Ersetze i-1234567898abcdef0 durch deine Instance-ID.

Du erhältst eine Ausgabe, die dem folgenden Beispiel ähnelt:

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

In dieser Ausgabe gibt "HttpEndpoint": "enabled" an, dass Metadaten für die Instance aktiviert sind.

Wenn Metadaten nicht aktiviert sind, kannst du Metadaten mit dem Befehl aws ec2 modify-instance-metadata-options aktivieren. Weitere Informationen findest du unter Ändern von Optionen für Instance-Metadaten für bestehende Instances.

SSM Agent kann Systems Manager-Service-Endpunkte nicht erreichen

Wenn SSM Agent keine Verbindung zu den Service-Endpunkten herstellen kann, schlägt SSM Agent fehl. SSM Agent muss eine ausgehende Verbindung mit dem SSM-Endpunkt: ssm.REGION.amazonaws.com nach Systems Manager Service API-Aufrufen auf Port 443 herstellen.

Hinweis: SSM Agent verwendet die Regionsinformationen, die der Instance-Metadatenservice abruft, um den Wert REGION in diesen Endpunkten zu ersetzen.

Wenn SSM Agent keine Verbindung zu den Systems Manager-Endpunkten herstellen kann, werden in den SSM-Agent-Protokollen Fehlermeldungen ähnlich den folgenden angezeigt:

„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)“

Im Folgenden sind einige Gründe aufgeführt, warum SSM Agent keine Verbindung zu den Systems Manager-API-Endpunkten auf Port 443 herstellen kann:

• Die Regeln der Sicherheitsgruppe für ausgehende Instances lassen keine ausgehenden Verbindungen auf Port 443 zu.
• Sicherheitsgruppenregeln für den Ein- und Ausgang von Virtual Private Cloud (VPC)-Endpunkten lassen keine eingehenden und ausgehenden Verbindungen zum VPC-Schnittstellenendpunkt auf Port 443 zu.
• Wenn sich die Instance in einem öffentlichen Subnetz befindet, sind die Routing-Tabellenregeln nicht so konfiguriert, dass der Datenverkehr über ein Internet-Gateway geleitet wird.
• Wenn sich die Instance in einem privaten Subnetz befindet, sind die Routing-Tabellenregeln nicht so konfiguriert, dass der Datenverkehr über ein NAT-Gateway oder einen VPC-Endpunkt geleitet wird.
• Wenn Routing-Tabellenregeln so konfiguriert sind, dass sie einen Proxy für alle ausgehenden Verbindungen verwenden, ist SSM Agent für die Verwendung eines Proxys nicht konfiguriert.

SSM Agent ist nicht berechtigt, die erforderlichen Systems Manager-API-Aufrufe aufzurufen

Da SSM Agent nicht autorisiert ist, die UpdateInstanceInformation-API-Aufrufe an den Service zu tätigen, kann sich SSM Agent im Systems Manager nicht als online registrieren.

Der API-Aufruf UpdateInstanceInformation muss eine Verbindung mit SSM Agent aufrechterhalten, damit der Service weiß, dass SSM Agent erwartungsgemäß funktioniert. SSM Agent ruft den Systems Manager-Service in der Cloud alle fünf Minuten auf, um Informationen zur Zustandsprüfung bereitzustellen. Wenn SSM Agent nicht über die richtigen IAM-Berechtigungen verfügt, veröffentlicht er eine Fehlermeldung in den SSM-Agent-Protokollen.

Wenn der SSM Agent die falschen IAM-Berechtigungen verwendet, wird ein Fehler angezeigt, der dem folgenden ähnelt:

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

Wenn SSM Agent keine IAM-Berechtigungen hat, wird eine Fehlermeldung angezeigt, die der folgenden ähnelt:

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

Stelle sicher, dass die IAM-Rolle, die der Instance zugeordnet ist, die erforderlichen Berechtigungen enthält, damit eine Instance die Kernfunktionen des Systems Manager-Service nutzen kann. Oder, falls noch keine Instance-Profilrolle angehängt ist, füge eine Instance-Profilrolle hinzu und schließe AmazonSSMManagedInstanceCore-Berechtigungen ein.

Weitere Informationen zu den erforderlichen IAM-Berechtigungen für Systems Manager findest du unter Zusätzliche Richtlinienüberlegungen für verwaltete Instances.

Drosselung von Aufrufen der Systems Manager-API

Wenn eine große Anzahl verwalteter Instances, auf denen SSM Agent ausgeführt wird, gleichzeitig die API-Aufrufe UpdateInstanceInformation durchführt, werden diese Aufrufe möglicherweise gedrosselt.

Wenn der API-Aufruf UpdateInstanceInformation für die Instance gedrosselt wird, werden in den SSM Agent-Protokollen Fehlermeldungen ähnlich den folgenden angezeigt:

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

Gehe wie folgt vor, um ThrottlingException-Fehler zu vermeiden:

• Senke die Häufigkeit der API-Aufrufe.
• Implementiere Wiederholungsversuche und exponentielles Backoff bei API-Aufrufen.
• Versetze die Intervalle der API-Aufrufe so, dass sie nicht alle gleichzeitig ausgeführt werden.
• Fordere eine Erhöhung des Drosselungslimits für UpdateInstanceInformation-API-Aufrufe an.

Amazon EC2 kann keine gültigen Anmeldeinformationen aus dem IAM-Instance-Profil annehmen

Wenn Amazon EC2 die IAM-Rolle nicht übernehmen kann, wird in den SSM-Agent-Protokollen eine Meldung angezeigt, die dem folgenden Beispiel ähnelt:

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

Wenn du IMDSv1 verwendest, um Metadaten von der EC2-Instance abzurufen, wird auch ein Fehler angezeigt, der dem folgenden Beispiel ähnelt:

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

Hinweis: Im vorherigen Beispiel ist profile-name der Name des Instance-Profils. Wenn du IMDSv2 verwendest, funktioniert der vorherige Befehl nicht. Weitere Informationen zum Abrufen von Metadaten findest du unter „Abrufen von Instance-Metadaten für Linux und Windows“.

Um diesen Fehler zu beheben, überprüfe die Vertrauensrichtlinie, die der IAM-Rolle zugeordnet ist. In der Richtlinie musst du Amazon EC2 als einen Service angeben, der die IAM-Rolle übernehmen darf. Aktualisiere deine IAM-Richtlinie über die UpdateAssumeRolePolicy-API, sodass sie dem folgenden Beispiel ähnelt:

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

Weitere Informationen findest du unter Das Dokument iam/security-credentials/[role-name] gibt „Code“ :„AssumeRoleUnauthorizedAccess“ an.