Recursos personalizados baseados no Amazon SNS

O tópico apresentado a seguir mostra como configurar um recurso personalizado com um token de serviço que especifica o tópico do Amazon SNS para o qual o CloudFormation envia solicitações. Além disso, você aprende a sequência de eventos e de mensagens enviadas e recebidas como resultado da criação, da atualização e da exclusão da pilha de recursos 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 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 EC2. 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 que todas essas ações forem concluídas, a aplicação enviará uma resposta (e quaisquer dados de saída) que notifica o CloudFormation para dar prosseguimento à operação de pilha.

Quando você especifica um tópico do Amazon SNS como o destino de um recurso personalizado, o CloudFormation envia mensagens para o tópico do SNS especificado durante as operações de pilha que envolvem o recurso personalizado. Para realizar o processamento dessas mensagens e executar as ações necessárias, você deve ter um endpoint com suporte que seja assinante do tópico do SNS.

Para obter uma introdução aos recursos personalizados e como eles funcionam, consulte Crie uma lógica de provisionamento personalizada com recursos personalizados. Para obter mais informações sobre o Amazon SNS e como ele funciona, consulte o Guia do desenvolvedor do Amazon Simple Notification Service.

Uso do Amazon SNS para criar recursos personalizados

Etapa 1: Criar a pilha

1. O desenvolvedor do modelo cria uma pilha do CloudFormation que contém um recurso personalizado.

   No exemplo de modelo apresentado abaixo, usamos o nome do tipo de recurso personalizado Custom::SeleniumTester para o recurso personalizado com ID lógico MySeleniumTest. Os nomes de tipo de recurso personalizados devem ser alfanuméricos e podem ter um comprimento máximo de 60 caracteres.

   O tipo de recurso personalizado é declarado com um token de serviço, propriedades opcionais específicas do provedor e atributos Fn::GetAtt opcionais que são definidos pelo provedor de recursos personalizados. Essas propriedades e os atributos podem ser usados para passar informações do template developer para o custom resource provider, e vice-versa. O token de serviço especifica um tópico do Amazon SNS configurado pelo provedor de recursos.

   {
      "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 CloudFormation. Caso o custom resource provider seja um terceiro, o template developer deverá obter os nomes desses valores de retorno do custom resource provider.

2. O 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/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10",
      "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" ]
      }
   }

   Para obter informações detalhadas sobre o objeto de solicitação para as solicitações Create, consulte o tópico Criar uma solicitação de recursos personalizados do CloudFormation.

3. 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 usa o URL do S3 enviado pelo CloudFormation para enviar uma resposta de SUCCESS ou de FAILED.

   O CloudFormation espera diferentes campos de resposta com base no tipo de resposta. Para obter informações sobre os campos de resposta para um tipo de solicitação em específico, consulte a documentação para esse tipo de solicitação na seção Tipos de solicitação de recurso personalizado.

   Em resposta a uma solicitação de criação ou atualização, o custom resource provider pode retornar elementos de dados no campo Data 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/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10",
      "RequestId" : "unique id for this create request",
      "LogicalResourceId" : "MySeleniumTester",
      "Data" : {
         "resultsPage" : "http://www.myexampledomain/test-results/guid",
         "lastUpdate" : "2012-11-14T03:30Z"
      }
   }

   Para obter informações detalhadas sobre o objeto de resposta para as solicitações Create, consulte o tópico Criar uma solicitação de recursos personalizados do CloudFormation.

   Os campos StackId, RequestId e LogicalResourceId devem ser copiados na íntegra da solicitação.

4. O 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"] }
      }
   }

Etapa 2: Atualizações de pilha

Para atualizar uma pilha existente, é necessário enviar um modelo que especifique as atualizações para as propriedades dos recursos na pilha, conforme mostrado no exemplo abaixo. O CloudFormation atualiza somente os recursos que têm alterações especificadas no modelo. Para ter mais informações, consulte Compreender atualização de comportamentos de recursos da pilha.

É possível atualizar recursos personalizados que exigem uma substituição do recurso físico subjacente. Quando você atualiza um recurso personalizado em um modelo do CloudFormation, o CloudFormation envia uma solicitação de atualização a 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 o CloudFormation recebe a resposta, ele compara o PhysicalResourceId entre os recursos personalizados antigos e novos. Se os recursos forem diferentes, o CloudFormation reconhecerá a atualização como uma substituição e enviará uma solicitação de exclusão para o recurso antigo, conforme mostrado na Etapa 3: Exclusão da pilha.

nota

Se você não fez alterações no recurso personalizado, o CloudFormation não enviará solicitações para ele durante uma atualização de pilha.

1. 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"] }
         }
      }
   }

2. O 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/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10",
      "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" ]
      }
   }

   Para obter informações detalhadas sobre o objeto de solicitação para as solicitações Update, consulte o tópico Atualizar solicitação de recursos personalizados para o CloudFormation.

3. O provedor de recursos personalizados realiza o processamento dos dados enviados pelo CloudFormation. O recurso personalizado executa a atualização e envia uma resposta de SUCCESS ou de FAILED para o URL do S3. Em seguida, o CloudFormation compara os PhysicalResourceIDs de recursos personalizados antigos e novos. Se os recursos forem diferentes, o CloudFormation reconhecerá que a atualização requer uma substituição e enviará 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/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10",
      "RequestId" : "uniqueid for this update request",
      "LogicalResourceId" : "MySeleniumTester",
      "PhysicalResourceId" : "Tester2"
   }

   Para obter informações detalhadas sobre o objeto de resposta para as solicitações Update, consulte o tópico Atualizar solicitação de recursos personalizados para o CloudFormation.

   Os campos StackId, RequestId e LogicalResourceId devem ser copiados na íntegra da solicitação.

4. O 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.

Etapa 3: Exclusão da pilha

1. O desenvolvedor do modelo exclui uma pilha que contém um recurso personalizado. O CloudFormation obtém as propriedades atuais especificadas no modelo de pilha em conjunto com o tópico do SNS e se prepara para fazer uma solicitação ao provedor de recursos personalizados.

2. O 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 CloudFormation compara o PhysicalResourceId entre os recursos personalizados antigos e novos. Se os recursos forem diferentes, o CloudFormation reconhecerá a atualização como uma substituição e enviará uma solicitação de exclusão para o recurso antigo (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/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10",
      "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" ]
      }
   }

   Para obter informações detalhadas sobre o objeto de solicitação para as solicitações Delete, consulte o tópico Excluir uma solicitação de recursos personalizados do CloudFormation.

   DescribeStackResource, DescribeStackResourcese ListStackResources exibem o nome definido pelo usuário caso ele tenha sido especificado.

3. O provedor de recursos personalizados realiza o processamento dos dados enviados pelo CloudFormation e determina se a solicitação Delete ocorreu com êxito. O provedor de recursos usa o URL do S3 enviado pelo CloudFormation para enviar uma resposta de SUCCESS ou de 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/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10",
      "RequestId" : "unique id for this delete request",
      "LogicalResourceId" : "MySeleniumTester",
      "PhysicalResourceId" : "Tester1"
   }

   Para obter informações detalhadas sobre o objeto de resposta para as solicitações Delete, consulte o tópico Excluir uma solicitação de recursos personalizados do CloudFormation.

   Os campos StackId, RequestId e LogicalResourceId devem ser copiados na íntegra da solicitação.

4. O CloudFormation declara o status da pilha como DELETE_COMPLETE ou DELETE_FAILED.