# Criar condições de espera em um modelo do CloudFormation Este tópico explica como criar uma condição de espera em um modelo para coordenar a criação de recursos de pilha ou acompanhar o progresso 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. Quando o CloudFormation cria uma pilha que inclui uma condição de espera: + Ele cria uma condição de espera como qualquer outro recurso e define o status da condição de espera como `CREATE_IN_PROGRESS`. + O CloudFormation espera até receber o número necessário de sinais de sucesso ou até que o período de tempo limite da condição de espera seja atingido. + Se ele receber o número necessário de sinais de sucesso antes que o período de tempo limite seja atingido: + Espere que o status da condição mude para `CREATE_COMPLETE` + A criação da pilha continua + Se o tempo limite for atingido ou um sinal de falha for recebido: + Espere que o status da condição mude para `CREATE_FAILED` + Reverter a pilha **Importante** Para recursos do Amazon EC2 e do Auto Scaling, recomendamos usar 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 o atributo [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-attribute-creationpolicy.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-attribute-creationpolicy.html). **nota** Se você usar o AWS PrivateLink, os recursos do VPC que respondem a condições de espera deverão ter acesso aos buckets do Amazon Simple Storage Service (Amazon S3) específicos do CloudFormation. Recursos devem enviar respostas à condição de espera para um URL pré-assinado do Amazon S3. Se não puderem enviar respostas para o Amazon S3, o CloudFormation não receberá uma resposta e há falha na operação de pilha. Para obter mais informações, consulte [Acessar o CloudFormation usando um endpoint de interface (AWS PrivateLink)](vpc-interface-endpoints.md) e [Controlar o acesso a partir de VPC endpoints com políticas de bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies-vpc-endpoint.html). **Topics** + [Criar uma condição de espera no modelo](#creating-wait-condition) + [Sintaxe de sinal da condição de espera](#wait-condition-signal-syntax) + [Acessar dados de sinal](#wait-condition-access-signal-data) ## Criar uma condição de espera no modelo **1. Processamento de condição de espera** Você começa definindo um recurso [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-waitconditionhandle.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-waitconditionhandle.html) no modelo da pilha. Esse recurso gera o URL pré-assinado necessário para enviar sinais. Isso permite que você envie um sinal sem precisar fornecer as suas credenciais da AWS. Por exemplo: ``` Resources: MyWaitHandle: Type: AWS::CloudFormation::WaitConditionHandle ``` **2. Condição de espera** Depois, você define um recurso [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-waitcondition.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-waitcondition.html) no modelo da pilha. A estrutura básica de um recurso `AWS::CloudFormation::WaitCondition` é assim: ``` MyWaitCondition: Type: AWS::CloudFormation::WaitCondition Properties: Handle: String Timeout: String Count: Integer ``` O recurso `AWS::CloudFormation::WaitCondition` tem duas propriedades obrigatórias e uma propriedade opcional. + `Handle` (obrigatório): uma referência a um `WaitConditionHandle` declarado no modelo. + `Timeout` (obrigatório): o número de segundos que o CloudFormation deve esperar até o número necessário de sinais ser recebido. `Timeout` é uma propriedade de limite mínimo, o que significa que o tempo limite não ocorre antes do tempo especificado, mas pode ocorrer logo depois. O tempo máximo que você pode especificar é 43200 segundos (12 horas). + `Count` (opcional): o número de sinais de sucesso que o CloudFormation deve receber antes de definir o status dessa condição de espera como `CREATE_COMPLETE` e continuar criando a pilha. Se não for especificado, o valor padrão é 1. Normalmente, você quer que uma condição de espera comece imediatamente após a criação de um determinado recurso. Para isso, adicione o atributo `DependsOn` a uma condição de espera. Quando você adiciona um atributo `DependsOn` a uma condição de espera, o CloudFormation primeiro cria o recurso no atributo `DependsOn` e depois cria a condição de espera. Para obter mais informações, consulte o atributo [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-attribute-dependson.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-attribute-dependson.html). O seguinte exemplo ilustra uma condição de espera que: + Começa após a criação bem-sucedida do recurso `MyEC2Instance` + Usa o recurso `MyWaitHandle` como `WaitConditionHandle` + Tem um tempo limite de 4.500 segundos + Tem a `Count` padrão de 1 (já que nenhuma propriedade `Count` está especificada) ``` MyWaitCondition: Type: AWS::CloudFormation::WaitCondition DependsOn: MyEC2Instance Properties: Handle: !Ref MyWaitHandle Timeout: '4500' ``` **3. Enviar um sinal** Para sinalizar sucesso ou falha para o CloudFormation, você normalmente executa algum código ou script. Por exemplo, uma aplicação em execução em uma instância do EC2 pode realizar algumas tarefas de configuração adicionais e enviar um sinal para o CloudFormation para indicar a conclusão. O sinal deve ser enviado para o URL pré-assinado gerado pelo identificador da condição de espera. Você usa o URL pré-assinado para sinalizar sucesso ou falha. **Para enviar um sinal** 1. Para recuperar o URL pré-assinado no modelo, use a função intrínseca `Ref` com o nome lógico do identificador da condição de espera. Conforme mostrado no exemplo a seguir, o modelo pode declarar uma instância do Amazon EC2 e passar o URL pré-assinado para instâncias EC2 usando a propriedade `UserData` do Amazon EC2. Isso permite que scripts ou aplicações executados nessas instâncias sinalizem sucesso ou falha para o CloudFormation. ``` MyEC2Instance: Type: AWS::EC2::Instance Properties: InstanceType: t2.micro # Example instance type ImageId: ami-055e3d4f0bbeb5878 # Change this as needed (Amazon Linux 2023 in us-west-2) UserData: Fn::Base64: Fn::Join: - "" - - "SignalURL=" - { "Ref": "MyWaitHandle" } ``` Isso gera uma saída `UserData` assim: ``` SignalURL=https://amzn-s3-demo-bucket.s3.amazonaws.com/.... ``` Observação: no Console de gerenciamento da AWS e nas ferramentas de linha de comando, o URL pré-assinado é exibido como um ID físico do identificador de condição de espera. 1. (Opcional) Para detectar quando a pilha entra na condição de espera, você pode usar um dos seguintes métodos: + Se você criar a pilha com notificações habilitadas, o CloudFormation publicará uma notificação para cada evento da 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 pode monitorar os eventos da pilha usando o Console de gerenciamento da AWS, a AWS CLI ou um SDK. 1. 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 [Sintaxe de sinal da condição de espera](#wait-condition-signal-syntax). É necessário enviar o número de sinais de sucesso especificados pela propriedade `Count` para que o CloudFormation continue a criar a pilha. Se a propriedade `Count` for maior do que 1, o valor do `UniqueId` de cada sinal deverá ser exclusivo em todos os sinais enviados a uma condição de espera específica. O `UniqueId` é uma string alfanumérica arbitrária. Um comando `curl` é uma forma de enviar um sinal. O exemplo a seguir mostra uma linha do comando `curl` que sinaliza o êxito para uma condição de espera. ``` $ curl -T /tmp/a \ "https://amzn-s3-demo-bucket.s3.amazonaws.com/arn%3Aaws%3Acloudformation%3Aus-west-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 êxito, exceto 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://amzn-s3-demo-bucket.s3.amazonaws.com/arn%3Aaws%3Acloudformation%3Aus-west-2%3A034017226601%3Astack%2Fstack-gosar-20110427004224-test-stack-with-WaitCondition--VEYW%2Fe498ce60-70a1-11e0-81a7-5081d0136786%2FmyWaitConditionHandle?Expires=1303976584&AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Signature=ik1twT6hpS4cgNAw7wyOoRejVoo%3D" ``` ## Sintaxe de sinal da condição de espera Ao enviar sinais para o URL gerado pela condição de espera, você deve usar o seguinte formato JSON: ``` { "Status" : "StatusValue", "UniqueId" : "Some UniqueId", "Data" : "Some Data", "Reason" : "Some Reason" } ``` ### Propriedades O campo `Status` pode ter um dos seguintes valores: + `SUCCESS` + `FAILURE` O campo `UniqueId` identifica o sinal para o CloudFormation. Se a propriedade `Count` da condição de espera for maior que 1, o valor de `UniqueId` deverá ser exclusivo em todos os sinais enviados de uma determinada condição de espera; caso contrário, o CloudFormation considerará o sinal uma retransmissão dos sinais enviados anteriormente com o mesmo `UniqueId` e o ignorará. O campo `Data` pode conter qualquer informação que você deseje enviar de volta com o sinal. Você pode acessar o valor `Data` chamando a função [Fn::GetAtt](resources-section-structure.md#resource-properties-getatt) no modelo. O campo `Reason` é uma string sem nenhuma outra restrição em seu conteúdo além de conformidade com JSON. ## Acessar dados de sinal Para acessar os dados enviados por sinais válidos, você pode criar um valor de saída para a condição de espera no modelo do CloudFormation. Por exemplo: ``` Outputs: WaitConditionData: Description: The data passed back as part of signalling the WaitCondition Value: !GetAtt MyWaitCondition.Data ``` Você pode visualizar esses dados usando o comando [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-stacks.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-stacks.html) ou a guia **Saídas** do console do CloudFormation. A função `Fn::GetAtt` retorna o `UniqueId` e os `Data` como um par de nome/valor em uma estrutura JSON. Por exemplo: ``` {"Signal1":"Application has completed configuration."} ```