Usar um identificador de condição de espera

Criar condições de espera em um modelo

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 Atributo CreationPolicy ou Implantar aplicações no Amazon EC2 com o AWS CloudFormation.

Usando o recurso AWS::CloudFormation::WaitConditionHandle e o atributo Atributo CreationPolicy, você pode 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 do endpoint de VPC, 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 CloudFormation. Recursos devem enviar respostas à condição de espera para um URL pré-assinado do Amazon S3. Se eles não conseguirem enviar respostas ao Amazon S3, o AWS CloudFormation não receberá uma resposta, e haverá 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 êxito antes que o período de tempo limite expire, ele continuará criando a pilha; caso contrário, ele 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. Ao adicionar um atributo DependsOn a uma condição de espera, você especifica que essa condição de espera será criada apenas após a criação de um recurso específico ter sido concluída. 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, você talvez queira que uma instância de banco de dados do Amazon RDS seja criada e que um banco de dados seja configurado nessa instância primeiro antes de criar instâncias do EC2 que usem esse banco de dados. Nesse caso, você cria uma condição de espera que tenha um atributo DependsOn que especifique a instância de banco de dados e cria recursos de instância do EC2 que tenham atributos DependsOn que especifiquem 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 êxito para uma condição de espera antes de definir o status dessa condição de espera para CREATE_COMPLETE e continuar criando a pilha. A propriedade Count da condição de espera especifica o número de sinais de êxito. 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 êxito (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 êxito de requisito ou se um sinal de falha for recebido).

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

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 URL pré-assinado que você pode usar para sinalizar o êxito ou a falha à WaitCondition. Por exemplo:
```
"myWaitHandle" : {
     "Type" : "AWS::CloudFormation::WaitConditionHandle",
     "Properties" : {
     }
}
```
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, e Timeout é o número de segundos que o AWS CloudFormation aguardará. Opcionalmente, você pode definir a propriedade Count, que determina o número de sinais de êxito 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 associa um recurso à condição de espera. Depois que o AWS CloudFormation cria o recurso DependsOn, ele bloqueia 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 êxito 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 com êxito do recurso Ec2Instance, usa o recurso myWaitHandle como o WaitConditionHandle, tem um tempo limite de 4.500 segundos e tem a Count padrão de 1 (desde que nenhuma propriedade Count seja especificada):
```
"myWaitCondition" : {
    "Type" : "AWS::CloudFormation::WaitCondition",
    "DependsOn" : "Ec2Instance",
    "Properties" : {
        "Handle" : { "Ref" : "myWaitHandle" },
        "Timeout" : "4500"
    }
}
```
Obtenha o pre-signed URL a ser usada para sinalização.

No modelo, o URL pré-assinado pode ser recuperado ao transmitir 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 transmitir o URL pré-assinado para as instâncias do Amazon EC2, a fim de que os scripts ou as aplicações em execução nessas instâncias possam sinalizar o êxito ou a falha para o AWS CloudFormation:
```
"UserData" : {
   "Fn::Base64" : {
       "Fn::Join" : [ "", ["SignalURL=", { "Ref" : "myWaitHandle" } ] ]
   }
}
```
Observação: no AWS Management Console ou nas ferramentas de linha de comando do AWS CloudFormation, o URL pré-assinado é exibido como ID físico do recurso de identificador de condição de espera.
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 de linha de comando do AWS CloudFormation ou a API do AWS CloudFormation.
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 êxito especificados pela propriedade Count para que o AWS CloudFormation continue com a criação da 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://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 ê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://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"
}

Em que:

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.

O UniqueId identifica o sinal para o AWS CloudFormation. Se a propriedade Count da condição de espera for maior que 1, o valor do 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 de Data pode ser acessado chamando a função Fn::GetAtt no modelo. Por exemplo, se você criar o seguinte valor de saída para a condição de espera mywaitcondition, poderá usar o comando aws cloudformation describe-stacks, a operação da API DescribeStacks ou a guia Saídas do console do AWS CloudFormation para visualizar os Data enviados pelos sinais válidos enviados para o 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 o UniqueId e os Data como um par de nome/valor em uma estrutura JSON. O exemplo abaixo é de um 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.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Implantar aplicativos

Trechos de modelo