Lambda-Hooks für Amazon ECS-Servicebereitstellungen

Lambda-Hooks sind Lambda-Funktionen, die Amazon ECS in bestimmten Phasen einer Bereitstellung aufruft. Sie können Hooks verwenden, um Validierungstests durchzuführen, Governance-Richtlinien durchzusetzen oder benutzerdefinierte Logik zu implementieren, bevor die Bereitstellung fortgesetzt wird.

Wenn Amazon ECS Ihren Hook aufruft, muss Ihre Funktion ein JSON-Objekt zurückgeben, das eine hookStatus Feld. Sie können optional Folgendes einschließen callBackDelay um das Timing der Wiederholungsversuche zu steuern und hookDetails um Daten zwischen Aufrufen zu übergeben. Wenn Ihre Funktion keinen gültigen Wert zurückgibt hookStatus, oder wenn es fehlschlägt, setzt Amazon ECS die Bereitstellung zurück.

HookStatus-Werte

Die folgenden sind gültig hookStatus Werte:

• SUCCEEDED - Die Bereitstellung wird bis zur nächsten Lebenszyklusphase fortgesetzt.

• FAILED — Amazon ECS setzt die Bereitstellung auf die letzte erfolgreiche Service-Revision zurück.

• IN_PROGRESS — Amazon ECS ruft die Funktion nach einer Verzögerung erneut auf. In der Standardeinstellung beträgt die Verzögerung 30 Sekunden. Sie können diesen Wert anpassen, indem Sie eine zurückgeben callBackDelay neben dem hookStatus.

Das folgende Beispiel zeigt, wie ein hookStatus mit einer benutzerdefinierten Callback-Verzögerung zurückgegeben wird. In diesem Beispiel versucht Amazon ECS den Hook nach 60 Sekunden statt nach den standardmäßigen 30 Sekunden erneut:

{
    "hookStatus": "IN_PROGRESS",
    "callBackDelay": 60
}
    

Status mit HookDetails übergeben

Das hookDetails Feld ist ein Wörterbuch, mit dem Sie Daten an Ihre Lifecycle-Hook-Funktion übergeben können. Es gibt zwei Möglichkeiten, Daten auszufüllen hookDetails:

• Bei der Erstellung oder Aktualisierung des Dienstes - Definieren hookDetails in der Lifecycle-Hook-Konfiguration innerhalb Ihrer Servicedefinition. Amazon ECS übergibt diese Daten bei jedem Aufruf an Ihre Funktion. Verwenden Sie dies, um Ihre Hooks für mehrere Dienste wiederverwendbar zu machen, indem Sie eine dienstspezifische Konfiguration übergeben.

• Zur Laufzeit über IN_PROGRESS-Antworten - Rückkehr hookDetails neben dem IN_PROGRESS Hakenstatus. Amazon ECS übergibt diese Daten beim nächsten Aufruf an Ihre Funktion zurück. Verwenden Sie dies, um den Status zwischen Aufrufen ohne externen Speicher beizubehalten.

Das folgende Beispiel zeigt eine Lifecycle-Hook-Konfiguration in einer Servicedefinition, die einen S3-Bucket-Namen an die Funktion übergibt:

{
    "hookTargetArn": "arn:aws:lambda:us-west-2:123456789012:function:my-approval-hook",
    "roleArn": "arn:aws:iam::123456789012:role/ecs-lambda-invoke-role",
    "lifecycleStages": [
        "POST_TEST_TRAFFIC_SHIFT"
    ],
    "hookDetails": {
        "S3_BUCKET_NAME": "my-approval-bucket"
    }
}
    

Wenn Ihre Funktion zurückkehrt IN_PROGRESS, kannst du auch einbeziehen hookDetails in der Antwort. Amazon ECS führt diese Daten zusammen und gibt sie beim nächsten Aufruf zurück. Zu den häufigsten Anwendungsfällen gehört die Weitergabe von Metrikzählern oder ARNs externer Ressourcen zwischen Aufrufen.

{
    "hookStatus": "IN_PROGRESS",
    "callBackDelay": 30,
    "hookDetails": {
        "approvalChecked": true,
        "S3_BUCKET_NAME": "my-approval-bucket"
    }
}
    

Beim nächsten Aufruf beinhaltet Amazon ECS die hookDetails in der Event-Nutzlast nebenan executionDetails:

{
  "executionId": "e8d5a28f-eb01-4f3c-9454-a30ba6dc54bc",
  "lifecycleStage": "POST_TEST_TRAFFIC_SHIFT",
  "resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
  "executionDetails": {
    "serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
    "targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
    "testTrafficWeights": {},
    "productionTrafficWeights": {}
  },
  "hookDetails": {
    "approvalChecked": true,
    "S3_BUCKET_NAME": "my-approval-bucket"
  }
}
    

Deine Funktion kann lesen event["hookDetails"] um auf die Konfiguration und den Status früherer Aufrufe zuzugreifen.

Anmerkung

Daten wurden hinzugefügt hookDetails zur Laufzeit bestehen nur zwischen Aufrufen desselben Hooks innerhalb einer einzelnen Bereitstellung. Daten werden nicht zwischen verschiedenen Hooks innerhalb derselben Bereitstellung oder zwischen demselben Hook in verschiedenen Bereitstellungen übertragen.

Timeout-Konfiguration

Sie können einen Timeout für Lambda-Hooks wie folgt konfigurieren timeoutConfiguration. Wenn die Lambda-Funktion nicht zurückkehrt SUCCEEDED oder FAILED bevor das Timeout abläuft, ergreift Amazon ECS die konfigurierte Timeout-Aktion.

Feld	Description
timeoutConfiguration.timeoutInMinutes	Wie lange soll ich warten? Gültiger Bereich: 1 bis 1.440 (24 Stunden). Standard: 1.440 Minuten.
timeoutConfiguration.action	Die Aktion, die ausgeführt werden soll, wenn das Timeout abläuft. Zulässige Werte: ROLLBACK, CONTINUE. Standard: ROLLBACK.

Unterstützte Lebenszyklusphasen

Sie können Lambda-Hooks in den folgenden Lebenszyklusphasen konfigurieren:

• RECONCILE_SERVICE

• PRE_SCALE_UP

• POST_SCALE_UP

• TEST_TRAFFIC_SHIFT

• POST_TEST_TRAFFIC_SHIFT

• PRE_PRODUCTION_TRAFFIC_SHIFT

• PRODUCTION_TRAFFIC_SHIFT

• POST_PRODUCTION_TRAFFIC_SHIFT

Für lineare und kanarische Bereitstellungen werden Lambda-Hooks konfiguriert unter PRODUCTION_TRAFFIC_SHIFT oder PRE_PRODUCTION_TRAFFIC_SHIFT werden bei jeder Verkehrsverlagerung aufgerufen.

Weitere Informationen zu den Kategorien der Lebenszyklusphasen finden Sie unter Lebenszyklus-Hooks für Amazon-ECS-Servicebereitstellungen.

Lebenszyklus-Nutzdaten

Gängige Nutzdatenstruktur

Wenn Amazon ECS Ihre Lifecycle-Hook-Lambda-Funktion aufruft, enthält die Event-Payload die folgenden Felder der obersten Ebene:

• executionId — Die eindeutige Kennung für diese Hook-Ausführung.

• lifecycleStage - Die aktuelle Lebenszyklusphase (zum Beispiel PRODUCTION_TRAFFIC_SHIFT).

• resourceArn — Der ARN der Ressource, die mit der Bereitstellung verknüpft ist.

• executionDetails — Ein Objekt, das die in der folgenden Liste beschriebenen bereitstellungsspezifischen Informationen enthält.

Das executionDetails-Objekt enthält die folgenden Felder:

• serviceArn – Der Amazon-Ressourcenname (ARN) des Service.

• targetServiceRevisionArn – Der ARN der Ziel-Service-Revision, die bereitgestellt wird.

• testTrafficWeights – Eine Zuordnung der ARNs der Service-Revision zu den entsprechenden prozentualen Gewichtsanteilen für den Test-Datenverkehr.

• productionTrafficWeights – Eine Zuordnung der ARNs der Service-Revision zu den entsprechenden prozentualen Gewichtsanteilen für den Produktionsdatenverkehr.

Das folgende Beispiel zeigt die vollständige Eventstruktur, die Ihre Lambda-Funktion erhält:

{
  "executionId": "f4fcae0f-9bec-41c6-ba87-0eaa0cef8af5",
  "lifecycleStage": "PRODUCTION_TRAFFIC_SHIFT",
  "resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
  "executionDetails": {
    "serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
    "targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
    "testTrafficWeights": {},
    "productionTrafficWeights": {
      "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900": 100,
      "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/1920498462936580504": 0
    }
  }
}
      

Lebenszyklusphasen-Nutzdaten

Die folgenden Abschnitte zeigen Beispiel-Payloads für jede Lebenszyklusphase. In diesen Beispielen ist die grüne Service-Revision (9313423515462893900) ist die neue Revision, die bereitgestellt wird, und die blaue Service-Revision (1920498462936580504) ist die bestehende Produktionsrevision.

PRE_SCALE_UP

Diese Phase findet statt, bevor Amazon ECS die Revisionsaufgaben für den grünen Service startet. Die Green-Service-Revision wurde noch nicht gestartet, und es wird kein Datenverkehr dorthin weitergeleitet.

{
  "executionId": "e8d5a28f-eb01-4f3c-9454-a30ba6dc54bc",
  "lifecycleStage": "PRE_SCALE_UP",
  "resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
  "executionDetails": {
    "serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
    "targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
    "testTrafficWeights": {},
    "productionTrafficWeights": {}
  }
}
        

POST_SCALE_UP

Diese Phase tritt ein, nachdem Amazon ECS die Green Service Revision-Aufgaben gestartet hat und sie fehlerfrei sind. Die grünen Aufgaben werden ausgeführt, empfangen aber noch keinen Datenverkehr.

{
  "executionId": "8b095b05-7bb0-4c56-a223-a3f61f4f9295",
  "lifecycleStage": "POST_SCALE_UP",
  "resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
  "executionDetails": {
    "serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
    "targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
    "testTrafficWeights": {},
    "productionTrafficWeights": {}
  }
}
        

TEST_TRAFFIC_SHIFT

Diese Phase tritt ein, wenn Amazon ECS den Testverkehr auf die grüne Service-Revision umleitet. Das testTrafficWeights zeigt an, dass die grüne Revision 100% des Testverkehrs erhält, während die blaue Revision 0% erhält. Der Verkehr aus der Produktion fließt weiterhin zur blauen Version.

{
  "executionId": "779085de-ab47-42bc-84ad-41f9914a8643",
  "lifecycleStage": "TEST_TRAFFIC_SHIFT",
  "resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
  "executionDetails": {
    "serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
    "targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
    "testTrafficWeights": {
      "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900": 100,
      "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/1920498462936580504": 0
    },
    "productionTrafficWeights": {}
  }
}
        

POST_TEST_TRAFFIC_SHIFT

Diese Phase findet statt, nachdem Amazon ECS die Testverkehrsverlagerung abgeschlossen hat. Die Green Service Revision wickelt 100% des Testverkehrs ab.

{
  "executionId": "3a0345ba-b029-404b-890d-7da2a4b266aa",
  "lifecycleStage": "POST_TEST_TRAFFIC_SHIFT",
  "resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
  "executionDetails": {
    "serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
    "targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
    "testTrafficWeights": {},
    "productionTrafficWeights": {}
  }
}
        

VERKEHRSSCHICHT VOR DER PRODUKTION

Diese Phase findet statt, bevor Amazon ECS den Produktionsdatenverkehr auf die grüne Service-Revision umleitet. Bei linearen und kanarischen Bereitstellungen wird diese Phase vor jedem Schritt der Verkehrsverlagerung aufgerufen.

{
  "executionId": "a2b3c4d5-e6f7-8901-abcd-ef1234567890",
  "lifecycleStage": "PRE_PRODUCTION_TRAFFIC_SHIFT",
  "resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
  "executionDetails": {
    "serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
    "targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
    "testTrafficWeights": {},
    "productionTrafficWeights": {
      "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900": 0,
      "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/1920498462936580504": 100
    }
  }
}
        

PRODUCTION_TRAFFIC_SHIFT

Diese Phase tritt ein, wenn Amazon ECS den Produktionsdatenverkehr auf die Version „Green Service“ umstellt. Das productionTrafficWeights zeigt, dass die grüne Revision 100% des Produktionsverkehrs erhält, während die blaue Revision 0% erhält.

{
  "executionId": "f4fcae0f-9bec-41c6-ba87-0eaa0cef8af5",
  "lifecycleStage": "PRODUCTION_TRAFFIC_SHIFT",
  "resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
  "executionDetails": {
    "serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
    "targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
    "testTrafficWeights": {},
    "productionTrafficWeights": {
      "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900": 100,
      "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/1920498462936580504": 0
    }
  }
}
        

POST_PRODUCTION_TRAFFIC_SHIFT

Diese Phase tritt ein, nachdem Amazon ECS die Verlagerung des Produktionsverkehrs abgeschlossen hat. Die Revision des grünen Dienstes wickelt jetzt den gesamten Produktionsverkehr ab.

{
  "executionId": "5f40ed04-7e54-437d-b95d-98bc872fec49",
  "lifecycleStage": "POST_PRODUCTION_TRAFFIC_SHIFT",
  "resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
  "executionDetails": {
    "serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
    "targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
    "testTrafficWeights": {},
    "productionTrafficWeights": {}
  }
}
        

Der Lebenszyklus hängt beim Rollback ab

Es gibt keinen dedizierten ROLLBACK Phase des Lebenszyklus. Wenn ein Rollback stattfindet, ruft Amazon ECS erneut Hooks auf, die bei der PRODUCTION_TRAFFIC_SHIFT und TEST_TRAFFIC_SHIFT Stufen (die wiederkehrenden Aufrufphasen). Während eines Rollbacks wird productionTrafficWeights zeigt in der Nutzlast, wie der Verkehr wieder zur blauen Version wechselt.

Das targetServiceRevisionArn bleibt der ARN der grünen Revision, da er immer noch das Ziel der ursprünglichen Bereitstellung ist, obwohl sich der Verkehr von ihm weg verlagert.

Das folgende Beispiel zeigt eine PRODUCTION_TRAFFIC_SHIFT Nutzlast während eines Rollbacks. Beachten Sie, dass die blaue Revision (1920498462936580504) erhält jetzt 100% des Produktionsverkehrs, während die grüne Version (9313423515462893900) erhält 0%:

{
  "executionId": "70073435-cb99-457f-b900-6ee1dcad05ec",
  "lifecycleStage": "PRODUCTION_TRAFFIC_SHIFT",
  "resourceArn": "arn:aws:ecs:us-west-2:123456789012:service-deployment/my-cluster/my-service/EZe5RNVLH6PPzHXINuP28",
  "executionDetails": {
    "serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/my-cluster/my-service",
    "targetServiceRevisionArn": "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900",
    "testTrafficWeights": {},
    "productionTrafficWeights": {
      "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/9313423515462893900": 0,
      "arn:aws:ecs:us-west-2:123456789012:service-revision/my-cluster/my-service/1920498462936580504": 100
    }
  }
}
    

Um festzustellen, ob Ihr Hook während eines Rollbacks aufgerufen wird, überprüfen Sie das productionTrafficWeights. Wenn der targetServiceRevisionArn (grüne Revision) hat eine Gewichtung von 0% und die andere Revision hat 100%, wird die Bereitstellung rückgängig gemacht.