Hooks do ciclo de vida Categorias de estágio do ciclo de vida Cargas úteis do ciclo de vida Hooks do ciclo de vida durante a reversão

Ganchos do ciclo de vida para implantações de serviços do Amazon ECS

Quando uma implantação é iniciada, ela progride por estágios do ciclo de vida. Cada estágio pode estar em um estado como IN_PROGRESS ou SUCCEEDED. É possível usar hooks do ciclo de vida, que são funções do Lambda que o Amazon ECS executa em seu nome em estágios específicos do ciclo de vida. Cada invocação inclui uma carga útil de JSON com informações sobre o estado atual da implantação.

Hooks do ciclo de vida

Os hooks do ciclo de vida são funções do Lambda que o Amazon ECS invoca em estágios específicos de uma implantação. É possível usar hooks para executar testes de validação, aplicar políticas de governança ou implementar etapas de aprovação manual 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 hook do ciclo de vida dentro de 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 hook. 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.

Categorias de estágio do ciclo de vida

Os estágios do ciclo de vida se encaixam em duas categorias:

Estágios de invocação única: o Amazon ECS invoca esses estágios apenas uma vez durante a implantação de um serviço:
- RECONCILE_SERVICE
- PRE_SCALE_UP
- POST_SCALE_UP
- POST_TEST_TRAFFIC_SHIFT
- POST_PRODUCTION_TRAFFIC_SHIFT
Estágios de invocação recorrente: o Amazon ECS pode invocar esses estágios várias vezes durante a implantação de um serviço, inclusive durante uma reversão:
- TEST_TRAFFIC_SHIFT
- PRODUCTION_TRAFFIC_SHIFT

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 único para esta execução de hook.
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 seus percentuais de peso de tráfego de teste correspondentes.
productionTrafficWeights: um mapa dos ARNs de revisão de serviço com seus percentuais 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": {}
  }
}

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 eTEST_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.

Convenções do documento

Como os alarmes do CloudWatch realizam a detecção de falhas de implantação

Parar implantações de serviços