Usar macros do AWS CloudFormation para realizar processamento personalizado em modelos - AWS CloudFormation

Usar macros do AWS CloudFormation para realizar processamento personalizado em modelos

Macros permitem realizar o processamento personalizado em modelos, desde ações simples, como operações de localizar e substituir, até transformações extensas de modelos inteiros.

Para ter uma ideia das possibilidades, considere as transformações AWS::Include e AWS::Serverless, que são macros hospedadas pelo AWS CloudFormation:

Como funcionam as macros do AWS CloudFormation

Há duas etapas principais para processar modelos usando macros: criar a macro propriamente dita e, em seguida, usar essa macro para realizar o processamento nos seus modelos.

Para criar uma definição de macro, você precisa criar o seguinte:

  • Uma função AWS Lambda para realizar o processamento do modelo. Essa função Lambda aceita um trecho inteiro ou um modelo inteiro e quaisquer parâmetros adicionais que você definir. Ele retorna o trecho de modelo processado ou todo o modelo como uma resposta.

  • Um recurso do tipo AWS::CloudFormation::Macro, que permite que os usuários chamem a função Lambda de dentro de modelos do AWS CloudFormation. Esse recurso especifica o ARN da função Lambda a ser chamada para esta macro, além de propriedades opcionais adicionais para ajudar na depuração. Para criar esse recurso em uma conta, crie um modelo que inclua um recurso AWS::CloudFormation::Macro e, depois, crie uma pilha ou um conjunto de pilhas com permissões autogerenciadas baseadas no modelo. No momento, o AWS CloudFormation StackSets não oferece suporte à criação ou à atualização de conjuntos de pilhas com permissões gerenciadas por serviço de modelos que fazem referência a macros.

Para usar uma macro, faça referência a ela no seu modelo:

  • Para processar uma seção ou um trecho, de um modelo, faça referência à macro em uma função Fn::Transform localizada em relação ao conteúdo do modelo que você deseja transformar. Ao usar Fn::Transform, você também pode transmitir os parâmetros especificados.

  • Para processar um modelo inteiro, faça referência à macro na seção Transformação do modelo.

Depois, normalmente você cria um conjunto de alterações e o executa. (O processamento de macros pode adicionar vários recursos dos quais você não tem conhecimento. Para garantir que você saiba todas as alterações apresentadas pelas macros, é altamente recomendável que você use conjuntos de alterações.) O AWS CloudFormation transmite o conteúdo do modelo especificado, além de qualquer outro parâmetro especificado, para a função Lambda especificada no recurso de macro. A função Lambda retorna o conteúdo do modelo processado, seja um trecho ou um modelo inteiro.

Depois que todas as macros do modelo tiverem sido chamadas, o AWS CloudFormation gerará um conjunto de alterações que inclui o conteúdo do modelo processado. Após revisar o conjunto de alterações, execute-o para aplicar as alterações.

Importante

Se o modelo do conjunto de pilhas fizer referência a uma ou mais macros, você deverá criar o conjunto de pilhas diretamente do modelo processado, sem primeiro revisar as alterações resultantes em um conjunto de alterações. Para criar ou atualizar o conjunto de pilhas diretamente, você deve usar a ação CreateStackSet ou UpdateStackSet e especificar o recurso CAPABILITY_AUTO_EXPAND. Antes de criar ou atualizar um conjunto de pilhas de um modelo que faça referência a macros diretamente, certifique-se de saber qual processamento as macros executam.


            Use a função intrínseca Fn::Transform ou a seção Transform do modelo para transmitir o conteúdo do modelo e os parâmetros associados para a função Lambda subjacente da macro, que retorna o conteúdo do modelo processado.
nota

Se você estiver certo de criar ou atualizar uma pilha diretamente de um modelo processado, sem primeiro analisar as alterações propostas em um conjunto de alterações, será possível fazer isso especificando o recurso CAPABILITY_AUTO_EXPAND durante uma solicitação UpdateStack ou CreateStack. Você só deve criar pilhas diretamente de um modelo que faz referência a macros, se souber qual processamento as macros executam.

Além disso, conjuntos de alterações não são compatíveis com pilhas aninhadas no momento. Se você deseja criar uma pilha de um modelo de pilhas que faz referência a macros e contém pilhas aninhadas, você deverá criar a pilha diretamente do modelo usando este recurso.

Para obter mais informações, consulte CreateStack ou UpdateStack, no AWS CloudFormation API Reference.

Criar uma definição de macros do AWS CloudFormation

Quando você cria uma definição de macro, ela disponibiliza a função Lambda subjacente na conta especificada, para que o AWS CloudFormation possa invocá-la para processar os modelos.

Interface de funções de macro do AWS CloudFormation

Para macros, o AWS CloudFormation invoca as funções Lambda subjacentes com o seguinte mapeamento de eventos. O AWS CloudFormation envia sua solicitação no formato JSON e espera que a resposta da função seja formatada como JSON também.

{ "region" : "us-east-1", "accountId" : "$ACCOUNT_ID", "fragment" : { ... }, "transformId" : "$TRANSFORM_ID", "params" : { ... }, "requestId" : "$REQUEST_ID", "templateParameterValues" : { ... } }
  • região

    A região na qual a macro reside.

  • accountId

    O ID de conta da conta da qual a macro está invocando a função Lambda.

  • fragment

    O conteúdo do modelo disponível para processamento personalizado, no formato JSON.

    • Para macros incluídas no modelo Transform, essa seção é o modelo inteiro, exceto pela seção Transform.

    • Para macros incluídas em uma chamada de função intrínseca Fn::Transform, isso inclui todos os nós irmãos (e os filhos deles) com base na localização da função intrínseca no modelo, exceto pela função Fn::Transform. Para obter mais informações, consulte Escopo de macros do AWS CloudFormation.

  • transformId

    O nome da macro que invoca essa função.

  • params

    Para chamadas de função Fn::Transform, quaisquer parâmetros especificados para a função. O AWS CloudFormation não avalia esses parâmetros antes de os transmitir à função.

    Para macros incluídas na seção do modelo Transform, essa seção é vazia.

  • requestId

    O ID da solicitação que invoca essa função.

  • templateParameterValues

    Quaisquer parâmetros especificados na seção Parâmetros do modelo. O AWS CloudFormation avalia esses parâmetros antes de os transmitir à função.

O AWS CloudFormation espera que a função subjacente retorne uma resposta no seguinte formato JSON:

{ "requestId" : "$REQUEST_ID", "status" : "$STATUS", "fragment" : { ... } }
  • requestId

    O ID da solicitação que invoca essa função. Isso deve corresponder ao ID de solicitação fornecido pelo AWS CloudFormation ao invocar a função.

  • status

    O status da solicitação (não diferencia maiúsculas de minúsculas). Deve ser definido como success. O AWS CloudFormation trata qualquer outra resposta como uma falha.

  • fragment

    O conteúdo de modelo processado para o AWS CloudFormation incluir no modelo processado, incluindo irmãos. O AWS CloudFormation substitui o conteúdo do modelo que é transmitido para a função Lambda pelo fragmento de modelo que ele recebe na resposta do Lambda.

    O conteúdo do modelo processado deve ser um JSON válido, e sua inclusão no modelo processado deve resultar em um modelo válido.

    Se a função não chegar a alterar o conteúdo do modelo que o AWS CloudFormation transmite a ela, mas você ainda precisar incluir esse conteúdo no modelo processado, sua função precisará retornar conteúdo de modelo ao AWS CloudFormation em sua resposta.

  • errorMessage

    A mensagem de erro que explica por que a transformação falhou. O CloudFormation exibe esta mensagem de erro no painel Events (Eventos) da página Stack details (Detalhes da pilha) para a sua pilha.

    Por exemplo, “Error creating change set: Transform AWS account account number::macro name failed with: error message string”.

Para obter informações sobre considerações adicionais ao criar macros, consulte Considerações ao criar definições de macro do AWS CloudFormation.

Escopo e permissões de conta de macros do AWS CloudFormation

Você pode usar macros apenas na conta em que elas foram criadas como um recurso. O nome da macro deve ser exclusivo dentro de uma conta especificada. No entanto, você pode disponibilizar a mesma funcionalidade em várias contas, ativando o acesso entre contas na função Lambda subjacente e, em seguida, criando definições de macro que fazem referência a essa função em várias contas. No exemplo abaixo, três contas contêm definições de macro, cada uma apontando para a mesma função Lambda.


                    Ao permitir o acesso entre contas na função Lambda, a AWS permite que você crie macros em várias contas que fazem referência a essa função.

Para obter mais informações, consulte Overview of managing access permissions to your AWS Lambda resources (Visão geral do gerenciamento das permissões de acesso aos recursos do ) no AWS Lambda Developer Guide.

Para criar uma definição de macro, o usuário deve ter permissões para criar uma pilha ou conjunto de pilhas dentro da conta especificada.

Para o AWS CloudFormation executar com êxito uma macro incluída em um modelo, o usuário deve ter permissões Invoke para a função Lambda subjacente. Para evitar possível dimensionamento de permissões, o AWS CloudFormation personifica o usuário ao executar a macro. Para obter mais informações, consulte Modelo de permissões do Lambda no AWS Lambda Developer Guide, e Ações e chaves de contexto de condição para o AWS Lambda no Guia do usuário do IAM.

As transformações Transformação AWS::Serverless e Transformação AWS::Include são macros hospedadas pelo AWS CloudFormation. Não são necessárias permissões especiais para usá-las, e elas estão disponíveis em qualquer conta no AWS CloudFormation.

Depurar macros do AWS CloudFormation

Para ajudar na depuração, você também pode especificar as propriedades LogRoleArn e LogGroupName ao criar o tipo de recurso AWS::CloudFormation::Macro para a sua macro. Essas propriedades permitem que você especifique o grupo de logs do CloudWatch ao qual o AWS CloudFormation envia informações de registro de erros ao invocar a função AWS Lambda subjacente da macro e a função que o AWS CloudFormation deve assumir ao enviar entradas de log para esses logs.

Faturamento

Quando uma macro é executada, o proprietário da função Lambda é cobrado por todos os custos relacionados à execução dessa função.

As transformações Transformação AWS::Serverless e Transformação AWS::Include são macros hospedadas pelo AWS CloudFormation. Não há custo pelo uso desses recursos.

Considerações ao criar definições de macro do AWS CloudFormation

Ao criar definições de macro, lembre-se do seguinte:

  • Macros têm suporte apenas em regiões da AWS nas quais o AWS Lambda está disponível. Para obter uma lista das regiões em que o Lambda está disponível, consulte http://docs.aws.amazon.com/general/latest/gr/rande.html#lambda_region.

  • Todos os trechos do modelo processado deve ser um JSON válido.

  • Quaisquer trechos de modelo processados devem passar por verificações de validação para uma operação de criação de pilha, atualização de pilha, criação de conjunto de pilhas ou atualização de conjunto de pilhas.

  • O AWS CloudFormationresolve as macros primeiro e depois processa o modelo. O modelo resultante deve ser um JSON válido e não deve exceder o limite de tamanho do modelo.

  • Devido à ordem na qual o CloudFormation processa elementos em um modelo, uma macro não pode incluir módulos no conteúdo do modelo processado que ela retorna ao CloudFormation. Para mais informações sobre módulos, consulte Como desenvolver módulos no Guia do usuário da CLI do CloudFormation .

  • Ao usar o recurso de reversão de atualização, o AWS CloudFormation utiliza uma cópia do modelo original. Ele reverterá para o modelo original, mesmo se o trecho incluído tiver sido alterado.

  • A inclusão de macros em macros não funciona, já que não os processamos de modo iterativo.

  • No momento, a função intrínseca Fn::ImportValue não é compatível em macros.

  • As funções intrínsecas incluídas no modelo são avaliadas depois de quaisquer macros. Portanto, o conteúdo do modelo processado retornado pela macro pode incluir chamadas para funções intrínsecas, e estas são avaliadas como de costume.

  • No momento, o StackSets não suporta a criação ou atualização de conjuntos de pilhas com permissões gerenciadas por serviço de modelos que fazem referência a macros do AWS CloudFormation.

  • Se o modelo do conjunto de pilhas fizer referência a uma ou mais macros, você deverá criar ou atualizar o conjunto de pilhas diretamente do modelo processado, sem primeiro revisar as alterações resultantes em um conjunto de alterações. Para criar ou atualizar o conjunto de pilhas diretamente, use a ação CreateStackSet ou UpdateStackSet e especifique o recurso CAPABILITY_AUTO_EXPAND. O processamento de macros pode adicionar vários recursos dos quais você não tem conhecimento. Antes de criar ou atualizar um conjunto de pilhas de um modelo que faça referência a macros diretamente, certifique-se de saber qual processamento as macros executam.

  • Conjuntos de alterações atualmente não dão suporte a pilhas aninhadas. Se quiser criar ou atualizar uma pilha usando um modelo que faz referência a macros e contém pilhas aninhadas, crie ou atualize a pilha diretamente. Para fazer isso, use a ação CreateStack or UpdateStack e especifique o recurso CAPABILITY_AUTO_EXPAND.

Para criar uma definição de macro do AWS CloudFormation

  1. Crie uma função AWS Lambda que processe modelos do AWS CloudFormation.

    A função Lambda que você criar realizará o processamento do conteúdo do modelo. Sua função pode processar qualquer parte de um modelo, até o modelo inteiro. Para obter informações sobre o mapeamento de eventos que a sua função deve seguir, consulte Interface de funções de macro do AWS CloudFormation. Para obter informações sobre considerações adicionais ao criar macros, consulte Considerações ao criar definições de macro do AWS CloudFormation.

  2. Crie um modelo que contenha um tipo de recurso AWS::CloudFormation::Macro.

    • É necessário especificar as propriedades Name e FunctionName. A propriedade FunctionName especifica o ARN da função Lambda a ser chamada quando o AWS CloudFormation executa a macro.

    • Para ajudar na depuração, você também pode especificar as propriedades LogRoleArn e LogGroupName.

  3. Crie uma pilha com base no modelo que contém a macro na conta desejada ou crie um conjunto de pilhas com permissões autogerenciadas com base no modelo que faz referência à macro na conta de administrador e, em seguida, crie instâncias de pilha nas contas de destino desejadas.

    Depois que o AWS CloudFormation criar com êxito as pilhas que contêm a definição da macro, a macro estará disponível para uso nessas contas.

Usar macros do AWS CloudFormation em seus modelos

Depois que o AWS CloudFormation criar com êxito as pilhas que contêm a definição da macro, a macro estará disponível para uso nessas contas. Você usa uma macro fazendo referência a ela em um modelo, no local apropriado relevante para o conteúdo do modelo que você deseja processar.

Ordem de avaliação de macros do AWS CloudFormation

Você pode fazer referência a várias macros em um determinado modelo, incluindo transformações hospedadas pelo AWS CloudFormation, como Transformação AWS::Include e Transformação AWS::Serverless.

As macros são avaliadas em ordem, com base na sua localização no modelo, da mais profundamente aninhada até a mais genérica. Macros no mesmo local do modelo são avaliadas em série com base na ordem em que estão listadas.

Transformações como AWS::Include e AWS::Transform são tratadas como qualquer outra macro em termos de ordem e escopo de ação.

Por exemplo, no modelo de exemplo abaixo, o AWS CloudFormation avalia primeiro a macro PolicyAdder, pois ela é a macro mais profundamente aninhada no modelo. O AWS CloudFormation em seguida avalia MyMacro antes de avaliar AWS::Serverless porque ela está listada antes de AWS::Serverless na seção Transform.

AWSTemplateFormatVersion: 2010-09-09 Transform: [MyMacro, AWS::Serverless] Resources: WaitCondition: Type: AWS::CloudFormation::WaitCondition MyBucket: Type: 'AWS::S3::Bucket' Properties: BucketName: MyBucket Tags: [{"key":"value"}] 'Fn::Transform': - Name: PolicyAdder CorsConfiguration:[] MyEc2Instance: Type: 'AWS::EC2::Instance' Properties: ImageID: "ami-123"

Escopo de macros do AWS CloudFormation

Macros referenciadas na seção Transform de um modelo podem processar todo o conteúdo desse modelo.

Macros referenciadas em uma função Fn::Transform podem processar o conteúdo de qualquer um dos elementos irmãos (incluindo filhos) dessa função Fn::Transform no modelo.

Por exemplo, no modelo de exemplo abaixo, AWS::Include pode processar todas as propriedades MyBucket com base na localização da função Fn::Transform que o contém. MyMacro pode processar o conteúdo de todo o modelo devido à sua inclusão na seção Transform.

// Start of processable content for MyMacro AWSTemplateFormatVersion: 2010-09-09 Transform: [MyMacro] Resources: WaitCondition: Type: AWS::CloudFormation::WaitCondition MyBucket: Type: 'AWS::S3::Bucket' //Start of processable content for AWS::Include Properties: BucketName: MyBucket Tags: [{"key":"value"}] 'Fn::Transform': - Name: 'AWS::Include' Parameters: Location: s3://MyAmazonS3BucketName/MyFileName.yaml CorsConfiguration:[] //End of processable content for AWS::Include MyEc2Instance: Type: 'AWS::EC2::Instance' Properties: ImageID: "ami-123" // End of processable content for MyMacro

Conjuntos de alterações e macros do AWS CloudFormation

Para criar ou atualizar uma pilha usando um modelo que faz referência a macros, normalmente você cria um conjunto de alterações e o executa. Um conjunto de alterações descreve as ações que o CloudFormation executará com base no modelo processado. O processamento de macros pode adicionar vários recursos dos quais você não tem conhecimento. Para garantir que você esteja ciente de todas as alterações apresentadas pelas macros, é altamente recomendável usar conjuntos de alterações. Após revisar o conjunto de alterações, você poderá executá-lo para realmente aplicar as alterações.

Uma macro pode adicionar recursos do IAM a seu modelo. Para esses recursos, o AWS CloudFormation requer que você confirme suas funcionalidades. Como o AWS CloudFormation não pode saber quais recursos são adicionados antes de processar seu modelo, pode ser necessário confirmar as funcionalidades do IAM ao criar o conjunto de alterações, dependendo de as macros referenciadas incluírem ou não recursos do IAM. Dessa forma, quando você executar o conjunto de alterações, o AWS CloudFormation terá os recursos necessários ao criar recursos do IAM.

Importante

Se o modelo do conjunto de pilhas fizer referência a uma ou mais macros, você deverá criar o conjunto de pilhas diretamente do modelo processado, sem primeiro revisar as alterações resultantes em um conjunto de alterações. Para criar ou atualizar o conjunto de pilhas diretamente, você deve usar a ação CreateStackSet ou UpdateStackSet e especificar o recurso CAPABILITY_AUTO_EXPAND. Antes de criar ou atualizar um conjunto de pilhas de um modelo que faça referência a macros diretamente, certifique-se de saber qual processamento as macros executam.

nota

Se você estiver certo de criar ou atualizar uma pilha diretamente de um modelo processado, sem primeiro analisar as alterações propostas em um conjunto de alterações, será possível fazer isso especificando o recurso CAPABILITY_AUTO_EXPAND durante uma solicitação UpdateStack ou CreateStack. Você só deverá criar pilhas diretamente de um modelo de pilha que contém macros se souber o que o processamento da macro executa. Você não pode usar conjuntos de alterações com macros de conjunto de pilhas; você deve atualizar seu conjunto de pilhas diretamente.

Para obter mais informações, consulte CreateStack ou UpdateStack, no AWS CloudFormation API Reference.

Se usar a AWS CLI, você poderá usar os comandos package e deploy para reduzir o número de etapas para iniciar pilhas com base em modelos que fazem referência a macros. Para obter mais informações, consulte Implantar aplicativos no Lambda no AWS Lambda Developer Guide.

Etapa do modelo e macros do CloudFormation

A etapa de um modelo indica se ele é o modelo original enviado pelo usuário ou um modelo em que o AWS CloudFormation processou as macros.

  • Original: o modelo que o usuário enviou originalmente para criar ou atualizar a pilha ou o conjunto de pilhas.

  • Processed: o modelo que o AWS CloudFormation usou para criar ou atualizar a pilha ou o conjunto de pilhas após o processamento de todas as macros referenciadas. O modelo processado é formatado como JSON, mesmo que o modelo original tenha sido formatado como YAML.

Use o modelo processado para solucionar problemas de pilhas. Se um modelo não referenciar macros, os modelos original e processado serão idênticos.

Você pode usar o console do AWS CloudFormation ou a AWS CLI para ver a etapa de um modelo de pilha.

nota

O tamanho máximo de um modelo de pilha processado é de 51.200 bytes quando transmitido diretamente em uma solicitação CreateStack, UpdateStack ou ValidateTemplate, ou 460.800 bytes quando transmitido como um objeto do S3 usando um URL do modelo do Amazon S3. No entanto, durante o processamento, o CloudFormation atualiza o estado temporário do modelo enquanto ele processa serialmente as macros contidas no modelo. Por causa disso, o tamanho do modelo durante o processamento pode temporariamente exceder o tamanho permitido de um modelo totalmente processado. O CloudFormation permite algum buffer para esses modelos em andamento. No entanto, você deve projetar modelos e macros tendo em mente o tamanho máximo permitido para um modelo de pilha processado.

Se o CloudFormation retornar um erro Transformation data limit exceeded ao processar seu modelo, é porque ele excedeu o tamanho máximo de modelo que o CloudFormation permite durante o processamento.

Para resolver esse problema, considere o seguinte:

  • Reestruture o modelo em vários modelos para evitar exceder o tamanho máximo de modelos em andamento. Por exemplo:

  • Reduza o tamanho do fragmento de modelo retornado por uma determinada macro. O CloudFormation não altera o conteúdo dos fragmentos retornados por macros.

Como usar uma macro do AWS CloudFormation no seu modelo

nota

Para o AWS CloudFormation executar com êxito uma macro referenciada em um modelo, o usuário deve ter permissões Invoke para a função Lambda subjacente. Para obter mais informações, consulte Overview of managing access permissions to your AWS Lambda resources (Visão geral do gerenciamento das permissões de acesso aos recursos do ) no AWS Lambda Developer Guide.

  1. Inclua uma referência à macro no seu modelo.

    • Para processar um trecho de sessão, faça referência à macro em uma função Fn::Transform localizada em relação ao conteúdo do modelo que você deseja processar.

    • Para processar o modelo inteiro, faça referência à macro na seção Transformação do modelo.

  2. Crie um conjunto de alterações usando o modelo.

    Importante

    Se o modelo do conjunto de pilhas fizer referência a uma ou mais macros, você deverá criar o conjunto de pilhas diretamente do modelo processado, sem primeiro revisar as alterações resultantes em um conjunto de alterações. Para criar ou atualizar o conjunto de pilhas diretamente, você deve usar a ação CreateStackSet ou UpdateStackSet e especificar o recurso CAPABILITY_AUTO_EXPAND. Antes de criar ou atualizar um conjunto de pilhas de um modelo que faça referência a macros diretamente, certifique-se de saber qual processamento as macros executam.

  3. Revise e execute o conjunto de alterações.

    Importante

    Se o modelo do conjunto de pilhas fizer referência a uma ou mais macros, você deverá criar o conjunto de pilhas diretamente do modelo processado, sem primeiro revisar as alterações resultantes em um conjunto de alterações. Para criar ou atualizar o conjunto de pilhas diretamente, você deve usar a ação CreateStackSet ou UpdateStackSet e especificar o recurso CAPABILITY_AUTO_EXPAND. Antes de criar ou atualizar um conjunto de pilhas de um modelo que faça referência a macros diretamente, certifique-se de saber qual processamento as macros executam.

Exemplos de macro

Além da demonstração Exemplo de macro: criar e usar uma macro neste guia, é possível encontrar exemplos de macros, incluindo código-fonte e modelos, na seção Exemplos de macros do repositório Amazon Web Services - Labs no GitHub. Esses exemplos são fornecidos "como estão" para fins de instrução.

Consulte também

AWS::CloudFormation::Macro

Transformação

Fn::Transform

Transformação AWS::Serverless

Transformação AWS::Include