# Ganchos do Lambda para implantações de serviços do Amazon ECS Os ganchos do Lambda são funções do Lambda que o Amazon ECS invoca em estágios específicos de uma implantação. É possível usar ganchos para executar testes de validação, aplicar políticas de governança ou implementar lógica personalizada antes que a implantação continue. Quando o Amazon ECS invoca seu hook, sua função deve retornar um objeto de JSON contendo um campo `hookStatus`. Opcionalmente, é possível incluir `callBackDelay` para controlar o tempo de repetição e `hookDetails` para passar dados entre invocações. Se sua função não retornar um `hookStatus` válido, ou se ela falhar, o Amazon ECS reverterá a implantação. ## Valores de hookStatus Os valores válidos de `hookStatus` são os seguintes: + `SUCCEEDED`: a implantação prossegue até o próximo estágio do ciclo de vida. + `FAILED`: o Amazon ECS reverte a implantação para a última revisão de serviço com êxito. + `IN_PROGRESS`: o Amazon ECS invoca a função novamente após um atraso. Por padrão, o atraso é de 30 segundos. É possível personalizar esse valor retornando um `callBackDelay` junto ao `hookStatus`. O exemplo a seguir mostra como retornar um `hookStatus` com um atraso de retorno de chamada personalizado. Neste exemplo, o Amazon ECS tentaria novamente esse hook em 60 segundos, em vez dos 30 segundos padrão: ``` { "hookStatus": "IN_PROGRESS", "callBackDelay": 60 } ``` ## Passagem de estado com hookDetails O campo `hookDetails` é um dicionário pode ser usado para passar dados para a sua função de hook do ciclo de vida. Há duas maneiras de preencher `hookDetails`: + **Na criação ou atualização do serviço**: defina `hookDetails` na configuração do gancho do ciclo de vida diretamente em sua definição de serviço. O Amazon ECS passa esses dados para sua função em cada invocação. Use isso para tornar seus hooks reutilizáveis em vários serviços, passando a configuração específica do serviço. + **No runtime por meio de respostas IN\_PROGRESS**: retorne `hookDetails` junto com o status `IN_PROGRESS` do gancho. O Amazon ECS passará esses dados de volta para sua função na próxima invocação. Use isso para manter o estado entre as invocações sem armazenamento externo. O exemplo a seguir mostra uma configuração de hook do ciclo de vida em uma definição de serviço que passa um nome de bucket do S3 para a função: ``` { "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" } } ``` Quando sua função retorna `IN_PROGRESS`, também será possível incluir `hookDetails` na resposta. O Amazon ECS combina esses dados e os repassa na próxima invocação. Casos de uso comuns incluem a passagem de contadores de métricas ou ARNs de recursos externos entre invocações. ``` { "hookStatus": "IN_PROGRESS", "callBackDelay": 30, "hookDetails": { "approvalChecked": true, "S3_BUCKET_NAME": "my-approval-bucket" } } ``` Na próxima invocação, o Amazon ECS inclui os `hookDetails` na carga útil do evento, junto a `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" } } ``` Sua função pode ler `event["hookDetails"]` para acessar a configuração e o estado das invocações anteriores. **nota** Os dados adicionados a `hookDetails` no runtime persistem apenas entre as invocações do mesmo hook em uma única implantação. Os dados não são transferidos entre hooks diferentes na mesma implantação ou entre o mesmo hook em diferentes implantações. ## Configuração de tempo limite Você pode configurar um tempo limite para ganchos do Lambda usando `timeoutConfiguration`. Se a função do Lambda não retornar `SUCCEEDED` ou `FAILED` antes do tempo limite expirar, o Amazon ECS executará a ação de tempo limite configurada. | Campo | Descrição | | --- | --- | | timeoutConfiguration.timeoutInMinutes | Quanto tempo esperar. Intervalo válido: 1 a 1.440 segundos (24 horas). Padrão: 1.440 minutos. | | timeoutConfiguration.action | A ação a ser executada se o tempo limite expirar. Valores válidos: ROLLBACK, CONTINUE. Padrão: ROLLBACK. | ## Estágios de ciclo de vida compatíveis Você pode configurar ganchos do Lambda nos seguintes estágios do 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` Para implantações lineares e de canário, os ganchos do Lambda configurados em `PRODUCTION_TRAFFIC_SHIFT` ou `PRE_PRODUCTION_TRAFFIC_SHIFT` são invocados em cada etapa de mudança de tráfego. Para obter mais informações sobre as categorias de estágio do ciclo de vida, consulte [Ganchos do ciclo de vida para implantações de serviços do Amazon ECS](deployment-lifecycle-hooks.md). ## Cargas úteis do ciclo de vida ### Estrutura de carga útil comum Quando o Amazon ECS invoca sua função do Lambda do hook do ciclo de vida, a carga útil do evento contém os campos de nível superior a seguir: + `executionId`: o identificador exclusivo para esta execução de gancho. + `lifecycleStage`: o estágio atual do ciclo de vida (por exemplo, `PRODUCTION_TRAFFIC_SHIFT`). + `resourceArn`: o ARN do recurso associado à implantação. + `executionDetails`: um objeto contendo as informações específicas da implantação descritas na lista a seguir. O objeto `executionDetails` contém os campos a seguir. + `serviceArn`: o nome do recurso da Amazon (ARN) do serviço. + `targetServiceRevisionArn`: o ARN da revisão do serviço de destino que está sendo implantada. + `testTrafficWeights`: um mapa dos ARNs de revisão de serviço com suas porcentagens de peso de tráfego de teste correspondentes. + `productionTrafficWeights`: um mapa dos ARNs de revisão de serviço com suas porcentagens de peso de tráfego de produção correspondentes. O exemplo a seguir mostra a estrutura completa do evento que sua função do Lambda recebe: ``` { "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 úteis do estágio do ciclo de vida As seções a seguir mostram exemplos de carga útil para cada estágio do ciclo de vida. Nesses exemplos, a revisão de serviço verde (`9313423515462893900`) é a nova revisão que está sendo implantada, e a revisão de serviço azul (`1920498462936580504`) é a revisão de produção existente. #### PRE\_SCALE\_UP Este estágio ocorre antes que o Amazon ECS inicie as tarefas de revisão de serviço verde. A revisão de serviço verde ainda não foi iniciada, e nenhum tráfego está sendo direcionado para ela. ``` { "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 Este estágio ocorre depois que o Amazon ECS inicia as tarefas de revisão do serviço verde e estas estão íntegras. As tarefas verdes estão em execução, mas ainda não estão recebendo nenhum tráfego. ``` { "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 Esse estágio ocorre quando o Amazon ECS direciona o tráfego de teste para a revisão de serviço verde. `testTrafficWeights` mostra a revisão verde recebendo 100% do tráfego de teste, enquanto a revisão azul recebe 0%. O tráfego de produção continua fluindo para a revisão 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 Esse estágio ocorre depois que o Amazon ECS conclui a mudança de tráfego de teste. A revisão do serviço verde está processando 100% do tráfego de teste. ``` { "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 Esse estágio ocorre quando o Amazon ECS muda o tráfego de produção para a revisão de serviço verde. Para implantações lineares e de canário, esse estágio é invocado antes de cada etapa de mudança de tráfego. ``` { "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 Esse estágio ocorre quando o Amazon ECS direciona o tráfego de produção para a revisão de serviço verde. `productionTrafficWeights` mostra a revisão verde recebendo 100% do tráfego de produção, enquanto a revisão azul recebe 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 Esse estágio ocorre depois que o Amazon ECS conclui a mudança de tráfego de produção. A revisão de serviço verde agora está processando todo o tráfego de produção. ``` { "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": {} } } ``` ## Hooks do ciclo de vida durante a reversão Não há um estágio de ciclo de vida de `ROLLBACK` dedicado. Quando ocorre uma reversão, o Amazon ECS invoca novamente os hooks registrados nos estágios `PRODUCTION_TRAFFIC_SHIFT` e`TEST_TRAFFIC_SHIFT` (os estágios de invocação recorrente). Durante uma reversão, `productionTrafficWeights` na carga útil mostra o tráfego voltando para a revisão azul. `targetServiceRevisionArn` continua sendo o ARN da revisão verde porque ainda é o destino da implantação original, mesmo que o tráfego esteja se afastando dele. O exemplo a seguir mostra uma carga útil de `PRODUCTION_TRAFFIC_SHIFT` durante uma métrica: Observe que a revisão azul (`1920498462936580504`) agora recebe 100% do tráfego de produção, enquanto a revisão verde (`9313423515462893900`) recebe 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 se seu hook está sendo invocado durante uma reversão, verifique `productionTrafficWeights`. Se o `targetServiceRevisionArn` (revisão verde) tiver um peso de 0% e a outra revisão tiver 100%, a implantação está sendo revertida.