Recursos personalizados - AWS CloudFormation

Recursos personalizados

nota

O registro do CloudFormation oferece várias vantagens sobre recursos personalizados, tais vantagens incluem:

  • Oferece suporte à modelagem, ao provisionamento e ao gerenciamento de recursos de aplicações de terceiros

  • Suporta as operações Create, Read, Update, Delete e List (CRUDL)

  • Suporta detecção de desvio em tipos de recursos privados e de terceiros

Ao contrário dos recursos personalizados, os recursos baseados em registro não precisarão associar um tópico do Amazon SNS ou uma função Lambda para executar operações CRUDL. Para obter mais informações sobre o registro do CloudFormation, consulte Using the CloudFormation AWSregistry (Usar o registro do CloudFormation).

Os recursos personalizados permitem escrever uma lógica de provisionamento personalizada em modelos que o AWS CloudFormation executa sempre que você cria, atualiza (caso você tenha alterado o recurso personalizado) ou exclui pilhas. Por exemplo, convém incluir recursos que não estejam disponíveis como tipos de recurso do AWS CloudFormation. Você pode incluir esses recursos usando recursos personalizados. Dessa forma, você ainda pode gerenciar todos os recursos relacionados em uma única pilha.

Use o tipo de recurso AWS::CloudFormation::CustomResource ou Custom::MyCustomResourceTypeName para definir recursos personalizados nos modelos. Os recursos personalizados exigem uma propriedade: o token de serviço, que especifica para onde o AWS CloudFormation envia solicitações, como um tópico do Amazon SNS.

nota

Caso você use o recurso VPC endpoint, os recursos personalizados na VPC devem ter acesso a buckets do S3 específicos do AWS CloudFormation. Os recursos personalizados devem enviar respostas a um URL pré-assinado do Amazon S3. Se eles não enviam respostas para o Amazon S3, o AWS CloudFormation não receberá uma resposta e há falha na operação de pilha. Para mais informações, consulte Configurar VPC endpoints VPC para o AWS CloudFormation.

Como os recursos personalizados funcionam

Qualquer ação executada por um recurso personalizado envolve três partes.

template developer

Cria um modelo que inclui um tipo de recurso personalizado. O template developer especifica o token de serviço e todos os dados de entrada no modelo.

custom resource provider

Possui o recurso personalizado e determina como processar e atender a solicitações do AWS CloudFormation. O custom resource provider deve fornecer um token de serviço usado pelo template developer.

AWS CloudFormation

Durante uma operação de pilha, envia uma solicitação para um token de serviço especificado no modelo e aguarda uma resposta antes de continuar a operação de pilha.

O template developer e o custom resource provider podem ser a mesma pessoa ou entidade, mas o processo é o mesmo. As seguintes etapas descrevem o processo geral:

  1. O template developer define um recurso personalizado no modelo, que inclui um token de serviço e os parâmetros de dados de entrada. Dependendo do recurso personalizado, os dados de entrada podem ser necessários. Porém, o token de serviço é sempre obrigatório.

    O token de serviço especifica para onde o AWS CloudFormation envia solicitações, como um ARN de tópico do Amazon SNS ou a um ARN de função do AWS Lambda. Para obter mais informações, consulte AWS::CloudFormation::CustomResource. O token de serviço e a estrutura dos dados de entrada são definidos pelo custom resource provider.

  2. Sempre que alguém usa o modelo para criar, atualizar ou excluir um recurso personalizado, o AWS CloudFormation envia uma solicitação para o token de serviço especificado. O serviço de token deve estar na mesma região em que a pilha está sendo criada.

    Na solicitação, o AWS CloudFormation inclui informações como o tipo de solicitação e um URL do Amazon Simple Storage Service pré-assinado, para o qual o recurso personalizado envia respostas. Para obter mais informações sobre o que está incluído na solicitação, consulte Objetos de solicitação de recursos personalizados.

    Os seguintes dados de exemplo mostram o que o AWS CloudFormation inclui em uma solicitação:

    { "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::TestResource", "LogicalResourceId" : "MyTestResource", "ResourceProperties" : { "Name" : "Value", "List" : [ "1", "2", "3" ] } }
    nota

    Neste exemplo, ResourceProperties permite que o AWS CloudFormation crie uma carga personalizada a ser enviada à função Lambda.

  3. O custom resource provider processa a solicitação do AWS CloudFormation e retorna uma resposta de SUCCESS ou FAILED para o pre-signed URL. O custom resource provider fornece a resposta em um arquivo formatado em JSON e o carrega no URL do S3 pré-assinado. Para obter mais informações, consulte Upload de objetos usando pre-signed URLs, no Guia do desenvolvedor do Amazon Simple Storage Service.

    Na resposta, o custom resource provider também pode incluir pares de nome e valor que o template developer pode acessar. Por exemplo, a resposta poderá incluir dados de saída se a solicitação tiver sido bem-sucedida ou uma mensagem de erro se a solicitação tiver falhado. Para obter mais informações sobre respostas, consulte Objetos de resposta de recursos personalizados.

    Importante

    Caso os pares nome/valor contenham informações confidenciais, você deve usar o campo NoEcho para mascarar a saída do recurso personalizado. Do contrário, os valores permanecerão visíveis por meio de APIs mostrando valores de propriedade (como DescribeStackEvents).

    Para obter mais informações sobre o uso de NoEcho para mascarar informações confidenciais, consulte a melhor prática Não incorporar credenciais em seus modelos.

    O custom resource provider é responsável por escutar e responder à solicitação. Por exemplo, para notificações do Amazon SNS, o custom resource provider deve escutar e responder às notificações enviadas para um ARN de tópico específico. O AWS CloudFormation aguarda e escuta uma resposta no local do pre-signed URL.

    Os seguintes dados de exemplo mostram o que um recurso personalizado pode incluir em uma resposta:

    { "Status" : "SUCCESS", "PhysicalResourceId" : "TestResource1", "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/stack-name/guid", "RequestId" : "unique id for this create request", "LogicalResourceId" : "MyTestResource", "Data" : { "OutputName1" : "Value1", "OutputName2" : "Value2", } }
  4. Após a obtenção de uma resposta SUCCESS, o AWS CloudFormation continua a operação da pilha. Caso uma resposta FAILED ou nenhuma resposta seja retornada, a operação falhará. Todos os dados de saída do recurso personalizado são armazenados no local do URL pré-assinado. O template developer pode recuperar os dados usando a função Fn::GetAtt.