Recursos personalizados - AWS CloudFormation
Como os recursos personalizados funcionamTempo limite de resposta

Recursos personalizados

Os recursos personalizados fornecem uma maneira de gravar uma lógica de provisionamento personalizada nos modelos do CloudFormation e fazer com que o CloudFormation a execute sempre que você criar, atualizar (se você alterou o recurso personalizado) ou excluir uma pilha. Isso pode ser útil quando os requisitos de provisionamento envolvem uma lógica complexa ou fluxos de trabalho que não podem ser expressos com os tipos de recursos integrados do CloudFormation.

Por exemplo, talvez você deseje incluir recursos que não estão disponíveis como tipos de recursos do CloudFormation. Você pode incluir esses recursos usando recursos personalizados. Dessa forma, você ainda poderá gerenciar todos os recursos relacionados em uma única pilha.

Para definir um recurso personalizado em seu modelo do CloudFormation, você usa o tipo de recurso AWS::CloudFormation::CustomResource ou Custom::MyCustomResourceTypeName. Os recursos personalizados requerem uma propriedade, o token de serviço, que especifica para qual local o CloudFormation envia as solicitações, como um tópico do Amazon SNS ou uma função do Lambda.

Os tópicos apresentados a seguir fornecem informações sobre como usar os recursos personalizados.

Tópicos
nota

O registro e os recursos personalizados do CloudFormation oferecem seus próprios benefícios. Os recursos personalizados oferecem os seguintes benefícios:

  • Você não precisa registrar o recurso.

  • Você pode incluir um recurso inteiro como parte de um modelo sem registrá-lo.

  • Aceta as operações Create, Update e Delete

As vantagens que os recursos baseados no registro oferecem são as seguintes:

  • 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 ter mais informações, consulte Gerenciar extensões com o registro do CloudFormation.

Como os recursos personalizados funcionam

O processo geral para configurar um novo recurso personalizado inclui as etapas a seguir. Essas etapas envolvem dois perfis: o provedor de recursos personalizados que é o proprietário do recurso personalizado e o desenvolvedor de modelos que cria um modelo que inclui um tipo de recurso personalizado. Eles podem ser a mesma pessoa, mas, se não forem, o provedor de recursos personalizados deverá trabalhar com o desenvolvedor de modelos.

  1. O provedor de recursos personalizados escreve uma lógica que determina como lidar com as solicitações do CloudFormation e realizar ações no recurso personalizado.

  2. O provedor de recursos personalizados cria o tópico do Amazon SNS ou a função do Lambda para a qual o CloudFormation pode enviar solicitações. O tópico do Amazon SNS ou a função do Lambda devem estar na mesma região em que a pilha será criada.

  3. O provedor de recursos personalizados fornece o ARN do tópico do Amazon SNS ou o ARN da função do Lambda ao desenvolvedor de modelos.

  4. O desenvolvedor de modelos define o recurso personalizado no modelo do CloudFormation. Isso inclui um token de serviço e todos os parâmetros de dados de entrada. O token de serviço e a estrutura dos dados de entrada são definidos pelo provedor de recursos personalizados. O token de serviço especifica o ARN do tópico do Amazon SNS ou o ARN da função do Lambda e sempre é obrigatório, mas os dados de entrada são opcionais, dependendo do recurso personalizado.

Sempre que alguém usa o modelo para criar, atualizar ou excluir o recurso personalizado, o CloudFormation envia uma solicitação para o token de serviço especificado e espera por uma resposta antes de prosseguir com a operação da pilha.

Este é o resumo do fluxo de criação de uma pilha usando o modelo:

  1. O CloudFormation envia uma solicitação para o token de serviço especificado. A solicitação inclui informações como o tipo de solicitação e uma URL do Amazon Simple Storage Service pré-assinada, para a qual o recurso personalizado envia as respostas. Para obter mais informações sobre o que está incluído na solicitação, consulte Objetos de solicitação de recursos personalizados.

    O exemplo de dados a seguir mostra o que o CloudFormation inclui em uma solicitação de Create. Neste exemplo, ResourceProperties permite que o CloudFormation crie uma carga útil personalizada para enviar à função do Lambda.

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

  2. O provedor de recursos personalizados realiza o processamento da solicitação do CloudFormation e retorna uma resposta de SUCCESS ou de FAILED para o URL assinado previamente. 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 URL pré-assinados, no Guia do usuário 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

    Se os pares de nome/valor contiverem informações confidenciais, você deverá utilizar o campo NoEcho para mascarar a saída do recurso personalizado. Caso contrário, os valores estarão visíveis por meio de APIs que exibem valores de propriedades (como DescribeStackEvents).

    Para obter mais informações sobre como usar NoEcho para mascarar informações confidenciais, consulte a prática recomendada 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 provedor de recursos personalizados deve atuar como receptor e responder às notificações enviadas para um ARN de tópico específico. O CloudFormation espera e atua como receptor para uma resposta no local do URL assinado previamente.

    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/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10",
   "RequestId" : "unique id for this create request",
   "LogicalResourceId" : "MyTestResource",
   "Data" : {
      "OutputName1" : "Value1",
      "OutputName2" : "Value2",
   }
}

  3. Após obter uma resposta de SUCCESS, o CloudFormation prossegue com a operação de 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.

nota

Se você usar o recurso endpoint da VPC, os recursos personalizados na VPC deverão ter acesso a buckets do S3 específicos para o CloudFormation. Os recursos personalizados devem enviar respostas a um URL pré-assinado do Amazon S3. Se não puderem enviar respostas para o Amazon S3, o CloudFormation não receberá uma resposta e há falha na operação de pilha. Para ter mais informações, consulte Acessar o CloudFormation usando um endpoint de interface (AWS PrivateLink).

Tempo limite de resposta

O tempo limite padrão para o recurso personalizado é de 3600 segundos (1 hora). Se nenhuma resposta for recebida durante esse período, a operação de pilha falhará.

É possível ajustar o valor do tempo limite com base em quanto tempo você espera que o recurso personalizado leve para responder. Por exemplo, ao provisionar um recurso personalizado que invoca uma função do Lambda que deve responder em cinco minutos, você pode definir um tempo limite de cinco minutos no modelo de pilha especificando a propriedade ServiceTimeout. Para ter mais informações, consulte Objetos de solicitação de recursos personalizados. Dessa forma, se houver um erro na função do Lambda que provoque sua paralisação, o CloudFormation determinará que houve falha na operação de pilha após cinco minutos, em vez de esperar a hora inteira.

Porém, tenha cuidado para não definir um valor de tempo limite muito pequeno. Para evitar que o tempo limite se esgote inesperadamente, certifique-se de que o recurso personalizado tenha tempo suficiente para realizar as ações necessárias e retornar uma resposta.