Wie behebe ich Probleme, wenn ich Umgebungsvariablen an meine Amazon ECS-Aufgabe übergebe?

Kurzbeschreibung

Wenn du eine Umgebungsvariable oder sensible Daten in deiner Aufgabe übergibst, erhältst du je nach Konfiguration möglicherweise einen der folgenden Fehler.

AWS Secrets Manager

„ResourceInitializationError error" or "AccessDenied error on Amazon Elastic Compute Cloud (Amazon EC2)“.

Informationen zur Behebung dieser Probleme findest du unter Wie behebe ich Probleme im Zusammenhang mit AWS-Secrets-Manager-Secrets in Amazon ECS?

Amazon Elastic Block Store (Amazon EBS)-Volumes oder -Sidecars

„ECS was unable to assume the configured ECS Infrastructure Role 'arn:aws:iam::111122223333:role/ecsInfrastructureRole'. Please verify that the role being passed has the proper trust relationship with Amazon ECS" or "ECS timed out while configuring the EBS volume attachment to your Task.“

Informationen zur Behebung dieser Probleme findest du unter Statusgründe für das Anfügen eines Amazon EBS-Volumes an Amazon ECS-Aufgaben.

Amazon Simple Storage Service (Amazon S3)

„ResourceInitializationError: failed to download env files: file download command: non empty error stream“.

Führe die folgenden Lösungsschritte durch, um dieses Problem zu beheben.

Parameter Store, eine Funktion von AWS Systems Manager

„Fetching secret data from SSM Parameter Store in region: AccessDeniedException: User: arn:aws:sts::123456789:assumed-role/ecsExecutionRole/f512996041234a63ac354214 is not authorized to perform: ssm:GetParameters on resource: arn:aws:ssm:ap-south-1:12345678:parameter/status code: 400, request id: e46b40ee-0a38-46da-aedd-05f23a41e861“. Oder „ResourceInitializationError: unable to pull secrets or registry auth: execution resource retrieval failed: unable to retrieve secrets from ssm: service call has been retried 5 time(s): RequestCanceled“.

Führe die folgenden Lösungsschritte durch, um diese Probleme zu beheben.

Hinweis: Es ist eine bewährte Sicherheitsmethode, sensible Daten in Secrets Manager-Secrets oder Parameter-Store-Parametern zu speichern.

Lösung

Hinweis: Wenn du beim Ausführen von AWS Command Line Interface (AWS CLI)-Befehlen Fehlermeldungen erhältst, findest du weitere Informationen dazu unter Problembehandlung bei der AWS CLI. Stelle außerdem sicher, dass du die neueste Version der AWS CLI verwendest.

Die Ursache des Problems ermitteln

Verwende das AWSSupport-TroubleshootECSTaskFailedToStart-Runbook in derselben AWS-Region, in der sich auch deine Amazon ECS-Cluster-Ressourcen befinden. Verwende außerdem die zuletzt fehlgeschlagene Aufgaben-ID. Wenn die fehlgeschlagene Aufgabe Teil eines Amazon ECS-Service ist, verwende die zuletzt fehlgeschlagene Aufgabe im Service. Die fehlgeschlagene Aufgabe muss während der Automatisierung in ECS:DescribeTasks sichtbar sein. Standardmäßig sind gestoppte ECS-Aufgaben 1 Stunde lang sichtbar, nachdem sie den Status Angehalten erreicht haben.

Verwende auf der Grundlage der Ergebnisse der Automatisierung einen der folgenden manuellen Schritte zur Fehlerbehebung.

Die Amazon-ECS-Aufgabenausführungsrolle verfügt nicht über die erforderlichen IAM-Berechtigungen

Wenn du Umgebungsvariablen im Parameter Store oder Secrets Manager verwendest, überprüfe die AWS-CloudTrail-Ereignisse auf die folgenden API-Aufrufe:

• GetParameters für Parameter Store
• GetSecretValue für Secrets Manager

Wenn der AccessDenied-Fehler für die Aufgabenausführungsrolle angezeigt wird, musst du der Rolle die erforderlichen Berechtigungen als Inline-Richtlinie manuell hinzufügen. Du kannst auch eine benutzerdefinierte verwaltete Richtlinie erstellen, die du der Amazon ECS-Aufgabenausführungsrolle hinzufügst.

Wenn du einen S3-Bucket verwendest, um die Umgebungsvariable als .env-Datei zu speichern, füge der Aufgabenausführungsrolle die erforderlichen Berechtigungen für Amazon S3 hinzu.

Es bestehen Probleme mit der Netzwerkkonfiguration

Wenn sich die Aufgabe in einem privaten Subnetz befindet, überprüfe die folgenden Konfigurationen:

• Die Sicherheitsgruppe für die Aufgabe oder den Service lässt ausgehenden Datenverkehr auf Port 443 zu.
• Wenn du ein NAT-Gateway verwendest, muss die Aufgabe eine Standardroute zum NAT-Gateway haben.
• Die Aufgaben verwenden die erforderlichen Virtual Private Cloud (VPC)-Endpunkte für Secrets Manager, Parameter Store oder Amazon S3.

Verwende den Befehl telnet, um die Konnektivität mit dem Systems Manager, Secrets Manager oder dem Amazon S3-Endpunkt zu überprüfen.

Überprüfe außerdem die folgenden VPC-Endpunktkonfigurationen:

• Die Sicherheitsgruppe für den VPC-Endpunkt ermöglicht ausgehenden Datenverkehr von der Aufgabe oder dem Service auf Port 443.
• Die Netzwerk-Zugriffssteuerungsliste (Netzwerk-ACL) ermöglicht ausgehenden Datenverkehr auf Port 443.
• Du hast den VPC-Endpunkt der richtigen VPC zugeordnet.
• Du hast die VPC-Attribute für DNS-Hostnamen und DNS-Auflösung aktiviert.

Wenn sich die Amazon ECS-Aufgabe in einem öffentlichen Subnetz befindet, überprüfe die folgenden Konfigurationen:

• Du hast eine öffentliche IP-Adresse für die Aufgabe aktiviert.
• Die Sicherheitsgruppe der VPC ermöglicht den ausgehenden Zugriff auf das Internet über Port 443.
• Die Netzwerk-ACL erlaubt den gesamten eingehenden und ausgehenden Datenverkehr zwischen den Subnetzen und dem Internet.

Die Anwendung kann die Umgebungsvariable nicht lesen

Um zu überprüfen, ob im Aufgabencontainer die richtigen Umgebungsvariablen befüllt sind, verwende ECS Exec, um im Container alle Umgebungsvariablen aufzulisten. Aktiviere ECS Exec und führe dann den folgenden Befehl aus, um mit dem Container zu interagieren:

aws ecs execute-command --cluster cluster-name \
    --task task-id \
    --container container-name \
    --interactive \
    --command "/bin/sh"  

Hinweis: Ersetze cluster-name durch deinen Cluster-Namen, task-id durch deine Aufgaben-ID und container-name durch deinen Container-Namen.

Beispielausgabe:

The Session Manager plugin was installed successfully. Use the AWS CLI to start a session.


Starting session with SessionId: ecs-execute-command-hlei32fctyur2bn63rhe2uraaq
sh-5.2#

Führe dann den Befehl env aus, um alle Umgebungsvariablen aufzulisten:

sh-5.2# env

Beispielausgabe:

sh-5.2# env
AWS_EXECUTION_ENV=AWS_ECS_FARGATE
AWS_DEFAULT_REGION=us-east-1
AWS_REGION=us-east-1
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
_=/usr/bin/env

Wenn du den Amazon-EC2-Starttyp verwendest, kannst du auch den Befehl „Docker exec“ verwenden, um mit dem Container zu interagieren. Gehe wie folgt vor, um „Docker exec“ zu verwenden:

1. Stelle eine Verbindung zur Container-Instance her, auf der die Aufgabe ausgeführt wird.

2. Führe den folgenden Docker-Befehl aus, um die Container-ID zu ermitteln:

   docker container ps

3. Führe den folgenden Docker-Befehl aus, um den Container zu öffnen:

   docker exec -it example-container-id bash

   Hinweis: Ersetze example-container-id durch deine Container-ID. Wähle außerdem die Shell aus, die auf der Standard-Shell des Containers basiert.

4. Führe den Befehl env im Container aus, um alle Umgebungsvariablen aufzulisten.

Stelle sicher, dass Umgebungsvariablen, die du in der Aufgabendefinition oder in der .env-Datei definiert hast, in der Variablenliste enthalten sind.

Das Format der Variablen in der Container-Definition ist falsch

Wenn du Umgebungsvariablen in der Container-Definition definierst, musst du die Umgebungsvariablen als Schlüssel-Wert-Paar-Objekte definieren:

"environment": [
    {
        "name": "variable",    
        "value": "value"
    }
]

Du musst dieses Format auch verwenden, wenn du die Umgebungsvariablen in den .env-Dateien definierst.

Die Aufgabe aktualisiert die Umgebungsvariable nicht automatisch

Die Aufgabe aktualisiert die Umgebungsvariablen im laufenden Container, den du in der .env-Datei oder dem Secret aktualisierst, nicht automatisch.

Um die aktualisierten Umgebungsvariablen zur Container-Instance hinzuzufügen, führe den folgenden update-service-Befehl aus:

aws ecs update-service --cluster example-cluster --service example-service --force-new-deployment

Hinweis: Ersetze example-cluster durch den Namen deines Clusters und example-service durch den Namen deines Service.

Wenn du Umgebungsvariablen in der Container-Definition verwendest, musst du eine neue Aufgabendefinition erstellen, um die Umgebungsvariablen zu aktualisieren. Führe dann den folgenden Befehl update-service aus, um die neue Aufgabendefinition zu verwenden, um eine neue Aufgabe zu erstellen oder den Amazon ECS-Service zu aktualisieren:

aws ecs update-service --cluster example-cluster --service example-service --task-definition family:revision

Hinweis: Ersetze example-cluster durch deinen Cluster-Namen, example-service durch deinen Service-Namen und family:revision durch deine neue Aufgabendefinition.

Wenn du Umgebungsvariablen an die Aufgabe übergibst, verwendet Amazon ECS die folgenden Konfigurationen:

• Umgebungsvariablen, die den Parameter environment in einer Container-Definition verwenden, haben Vorrang vor den Variablen in einer Umgebungsdatei.
• Wenn du mehrere Umgebungsdateien angibst und diese dieselbe Variable verwenden, werden die Dateien in der Reihenfolge ihrer Eingabe verarbeitet. Amazon ECS verwendet den ersten Wert der Variablen und ignoriert nachfolgende Werte doppelter Variablen. Es hat sich bewährt, eindeutige Variablennamen zu verwenden.
• Wenn du eine Umgebungsdatei als Container-Überschreibung angibst, verwendet Amazon ECS diese Datei und ignoriert andere Umgebungsdateien in der Container-Definition.
• Die Umgebungsvariablen stehen den PID-1-Prozessen in einem Container aus der Datei /proc/1/environ zur Verfügung. Wenn der Container mehrere Prozesse oder Initialisierungsprozesse ausführt, z. B. das Wrapper-Skript oder supervisord, dann ist die Umgebungsvariable für Nicht-PID-1-Prozesse nicht verfügbar.

Ähnliche Informationen

Übergabe sensibler Daten an einen Amazon ECS-Container