Executar processamento personalizado em modelos do CloudFormation com macros de modelo

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, ambas macros hospedadas pelo CloudFormation:

• Transformação AWS::Include permite que você insira trechos de modelo de clichê em seus modelos.

• Transformação AWS::Serverless usa um modelo inteiro escrito na sintaxe do AWS Serverless Application Model (AWS SAM) e o transforma e expande em um modelo compatível com o CloudFormation. (Para obter mais informações sobre aplicações sem servidor e o AWS SAM, consulte Implantar aplicações baseadas no Lambda, no Guia do desenvolvedor do AWS Lambda).

Como as macros do CloudFormation funcionam

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 do Lambda de dentro de modelos do 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 dentro de uma conta, crie um modelo de pilha que inclua o recurso AWS::CloudFormation::Macro e, depois, crie uma pilha ou um conjunto de pilhas com permissões autogerenciadas por meio do modelo. AWS No momento, o CloudFormation StackSets não oferece suporte para a criação ou a 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 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 Transform 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ê pode não estar ciente. Para garantir que você conheça todas as alterações apresentadas pelas macros, é altamente recomendável usar conjuntos de alterações.) O CloudFormation transmite o conteúdo do modelo especificado, além de qualquer outro parâmetro especificado, para a função do 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 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.

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.

Para obter mais informações, consulte CreateStack ou UpdateStack, na Referência a APIs do AWS CloudFormation.

Criar uma definição de macro do CloudFormation

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

Interface de função de macro do CloudFormation

Para macros, o CloudFormation invoca as funções do Lambda subjacentes com o mapeamento de eventos a seguir. O 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 CloudFormation.

• transformId

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

• params

  Para chamadas à função Fn::Transform, quaisquer parâmetros especificados para a função. O CloudFormation não avalia esses parâmetros antes de passá-los para a 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 Parameters do modelo. O CloudFormation avalia esses parâmetros antes de passá-los para a função.

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

{
    "requestId" : "$REQUEST_ID",
    "status" : "$STATUS",
    "fragment" : { ... }
    "errorMessage": "optional error message for failures"
}

• requestId

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

• status

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

• fragment

  O conteúdo do modelo processado para o CloudFormation incluir no modelo processado, incluindo irmãos. O CloudFormation substitui o conteúdo do modelo que é transmitido para a função do 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 CloudFormation transmite a ela, mas você ainda precisar incluir esse conteúdo no modelo processado, a função precisará retornar conteúdo do modelo ao CloudFormation em sua resposta.

• errorMessage

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

  Por exemplo, um erro ao criar conjunto de alterações: a transformação número da conta da Conta da AWS::nome da macro em falha com: string da mensagem de erro.

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

Escopo e permissões de conta de macros do 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.

Para obter mais informações, consulte Visão geral do gerenciamento de permissões de acesso aos recursos do AWS Lambda, no Guia do desenvolvedor do AWS Lambda.

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

Para o CloudFormation executar com êxito uma macro incluída em um modelo, o usuário deve ter permissões Invoke para a função do Lambda subjacente. Para evitar um possível dimensionamento de permissões, o CloudFormation personifica o usuário ao executar a macro. Para obter mais informações, consulte Modelo de permissões do Lambda, no Guia do desenvolvedor do AWS Lambda, 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 CloudFormation. Não são necessárias permissões especiais para usá-las, e elas estão disponíveis em qualquer conta no CloudFormation.

Depurar macros do 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 CloudFormation envia informações de log de erros ao invocar a função do AWS Lambda subjacente da macro e a função que o 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 CloudFormation. Não há custo pelo uso desses recursos.

Considerações ao criar definições de macro do 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 de regiões em que o Lambda está disponível, consulte Endpoints e cotas do AWS Lambda.

• 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 CloudFormation resolve 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 Desenvolver módulos, no Guia do usuário da CLI do CloudFormation.

• Ao usar o recurso de reversão de atualização, o 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 dentro de macros não funciona porque não processamos macros de modo recursivo.

• 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 permite a criação nem a atualização de conjuntos de pilhas com permissões gerenciadas por serviço de modelos que fazem referência a macros do 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.

Como criar uma definição de macro do CloudFormation:

1. Crie uma função do AWS Lambda que processe modelos do 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ção de macro do CloudFormation. Para obter informações sobre considerações adicionais ao criar macros, consulte Considerações ao criar definições de macro do 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 do Lambda que deve ser invocada quando o 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 CloudFormation criar com êxito as pilhas que contêm a definição da macro, ela estará disponível para uso nessas contas.

Usar macros do CloudFormation nos modelos

Depois que o CloudFormation criar com êxito as pilhas que contêm a definição da macro, ela 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 CloudFormation

É possível fazer referência a várias macros em um determinado modelo, incluindo transformações hospedadas pelo 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 CloudFormation avalia primeiro a macro PolicyAdder, pois ela é a mais profundamente aninhada no modelo. Depois, o CloudFormation 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: amzn-s3-demo-bucket
        Tags: [{"key":"value"}]
        'Fn::Transform':
          - Name: PolicyAdder
        CorsConfiguration: []
    MyEc2Instance:
      Type: 'AWS::EC2::Instance'
      Properties:
        ImageID: ami-1234567890abcdef0

Escopo de macros do 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: amzn-s3-demo-bucket1
        Tags: [{"key":"value"}] 
        'Fn::Transform':
          - Name: 'AWS::Include'
              Parameters:
                Location: s3://amzn-s3-demo-bucket2/MyFileName.yaml
        CorsConfiguration: []
        # End of processable content for AWS::Include
    MyEc2Instance:
      Type: 'AWS::EC2::Instance' 
      Properties:
        ImageID: ami-1234567890abcdef0
# End of processable content for MyMacro

Conjuntos de alterações e macros do 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, sugerimos o uso de 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 CloudFormation requer que você confirme suas funcionalidades. Como o CloudFormation não pode saber quais recursos são adicionados antes de processar o 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 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 e deve atualizar seu conjunto de pilhas diretamente.

Para obter mais informações, consulte CreateStack ou UpdateStack, na Referência a APIs do AWS CloudFormation.

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 aplicações baseadas 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 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 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.

É possível usar o console do 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 1 MB 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 um buffer para esses modelos em processamento. 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:

  • Use os modelos de pilha aninhada para encapsular partes do modelo. Para obter mais informações, consulte Incorporar pilhas em outras pilhas usando pilhas aninhadas.

  • Crie várias pilhas e use referências entre pilhas para trocar informações entre elas. Para obter mais informações, consulte Consultar saídas de recurso em outra pilha do CloudFormation.

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

Como usar uma macro do CloudFormation no modelo

nota

Para o CloudFormation executar com êxito uma macro referenciada em um modelo, o usuário deve ter permissões Invoke para a função do Lambda subjacente. Para obter mais informações, consulte Visão geral do gerenciamento de permissões de acesso aos recursos do AWS Lambda, no Guia do desenvolvedor do AWS Lambda.

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 Transform 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 orientação passo a passo Exemplo de macro: criar e usar uma macro apresentada neste guia, é possível encontrar macros de exemplo, incluindo código-fonte e modelos, em nosso repositório do GitHub. Esses exemplos são fornecidos "como estão" para fins de instrução.

Consulte também

AWS::CloudFormation::Macro

Transform

Fn::Transform

Transformação AWS::Serverless

Transformação AWS::Include