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

Kurzbeschreibung

SSM Agent wird auf Ihrer 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)-Berechtigungen, um die Systems Manager-API-Aufrufe aufzurufen.
• Amazon EC2 muss gültige Anmeldeinformationen aus dem IAM-Instance-Profil annehmen.

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

Um die Ursache des SSM Agent-Fehlers zu ermitteln, überprüfen Sie 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 der SSM Agent häufig mit neuen Funktionen aktualisiert wird, empfiehlt es sich, automatische Updates für SSM Agent zu konfigurieren.

Lösung

Überprüfen Sie zunächst die Protokolle und stellen Sie fest, ob das Problem durch fehlende Endpunktverbindungen, fehlende Berechtigungen oder fehlende Anmeldeinformationen verursacht wird. Lesen Sie dann die entsprechenden Schritte zur Fehlerbehebung für Ihr Problem.

SSM Agent kann mit den erforderlichen Endpunkten nicht kommunizieren

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“

Der häufigste Grund für diesen Fehler ist die Verwendung eines Proxys für ausgehende Internetverbindungen von Ihrer Instance aus, ohne den SSM Agent für einen Proxy zu konfigurieren. Stellen Sie sicher, dass der SSM Agent so konfiguriert ist, dass er einen Proxy verwendet.

Bei Windows-Instances kann dieser Fehler auch aufgrund einer falsch konfigurierten persistenten Netzwerkroute auftreten, wenn Sie ein benutzerdefiniertes AMI zum Starten Ihrer Instance verwenden. Sie müssen überprüfen, ob die Route für die Metadatendienst-IP auf das richtige Standard-Gateway verweist.

Um zu überprüfen, ob Metadaten für Ihre Instance aktiviert sind, führen Sie den folgenden Befehl in der AWS Command Line Interface (AWS CLI) aus. Achten Sie darauf, i-1234567898abcdef0 durch Ihre Instance-ID zu ersetzen:

Hinweis: Wenn beim Ausführen von Befehlen über AWS CLI Fehler auftreten, stellen Sie sicher, dass Sie die neueste Version von AWS CLI verwenden.

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

Sie erhalten eine Ausgabe wie die folgende:

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

In dieser Ausgabe gibt „HttpEndpoint“: „enabled“ an, dass Metadaten für Ihre Instance aktiviert sind.

Wenn Metadaten nicht aktiviert sind, können Sie sie mit dem Befehl aws ec2 modify-instance-metadata-options aktivieren. Weitere Informationen finden Sie 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 den folgenden Systems Manager-Dienst-API-Aufrufen auf Port 443 herstellen:

• SSM-Endpunkt: ssm.REGION.amazonaws.com
• EC2-Messaging-Endpunkt: ec2messages.REGION.amazonaws.com
• SSM-Messaging-Endpunkt: ssmmessages.REGION.amazonaws.com

Hinweis: SSM Agent verwendet die Regionsinformationen, die der Instance-Metadatenservice abruft, um den REGION-Wert 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 häufige 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 ausgehenden Instance 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

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

Der API-Aufruf UpdateInstanceInformation muss eine Verbindung mit SSM Agent aufrechterhalten, damit der Dienst 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, wird in den SSM Agent-Protokollen eine Fehlermeldung angezeigt.

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“

Stellen Sie 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ügen Sie eine Instance-Profilrolle hinzu und schließen Sie AmazonSSMManagedInstanceCore-Berechtigungen ein.

Weitere Informationen zu den erforderlichen IAM-Berechtigungen für Systems Manager finden Sie 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 UpdateInstanceInformationder für Ihre Instanz 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“

Gehen Sie wie folgt vor, um ThrottlingException-Fehler zu vermeiden:

• Senken Sie die Häufigkeit der API-Aufrufe.
• Implementieren Sie Wiederholungsversuche und exponentielles Backoff bei API-Aufrufen.
• Versetzen Sie die Intervalle der API-Aufrufe so, dass sie nicht alle gleichzeitig ausgeführt werden.
• Fordern Sie 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 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

Wenn Sie versuchen, 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:**In diesem Beispiel ist profile-name der Name des Instance-Profils.

Um diesen Fehler zu beheben, überprüfen Sie die Vertrauensrichtlinie, die der IAM-Rolle zugeordnet ist. In der Richtlinie müssen Sie Amazon EC2 als einen Service angeben, der die IAM-Rolle übernehmen darf. Aktualisieren Sie Ihre 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 finden Sie unter Das Dokument iam/security-credentials/[role-name] gibt „Code“ :„AssumeRoleUnauthorizedAccess“ an.

---