Recursos personalizados com suporte do Amazon Simple Notification Service - AWS CloudFormation

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 disparar 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 aprovados. 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.

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

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

  1. O template developer 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 custom resource provider 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.

  2. 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" ] } }
  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 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 campos devem ser copiados textualmente da solicitação.

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

  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 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 que o campo OldResourceProperties contém as propriedades de recurso antigas e ResourceProperties contém as propriedades de recurso atualizadas (se houver 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" ] } }
  3. O custom resource provider 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 campos devem ser copiados textualmente da solicitação.

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

  1. O template developer 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 custom resource provider.

  2. 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 eles 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.

  3. O custom resource provider 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 campos devem ser copiados textualmente da solicitação.

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