Criar condições de espera em um modelo - AWS CloudFormation

Criar condições de espera em um modelo

Importante

Para recursos do Amazon EC2 e do Auto Scaling, recomendamos que você use um atributo CreationPolicy, em vez de condições de espera. Adicione um atributo CreationPolicy a esses recursos e use o script auxiliar cfn-signal para sinalizar quando um processo de criação de instância foi concluído com êxito.

Para obter mais informações, consulte CreationPolicy ou Implantar aplicativos no Amazon EC2 com o AWS CloudFormation.

Usando o recurso AWS::CloudFormation::WaitConditionHandle e o atributo CreationPolicy, é possível fazer o seguinte:

  • Coordenar a criação de recursos de pilha com outras ações de configuração que são externas à criação da pilha

  • Acompanhar o status de um processo de configuração

Por exemplo, você pode iniciar a criação de outro recurso depois que a configuração de um aplicativo é parcialmente concluída, ou você pode enviar sinais durante um processo de instalação e configuração para acompanhar seu progresso.

Usar um identificador de condição de espera

nota

Se você usar o recurso VPC endpoint, os recursos na VPC que respondem à condição de espera devem ter acesso a buckets do Amazon Simple Storage Service (Amazon S3) específicos do AWS CloudFormation. Os recursos devem enviar respostas à condição de espera para uma pre-signed URL do Amazon S3. Se eles não enviam respostas para o Amazon S3, o AWS CloudFormation não receberá uma resposta e há falha na operação de pilha. Para obter mais informações, consulte Configurar VPC endpoints VPC para o AWS CloudFormation e Exemplos de políticas de buckets para VPC endpoints do Amazon S3.

Você pode usar a condição de espera e o identificador de condição de espera para fazer com que o AWS CloudFormation pause a criação de uma pilha e espere por um sinal antes de continuar a criação da pilha. Por exemplo, talvez seja necessário fazer download dos aplicativos em uma instância do Amazon EC2 e configurá-los antes de considerar a conclusão da criação da instância do Amazon EC2.

A lista a seguir fornece um resumo de como funciona uma condição de espera com um identificador de condição de espera:

  • O AWS CloudFormation cria uma condição de espera como qualquer outro recurso. Quando o AWS CloudFormation cria uma condição de espera, ele informa o status da condição de espera como CREATE_IN_PROGRESS e aguarda até receber o número de requisito dos sinais de sucesso ou o período de tempo limite da condição de espera expirou. Se o AWS CloudFormation receber o número de requisito de sinais de sucesso antes que o período de tempo limite expire, ela continuará criando a pilha; caso contrário, ela definirá o status da condição de espera para CREATE_FAILED e reverterá a pilha.

  • A propriedade Timeout determina por quanto tempo o AWS CloudFormation aguardará o número de requisito de sinais de sucesso. Timeout é uma propriedade de limite mínimo, o que significa que o tempo limite não ocorre antes do tempo especificado, mas pode ocorrer um pouco depois. O tempo máximo que você pode especificar é 43200 segundos (12 horas).

  • Normalmente, você deseja que uma condição de espera comece imediatamente após a criação de um recurso específico, como uma instância do Amazon EC2, uma instância de banco de dados do RDS ou um grupo de Auto Scaling. Para isso, adicione o atributo DependsOn a uma condição de espera. Quando você adiciona um atributo DependsOn a uma condição de espera, especifica que essa condição será criada apenas após a criação de um recurso específico. Quando a condição de espera é criada, o AWS CloudFormation inicia o período de tempo limite e aguarda os sinais de sucesso.

  • Você também pode usar o atributo DependsOn em outros recursos. Por exemplo, talvez seja necessário que uma instância de banco de dados do RDS seja criada e que um banco de dados seja configurado nessa instância primeiro antes da criação de instâncias EC2 que usem esse banco de dados. Nesse caso, você cria uma condição de espera que tem um atributo DependsOn, que especifica a instância de banco de dados, e você cria recursos da instância EC2 que têm atributos DependsOn, que especificam a condição de espera. Isso garante que as instâncias EC2 serão criadas diretamente depois que a instância de banco de dados e a condição de espera forem concluídas.

  • O AWS CloudFormation deve receber um número especificado de sinais de sucesso para uma condição de espera antes que o status dessa condição de espera seja definido para CREATE_COMPLETE e continue criando a pilha. A propriedade Count da condição de espera especifica o número de sinais de sucesso. Se não for definido nenhum, o padrão será 1.

  • Uma condição de espera requer um identificador de condição de espera para configurar um pre-signed URL que é usado como mecanismo de sinalização. O URL pré-assinado permite que você envie um sinal sem precisar fornecer as credenciais da AWS. Você usa o pre-signed URL para sinalizar sucesso ou falha, que é encapsulado em uma instrução JSON. Para saber o formato dessa instrução JSON, consulte o Formato JSON do sinal da condição de espera.

  • Se uma condição de espera receber o número de requisito de sinais de sucesso (conforme definido na propriedade Count) antes que o tempo de espera expire, o AWS CloudFormation marcará a condição de espera como CREATE_COMPLETE e continuará criando a pilha. Caso contrário, o AWS CloudFormation fará com que a condição de espera falhe e reverterá a pilha (por exemplo, se o período de tempo limite expirar sem sinais de sucesso de requisito ou se um sinal de falha for recebido).

Para usar uma condição de espera em uma pilha:

  1. Declare um recurso AWS::CloudFormation::WaitConditionHandle no modelo da pilha. Um identificador de condição de espera não tem propriedades. No entanto, uma referência a um recurso WaitConditionHandle retorna um pre-signed URL que você pode usar para sinalizar sucesso ou falha à WaitCondition. Por exemplo:

    "myWaitHandle" : { "Type" : "AWS::CloudFormation::WaitConditionHandle", "Properties" : { } }
  2. Declare um recurso AWS::CloudFormation::WaitCondition no modelo da pilha. Um recurso WaitCondition tem duas propriedades necessárias: Handle é uma referência a um WaitConditionHandle declarado no modelo, enquanto Timeout é o número de segundos que o AWS CloudFormation aguardará. Você pode também definir a propriedade Count, que determina o número de sinais de sucesso que a condição de espera deve receber para que o AWS CloudFormation possa retomar a criação da pilha.

    Para determinar quando a condição de espera será acionada, defina um atributo DependsOn na condição de espera. Uma cláusula DependsOn cláusula associa um recurso à condição de espera. Depois que o AWS CloudFormation cria o recurso DependsOn, ele bloqueia posteriormente a criação de recursos de pilha até que um dos seguintes eventos ocorra: a) o período de tempo limite expire; b) o número de requisito de sinais de sucesso seja recebido; c) um sinal de falha seja recebido.

    Este é um exemplo de uma condição de espera que começa após a criação bem-sucedida do recurso Ec2Instance, usa o recurso myWaitHandle como WaitConditionHandle, tem um tempo limite de 4500 segundos e assume 1 como valor padrão de Count (desde que nenhuma propriedade Count seja especificada):

    "myWaitCondition" : { "Type" : "AWS::CloudFormation::WaitCondition", "DependsOn" : "Ec2Instance", "Properties" : { "Handle" : { "Ref" : "myWaitHandle" }, "Timeout" : "4500" } }
  3. Obtenha o pre-signed URL a ser usada para sinalização.

    No modelo, o pre-signed URL pode ser recuperado passando o nome lógico do recurso AWS::CloudFormation::WaitConditionHandle para a função intrínseca Ref. Por exemplo, você pode usar a propriedade UserData nos recursos AWS::EC2::Instance para passar o pre-signed URL para as instâncias do Amazon EC2, a fim de que os scripts ou os aplicativos em execução nessas instâncias possam sinalizar sucesso ou falha para o AWS CloudFormation:

    "UserData" : { "Fn::Base64" : { "Fn::Join" : [ "", ["SignalURL=", { "Ref" : "myWaitHandle" } ] ] } }

    Observação: nas ferramentas de linha de comando do AWS Management Console ou AWS CloudFormation o URL pré-assinado é exibido como ID físico do recurso de identificador de condição de espera.

  4. Selecione um método para detectar quando a pilha informará a condição de espera.

    Se você criar a pilha com notificações habilitadas, o AWS CloudFormation publicará uma notificação para cada evento de pilha no tópico especificado. Se você ou seu aplicativo se inscrever nesse tópico, você poderá monitorar as notificações do evento de criação do identificador de condição de espera e recuperará o pre-signed URL na mensagem de notificação.

    Você também poderá monitorar os eventos da pilha usando o AWS Management Console, as ferramentas da linha de comando AWS CloudFormation ou a API do AWS CloudFormation.

  5. Use o pre-signed URL para sinalizar sucesso ou falha.

    Para enviar um sinal, envie uma mensagem de solicitação HTTP usando o pre-signed URL. O método de solicitação deve ser PUT, e o cabeçalho Content-Type deve ser omitido ou uma string vazia. A mensagem de solicitação deve ser uma estrutura JSON do formulário especificado em Formato JSON do sinal da condição de espera.

    Você precisa enviar o número de sinais de sucesso especificados pela propriedade Count para que o AWS CloudFormation continue a criação da pilha. Se a propriedade Count for maior que 1, o valor UniqueId de cada sinal deverá ser exclusivo em todos os sinais enviados a uma condição de espera específica. UniqueId é uma string alfanumérica arbitrária.

    O comando Curl é uma forma de enviar um sinal. O exemplo a seguir mostra uma linha do comando Curl que sinaliza o sucesso para uma condição de espera.

    curl -T /tmp/a "https://cloudformation-waitcondition-test.s3.amazonaws.com/arn%3Aaws%3Acloudformation%3Aus-east-2%3A034017226601%3Astack%2Fstack-gosar-20110427004224-test-stack-with-WaitCondition--VEYW%2Fe498ce60-70a1-11e0-81a7-5081d0136786%2FmyWaitConditionHandle?Expires=1303976584&AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Signature=ik1twT6hpS4cgNAw7wyOoRejVoo%3D"

    em que o arquivo/tmp/a contém a seguinte estrutura JSON:

    { "Status" : "SUCCESS", "Reason" : "Configuration Complete", "UniqueId" : "ID1234", "Data" : "Application has completed configuration." }

    Este exemplo mostra uma linha do comando Curl que envia o mesmo sinal de sucesso; a única diferença é que ele envia a estrutura JSON como um parâmetro na linha de comando.

    curl -X PUT -H 'Content-Type:' --data-binary '{"Status" : "SUCCESS","Reason" : "Configuration Complete","UniqueId" : "ID1234","Data" : "Application has completed configuration."}' "https://cloudformation-waitcondition-test.s3.amazonaws.com/arn%3Aaws%3Acloudformation%3Aus-east-2%3A034017226601%3Astack%2Fstack-gosar-20110427004224-test-stack-with-WaitCondition--VEYW%2Fe498ce60-70a1-11e0-81a7-5081d0136786%2FmyWaitConditionHandle?Expires=1303976584&AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Signature=ik1twT6hpS4cgNAw7wyOoRejVoo%3D"

Formato JSON do sinal da condição de espera

Quando você sinaliza uma condição de espera, deve usar o seguinte formato JSON:

{ "Status" : "StatusValue", "UniqueId" : "Some UniqueId", "Data" : "Some Data", "Reason" : "Some Reason" }

Onde:

StatusValue deve ser um dos seguintes valores:

  • SUCCESS indica um sinal de sucesso.

  • FAILURE indica um sinal de falha e aciona uma condição de espera com falha e uma reversão de pilha.

UniqueId identifica o sinal para o AWS CloudFormation. Se a propriedade Count da condição de espera for maior que 1, o valor UniqueId deverá ser exclusivo em todos os sinais enviados de uma condição de espera; caso contrário, o AWS CloudFormation considerará o sinal uma retransmissão dos sinais enviados anteriormente com o mesmo UniqueId e ignorará o sinal.

Data é qualquer informação que você deseje enviar novamente com o sinal. O valor Data pode ser acessado chamando a função Fn:: GetAtt no modelo. Por exemplo, se você criar o valor de saída a seguir para a condição de espera mywaitcondition, poderá usar o comando aws cloudformation describe-stacks, a ação DescribeStacks ou a guia Outputs do console do CloudFormation para exibir os dados enviados pelos sinais válidos enviados ao AWS CloudFormation:

"WaitConditionData" : { "Value" : { "Fn::GetAtt" : [ "mywaitcondition", "Data" ]}, "Description" : "The data passed back as part of signalling the WaitCondition" },

A função Fn::GetAtt retorna UniqueId e Data como um par de nomes/valores em uma estrutura JSON. Veja a seguir um exemplo do atributo Data retornado pelo valor de saída WaitConditionData definido acima:

{"Signal1":"Application has completed configuration."}

Reason é uma string sem outras restrições em seu conteúdo, além da conformidade com JSON.