Demonstração: Usar o Amazon Simple Notification Service para criar recursos personalizados

Recursos personalizados com suporte do Amazon Simple Notification Service

Ao associar um tópico do Amazon SNS a um recurso personalizado, você usa as notificações do Amazon SNS para invocar a lógica de provisionamento personalizada. Com recursos personalizados e o Amazon SNS, você pode habilitar cenários como adicionar novos recursos a uma pilha e injetar dados dinâmicos em uma pilha. Por exemplo, quando você cria uma pilha, o AWS CloudFormation pode enviar uma solicitação create para um tópico monitorado por uma aplicação em execução em uma instância do Amazon Elastic Compute Cloud. A notificação do Amazon SNS aciona a aplicação para realizar tarefas de provisionamento adicionais, como recuperar um grupo de IPs elásticos na lista de permissão. Depois de pronta, a aplicação enviará uma resposta (e quaisquer dados de saída) que notifica o AWS CloudFormation para avançar na operação da pilha.

Esta descrição passará pelo processo de recursos personalizados, explicando a sequência de eventos e mensagens enviadas e recebidas decorrentes da criação da pilha de recursos personalizada, das atualizações e da exclusão.

Etapa 1: Criar a pilha

O desenvolvedor de modelos cria uma pilha do AWS CloudFormation que contém um recurso personalizado. No exemplo do modelo abaixo, usamos o nome do tipo de recurso personalizado Custom::SeleniumTester para o recurso personalizado MySeleniumTest.

O tipo de recurso personalizado é declarado com um token de serviço, provider-specific properties opcional e atributos Fn::GetAtt opcionais definidos pelo custom resource provider. Essas propriedades e os atributos podem ser usados para passar informações do template developer para o custom resource provider, e vice-versa. Os nomes de tipo de recurso personalizados devem ser alfanuméricos e podem ter um comprimento máximo de 60 caracteres.

O seguinte exemplo mostra um modelo com propriedades personalizadas e atributos de retorno:
```
{
   "AWSTemplateFormatVersion" : "2010-09-09",
   "Resources" : {
      "MySeleniumTest" : {
         "Type": "Custom::SeleniumTester",
         "Version" : "1.0",
         "Properties" : {
            "ServiceToken": "arn:aws:sns:us-west-2:123456789012:CRTest",
            "seleniumTester" : "SeleniumTest()",
            "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ],
            "frequencyOfTestsPerHour" : [ "3", "2", "4" ]
         }
      }
   },
   "Outputs" : {
      "topItem" : {
         "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] }
      },
      "numRespondents" : {
         "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] }
      }
   }
}
```
nota
Os nomes e os valores dos dados acessados com Fn::GetAtt são retornados pelo provedor de recursos personalizados durante a resposta do provedor para o AWS CloudFormation. Caso o custom resource provider seja um terceiro, o template developer deverá obter os nomes desses valores de retorno do custom resource provider.
O AWS CloudFormation envia uma notificação do Amazon SNS para o provedor de recursos com um "RequestType" : "Create" que contém informações sobre a pilha, as propriedades do recurso personalizado do modelo da pilha e um URL de S3 para a resposta.

O tópico SNS usado para enviar a notificação é incorporado no modelo na propriedade ServiceToken. Para evitar usar um valor codificado, um template developer pode usar um parâmetro de modelo, de maneira que o valor seja informado no momento em que a pilha é iniciada.

O exemplo a seguir mostra uma solicitação Create de recurso personalizado que inclui um nome de tipo de recurso personalizado Custom::SeleniumTester, criado com um LogicalResourceId de MySeleniumTester:
```
{
   "RequestType" : "Create",
   "ResponseURL" : "http://pre-signed-S3-url-for-response",
   "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/stack-name/guid",
   "RequestId" : "unique id for this create request",
   "ResourceType" : "Custom::SeleniumTester",
   "LogicalResourceId" : "MySeleniumTester",
   "ResourceProperties" : {
      "seleniumTester" : "SeleniumTest()",
      "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ],
      "frequencyOfTestsPerHour" : [ "3", "2", "4" ]
   }
}
```
O custom resource provider processa os dados enviados pelo template developer e determina se a solicitação Create foi bem-sucedida. O provedor de recursos acaba usando o URL do S3 enviado pelo AWS CloudFormation para enviar uma resposta de SUCCESS ou FAILED.

Dependendo do tipo de resposta, campos de resposta diferentes serão esperados pelo AWS CloudFormation. Consulte a seção Respostas no tópico de referência do RequestType que está sendo processado.

Em resposta a uma solicitação de criação ou atualização, o custom resource provider pode retornar elementos de dados no campo Dados da resposta. Esses são os pares de nome/valor, e os nomes correspondem aos atributos Fn::GetAtt usados com o recurso personalizado no modelo de pilha. Os valores são os dados retornados quando o Template Developer chama Fn::GetAtt no recurso com o nome do atributo.

Este é um exemplo de uma resposta de recurso personalizado:
```
{
   "Status" : "SUCCESS",
   "PhysicalResourceId" : "Tester1",
   "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/stack-name/guid",
   "RequestId" : "unique id for this create request",
   "LogicalResourceId" : "MySeleniumTester",
   "Data" : {
      "resultsPage" : "http://www.myexampledomain/test-results/guid",
      "lastUpdate" : "2012-11-14T03:30Z",
   }
}           
```
Os campos StackId, RequestId e LogicalResourceId devem ser copiados na íntegra da solicitação.
O AWS CloudFormation declara o status da pilha como CREATE_COMPLETE ou CREATE_FAILED. Caso a pilha tenha sido criada com êxito, o template developer pode usar os valores de saída do recurso personalizado criado os acessando com Fn::GetAtt.

Por exemplo, o modelo de recurso personalizado usado na ilustração utilizou Fn::GetAtt para copiar saídas de recurso para as saídas de pilha:
```
"Outputs" : {
   "topItem" : {
      "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] }
   },
   "numRespondents" : {
      "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] }
   }
}           
```

Para obter informações detalhadas sobre os objetos de solicitação e resposta envolvidos em solicitações Create, consulte Create no Custom Resource Reference.

Etapa 2: Atualizações de pilha

Para atualizar uma pilha existente, você deve enviar um modelo que especifica as atualizações das propriedades de recursos na pilha, conforme mostrado no exemplo abaixo. O AWS CloudFormation atualiza apenas os recursos cujas alterações estejam especificadas no modelo. Para obter mais informações sobre como atualizar pilhas, consulte Atualizações de pilhas do AWS CloudFormation.

É possível atualizar recursos personalizados que exigem uma substituição do recurso físico subjacente. Ao atualizar um recurso personalizado em um modelo do AWS CloudFormation, o AWS CloudFormation envia uma solicitação de atualização para esse recurso personalizado. Caso um recurso personalizado exija uma substituição, o novo recurso personalizado deve enviar uma resposta com o novo ID físico. Quando recebe a resposta, o AWS CloudFormation compara o PhysicalResourceId entre os recursos personalizados antigos e novos. Caso sejam diferentes, o AWS CloudFormation reconhece a atualização como uma substituição e envia uma solicitação de exclusão para o recurso anterior, conforme mostrado em Etapa 3: Exclusão da pilha.

nota

Se você não fizer alterações do recurso personalizado, o AWS CloudFormation não enviará solicitações para ele durante uma atualização da pilha.

O template developer inicia uma atualização para a pilha que contém um recurso personalizado. Durante uma atualização, o template developer pode especificar novas propriedades no modelo da pilha.

Este é um exemplo de um Update para o modelo de pilha que usa um tipo de recurso personalizado:


{
   "AWSTemplateFormatVersion" : "2010-09-09",
   "Resources" : {
      "MySeleniumTest" : {
         "Type": "Custom::SeleniumTester",
         "Version" : "1.0",
         "Properties" : {
            "ServiceToken": "arn:aws:sns:us-west-2:123456789012:CRTest",
            "seleniumTester" : "SeleniumTest()",
            "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com",
               "http://mynewsite.com" ],
            "frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ]
         }
      }
   },
   "Outputs" : {
      "topItem" : {
         "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] }
      },
      "numRespondents" : {
         "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] }
      }
   }
}

O AWS CloudFormation envia uma notificação do Amazon SNS para o provedor de recursos com um "RequestType" : "Update" que contém informações semelhantes às da chamada Create, exceto por o campo OldResourceProperties conter as propriedades de recurso anteriores e ResourceProperties conter as propriedades de recurso atualizadas (caso haja alguma).

Este é um exemplo de uma solicitação Update:


{
   "RequestType" : "Update",
   "ResponseURL" : "http://pre-signed-S3-url-for-response",
   "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/stack-name/guid",
   "RequestId" : "uniqueid for this update request",
   "LogicalResourceId" : "MySeleniumTester",
   "ResourceType" : "Custom::SeleniumTester",  
   "PhysicalResourceId" : "Tester1",
   "ResourceProperties" : {
      "seleniumTester" : "SeleniumTest()",
      "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com",
         "http://mynewsite.com" ],
      "frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ]
   },
   "OldResourceProperties" : {
      "seleniumTester" : "SeleniumTest()",
      "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ],
      "frequencyOfTestsPerHour" : [ "3", "2", "4" ]
   }
}

O provedor de recurso personalizado processa os dados enviados pelo AWS CloudFormation. O recurso personalizado realiza a atualização e envia uma resposta de SUCCESS ou FAILED para o URL do S3. Em seguida, o AWS CloudFormation compara o PhysicalResourceIDs de recursos personalizados antigos e novos. Caso sejam diferentes, o AWS CloudFormation reconhece que a atualização exige uma substituição e envia uma solicitação de exclusão para o recurso antigo. O exemplo a seguir demonstra a resposta do custom resource provider a uma solicitação Update.
```
{
   "Status" : "SUCCESS",
   "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/stack-name/guid",
   "RequestId" : "uniqueid for this update request",
   "LogicalResourceId" : "MySeleniumTester",
   "PhysicalResourceId" : "Tester2"
}           
```
Os campos StackId, RequestId e LogicalResourceId devem ser copiados na íntegra da solicitação.
O AWS CloudFormation declara o status da pilha como UPDATE_COMPLETE ou UPDATE_FAILED. Em caso de falha na atualização, a pilha é revertida. Caso a pilha tenha sido atualizada com êxito, o template developer poderá acessar todos os novos valores de saída do recurso personalizado criado com Fn::GetAtt.

Para obter informações detalhadas sobre os objetos de solicitação e resposta envolvidos em solicitações Update, consulte Update no Custom Resource Reference.

Etapa 3: Exclusão da pilha

O desenvolvedor de modelos exclui uma pilha que contém um recurso personalizado. O AWS CloudFormation obtém as propriedades atuais especificadas no modelo de pilha com o tópico do SNS e se prepara para fazer uma solicitação ao provedor de recursos personalizados.
O AWS CloudFormation envia uma notificação do Amazon SNS para o provedor de recursos com um "RequestType" : "Delete" que contém informações atuais sobre a pilha, as propriedades do recurso personalizado do modelo da pilha e um URL de S3 para a resposta.

Sempre que você exclui uma pilha ou faz uma atualização que remove ou substitui o recurso personalizado, o AWS CloudFormation compara o PhysicalResourceId entre os recursos personalizados antigos e novos. Caso sejam diferentes, o AWS CloudFormation reconhece a atualização como uma substituição e envia uma solicitação de exclusão para o recurso anterior (OldPhysicalResource), conforme mostrado no exemplo a seguir de uma solicitação Delete.
```
{
   "RequestType" : "Delete",
   "ResponseURL" : "http://pre-signed-S3-url-for-response",
   "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/stack-name/guid",
   "RequestId" : "unique id for this delete request",
   "ResourceType" : "Custom::SeleniumTester",
   "LogicalResourceId" : "MySeleniumTester",
   "PhysicalResourceId" : "Tester1",
   "ResourceProperties" : {
      "seleniumTester" : "SeleniumTest()",
      "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com",
         "http://mynewsite.com" ],
      "frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ]
   }
}    
            
```
DescribeStackResource, DescribeStackResourcese ListStackResources exibem o nome definido pelo usuário caso ele tenha sido especificado.
O provedor de recurso personalizado processa os dados enviados pelo AWS CloudFormation e determina se a solicitação Delete foi bem-sucedida. O provedor de recursos acaba usando o URL do S3 enviado pelo AWS CloudFormation para enviar uma resposta de SUCCESS ou FAILED. Para excluir com êxito uma pilha com um recurso personalizado, o custom resource provider devem responder com êxito a uma solicitação de exclusão.

Este é um exemplo de uma resposta do custom resource provider a uma solicitação Delete:
```
{
   "Status" : "SUCCESS",
   "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/stack-name/guid",
   "RequestId" : "unique id for this delete request",
   "LogicalResourceId" : "MySeleniumTester",
   "PhysicalResourceId" : "Tester1"
}         
```
Os campos StackId, RequestId e LogicalResourceId devem ser copiados na íntegra da solicitação.
O AWS CloudFormation declara o status da pilha como DELETE_COMPLETE ou DELETE_FAILED.

Para obter informações detalhadas sobre os objetos de solicitação e resposta envolvidos em solicitações Delete, consulte Delete, no Referência de recursos personalizados.

Consulte também

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

Recursos personalizados

Recursos personalizados com suporte do AWS Lambda