Recursos personalizados baseados no Amazon SNS - AWS CloudFormation
Uso do Amazon SNS para criar recursos personalizados

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.

  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.

    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.

  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.

    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 Delete.

    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 Delete.

    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.