# Enlaces de Lambda para implementaciones de servicios de Amazon ECS Los enlaces de Lambda son funciones de Lambda que Amazon ECS invoca en etapas específicas de una implementación. Los enlaces se pueden usar para ejecutar pruebas de validación, aplicar políticas de gobernanza o implementar lógica personalizada antes de que continúe la implementación. Cuando Amazon ECS invoca su enlace, la función debe devolver un objeto JSON que contenga un campo de `hookStatus`. Opcionalmente, puede incluir `callBackDelay` para controlar el tiempo de los reintentos y `hookDetails` para pasar datos entre las invocaciones. Si la función no devuelve un `hookStatus` válido o si falla, Amazon ECS revierte la implementación. ## Valores de hookStatus Los siguientes son los valores de `hookStatus` válidos: + `SUCCEEDED`: la implementación pasa a la siguiente fase del ciclo de vida. + `FAILED`: Amazon ECS restaura la implementación a la última revisión de servicio exitosa. + `IN_PROGRESS`: Amazon ECS vuelve a invocar la función tras un retraso. De forma predeterminada, el retraso es de 30 segundos. Este valor puede personalizarse; para ello, devuelva un `callBackDelay` junto con el `hookStatus`. En el siguiente ejemplo se muestra cómo devolver un `hookStatus` con un retraso de devolución de llamada personalizado. En este ejemplo, Amazon ECS reintenta este enlace después de 60 segundos en lugar de los 30 segundos predeterminados: ``` { "hookStatus": "IN_PROGRESS", "callBackDelay": 60 } ``` ## Pase de un estado con hookDetails El campo `hookDetails` es un diccionario que puede utilizar para pasar los datos a su función de enlace de ciclo de vida. Hay dos formas de llenar el campo `hookDetails`: + **Al crear o actualizar el servicio**: defina los `hookDetails` en la configuración del enlace de ciclo de vida dentro de la definición del servicio. Amazon ECS transfiere estos datos a su función en cada invocación. Utilícelo para que sus enlaces sean reutilizables en varios servicios mediante el pase de la configuración específica para cada servicio. + **En el tiempo de ejecución, mediante las respuestas de IN\_PROGRESS**: devuelva los `hookDetails` junto con el estado `IN_PROGRESS` del enlace. Amazon ECS devuelve estos datos a su función en la siguiente invocación. Utilice este método para mantener el estado entre las invocaciones sin almacenamiento externo. En el siguiente ejemplo se muestra una configuración de enlace de ciclo de vida en una definición de servicio que pasa un nombre de bucket de S3 a la función: ``` { "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" } } ``` Cuando la función devuelve `IN_PROGRESS`, también puede incluir los `hookDetails` en la respuesta. Amazon ECS fusiona estos datos y los vuelve a pasar en la siguiente invocación. Los casos de uso más comunes incluyen el paso de contadores de métricas o ARN de recursos externos entre invocaciones. ``` { "hookStatus": "IN_PROGRESS", "callBackDelay": 30, "hookDetails": { "approvalChecked": true, "S3_BUCKET_NAME": "my-approval-bucket" } } ``` En la siguiente invocación, Amazon ECS incluye los `hookDetails` en la carga útil del evento junto con `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" } } ``` Su función puede leer los `event["hookDetails"]` para acceder a la configuración y el estado de las invocaciones anteriores. **nota** Los datos agregados en los `hookDetails` en el tiempo de ejecución solo persisten entre las invocaciones del mismo enlace en una sola implementación. Los datos no se transfieren entre diferentes enlaces dentro de la misma implementación ni entre el mismo enlace en diferentes implementaciones. ## Configuración de tiempo de espera El tiempo de espera de los enlaces de Lambda se puede configurar mediante `timeoutConfiguration`. Si la función de Lambda no devuelve `SUCCEEDED` ni `FAILED` antes de que se agote el tiempo de espera, Amazon ECS ejecuta la acción de tiempo de espera configurada. | Campo | Descripción | | --- | --- | | timeoutConfiguration.timeoutInMinutes | Tiempo máximo de espera. Intervalo válido: de 1 a 1440 (24 horas). Valor predeterminado: 1440 minutos. | | timeoutConfiguration.action | Acción que se realizará si vence el tiempo máximo de espera. Valores válidos: ROLLBACK, CONTINUE. Valor predeterminado: ROLLBACK. | ## Etapas del ciclo de vida compatibles Los enlaces de Lambda se pueden configurar en las siguientes etapas del ciclo de vida: + `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` En las implementaciones lineales y canario, los enlaces de Lambda configurados en `PRODUCTION_TRAFFIC_SHIFT` o `PRE_PRODUCTION_TRAFFIC_SHIFT` se invocan en cada paso de cambio de tráfico. Para obtener más información sobre las categorías de etapas del ciclo de vida, consulte [Enlaces de ciclo de vida para las implementaciones de servicios de Amazon ECS](deployment-lifecycle-hooks.md). ## Cargas útiles del ciclo de vida ### Estructura común de las cargas útiles Cuando Amazon ECS invoca la función de Lambda del enlace de ciclo de vida, la carga útil del evento contiene los siguientes campos de nivel superior: + `executionId`: identificador único de esta ejecución del enlace. + `lifecycleStage`: etapa actual del ciclo de vida, por ejemplo, `PRODUCTION_TRAFFIC_SHIFT`. + `resourceArn`: ARN del recurso asociado con la implementación. + `executionDetails`: objeto que contiene la información específica de la implementación que se describe en la siguiente lista. El objeto `executionDetails` contiene los siguientes campos: + `serviceArn`: el nombre de recurso de Amazon (ARN) del servicio. + `targetServiceRevisionArn`: el ARN de la revisión de servicio de destino que se está implementando. + `testTrafficWeights`: un mapa de los ARN de las revisiones de servicio con sus correspondientes porcentajes de ponderación de tráfico de prueba. + `productionTrafficWeights`: un mapa de los ARN de las revisiones de servicio con sus correspondientes porcentajes de ponderación de tráfico de producción. En el siguiente ejemplo se muestra la estructura completa del evento que recibe la función de Lambda: ``` { "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 } } } ``` ### Cargas útiles de las etapas del ciclo de vida En las siguientes secciones se muestra un ejemplo de cargas útiles para cada etapa del ciclo de vida. En estos ejemplos, la revisión de servicio verde (`9313423515462893900`) es la nueva revisión que está en implementación y la revisión de servicio azul (`1920498462936580504`) es la revisión de producción existente. #### PRE\_SCALE\_UP Esta etapa se produce antes de que Amazon ECS lance las tareas de revisión de servicio verde. La revisión de servicio verde no ha comenzado, y no se direcciona ningún tráfico hacia él. ``` { "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 Esta etapa se produce después de que Amazon ECS haya lanzado las tareas de revisión de servicio verde y estas se encuentren en buen estado. Las tareas verdes están en ejecución, pero aún no reciben tráfico. ``` { "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 Esta etapa se produce cuando Amazon ECS transfiere el tráfico de prueba a la revisión de servicio verde. Los `testTrafficWeights` muestran que la revisión verde recibe el 100 % del tráfico de prueba, mientras que la revisión azul recibe el 0 %. El tráfico de producción sigue fluyendo hacia la revisión azul. ``` { "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 Esta etapa se produce después de que Amazon ECS haya completado el cambio de tráfico de prueba. La revisión de servicio verde gestiona el 100 % del tráfico de prueba. ``` { "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": {} } } ``` #### PRE\_PRODUCTION\_TRAFFIC\_SHIFT Esta etapa se produce antes de que Amazon ECS transfiera el tráfico de producción a la revisión de servicio verde. En las implementaciones lineales y canario, esta etapa se invoca antes de cada paso de cambio de tráfico. ``` { "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 Esta etapa se produce cuando Amazon ECS transfiere el tráfico de producción a la revisión de servicio verde. Las `productionTrafficWeights` muestran que la revisión verde recibe el 100 % del tráfico de producción, mientras que la revisión azul recibe el 0 %. ``` { "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 Esta etapa se produce después de que Amazon ECS haya completado el cambio de tráfico de producción. La revisión de servicio verde se ocupa ahora de todo el tráfico de producción. ``` { "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": {} } } ``` ## Enlace de ciclo de vida durante la reversión No hay una etapa del ciclo de vida dedicada a la `ROLLBACK`. Cuando se produce una reversión, Amazon ECS vuelve a invocar los enlaces registrados en las etapas de `PRODUCTION_TRAFFIC_SHIFT` y `TEST_TRAFFIC_SHIFT` (las etapas de invocación recurrentes). Durante una reversión, los `productionTrafficWeights` en la carga útil muestran que el tráfico vuelve a la revisión azul. `targetServiceRevisionArn` sigue siendo el ARN de revisión verde porque sigue siendo el objetivo de la implementación original, a pesar de que el tráfico se aleja de él. En el ejemplo a continuación se muestra una carga útil de `PRODUCTION_TRAFFIC_SHIFT` durante una reversión. Cabe observar que la revisión azul (`1920498462936580504`) ahora recibe el 100 % del tráfico de producción, mientras que la revisión verde (`9313423515462893900`) recibe el 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 } } } ``` Para determinar si se invoca el enlace durante una reversión, controle los `productionTrafficWeights`. Si `targetServiceRevisionArn` (revisión verde) tiene un peso del 0 % y la otra revisión tiene el 100 %, la implementación está en proceso de reversión.