Procesamientos personalizados en plantillas de CloudFormation con macros de plantillas

Las macros le permiten realizar un procesamiento personalizado de plantillas, desde acciones sencillas como operaciones de búsqueda y reemplazo, hasta amplias transformaciones de plantillas completas.

Para que se haga una idea de la gran variedad de posibilidades, piense en las transformaciones AWS::Include y AWS::Serverless, que son macros alojadas por CloudFormation:

Cómo funcionan las macros de CloudFormation

El procesamiento de plantillas con macros consta de dos fases principales: crear la macro en sí y luego usar la macro para procesar las plantillas.

Para crear una definición de macro, tiene que crear lo siguiente:

Para utilizar una macro, consulte la macro en su plantilla:

A continuación, se suele crear un conjunto de cambios y, a continuación, ejecutarlo. (El procesamiento de macros puede agregar varios recursos de los que quizás no esté al tanto. Para asegurarse de que está al tanto de todos los cambios hechos por las macros, le recomendamos usar conjuntos de cambios). CloudFormation pasa el contenido de la plantilla especificada, junto con cualquier parámetro especificado adicional, a la función de Lambda especificada en el recurso de macro. La función de Lambda devuelve el contenido de la plantilla procesada, ya sea como fragmento o como una plantilla completa.

Después de que se hayan llamado a todas las macros de la plantilla, CloudFormation genera un conjunto de cambios que incluye el contenido de la plantilla procesada. Después de revisar el conjunto de cambios, ejecútelo para aplicar los cambios.

Creación de una definición de macro de CloudFormation

Al crear una definición de macro, la definición de macro hace que la función de Lambda subyacente esté disponible en la cuenta especificada, de modo que CloudFormation la llame para procesar las plantillas.

Interfaz de la función de macro de CloudFormation

En el caso de las macros, CloudFormation llama a las funciones de Lambda subyacentes con la siguiente asignación de eventos. CloudFormation envía su solicitud en formato JSON y espera que la respuesta de la función también esté en formato JSON.

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

CloudFormation espera que la función subyacente devuelva una respuesta con formato JSON siguiente:

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

Para obtener más información sobre consideraciones adicionales al crear macros, consulte Consideraciones sobre la creación de definiciones de macros de CloudFormation.

Ámbito y permisos de la cuenta de macro de CloudFormation

Puede utilizar macros solo en la cuenta en la que se han creado como un recurso. El nombre de la macro tiene que ser único en una cuenta determinada. Sin embargo, puede hacer que la misma funcionalidad esté disponible en varias cuentas habilitando el acceso entre cuentas en la función de Lambda subyacente y, a continuación, creando definiciones de macro que haga referencia a dicha función en varias cuentas. En el ejemplo siguiente, tres cuentas macro contienen definiciones y cada una de ellas apunta a la misma función de Lambda.

Para obtener más información, consulte Información general de la administración de permisos de acceso a sus recursos de AWS Lambda) en la Guía para desarrolladores de AWS Lambda.

Para crear una definición de macro, el usuario debe tener permisos para crear una pila o un conjunto de pilas dentro de la cuenta especificada.

Para que CloudFormation ejecute correctamente una macro incluida en una plantilla, el usuario debe tener permisos Invoke para la función de Lambda subyacente. Para evitar posibles transmisiones de permisos, CloudFormation representa al usuario al ejecutar la macro. Para obtener más información, consulte Modelo de permisos de Lambda en la Guía para desarrolladores de AWS Lambda y Claves de contexto de condición y acciones para AWS Lambda en la Guía del usuario de IAM.

Las transformaciones Transformación AWS::Serverless y Transformación AWS::Include son macros alojadas por CloudFormation. No se necesitan permisos especiales para utilizarlas y están disponibles desde cualquier cuenta en CloudFormation.

Depuración de macros de CloudFormation

Para ayudar en la depuración, también puede especificar las propiedades LogRoleArn y LogGroupName cuando cree el tipo de recurso AWS::CloudFormation::Macro para su macro. Estas propiedades le permiten especificar el grupo de registro de CloudWatch al que CloudFormation envía la información de registro de errores al invocar la función de AWS Lambda subyacente de la macro y el rol que CloudFormation debe asumir al enviar entradas de registro a dichos registros.

Facturación

Cuando se ejecuta una macro, se factura al propietario de la función de Lambda todos los gastos relacionados con la ejecución de esa función.

Las transformaciones Transformación AWS::Serverless y Transformación AWS::Include son macros alojadas por CloudFormation. No se cobra por usarlas.

Consideraciones sobre la creación de definiciones de macros de CloudFormation

Al crear definiciones de macros, tenga en cuenta lo siguiente:

Uso de macros de CloudFormation en sus plantillas

Una vez que CloudFormation haya creado correctamente las pilas que contienen la definición de la macro, esta estará disponible para su uso en dichas cuentas. Una macro se utiliza haciendo referencia a ella en una plantilla, en la ubicación adecuada relevante para el contenido de la plantilla que desea procesar.

Orden de evaluación de macros de CloudFormation

Puede consultar varias macros de una determinada plantilla, incluidas transformaciones alojadas por CloudFormation, como Transformación AWS::Include y Transformación AWS::Serverless.

Las macros se evalúan en orden, en función de su ubicación en la plantilla, desde la que esté más profundamente anidada hasta la más general. Las macros que están en la misma ubicación de la plantilla se evalúan en serie en función del orden en que aparecen en la lista.

Las transformaciones como, por ejemplo, AWS::Include y AWS::Transform, se tratan de la misma manera que cualquier otra macro en términos de orden y ámbito de acción.

Por ejemplo, en la siguiente plantilla de ejemplo, CloudFormation evalúa primero la macro PolicyAdder, ya que es la macro que está anidada más profundamente en la plantilla. A continuación, CloudFormation evalúa MyMacro antes de evaluar AWS::Serverless, ya que aparece antes de AWS::Serverless en la sección 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

Ámbito de las macros de CloudFormation

Las macros a las que se hace referencia en la sección Transform de una plantilla pueden procesar todo el contenido de dicha plantilla.

Las macros a las que se hace referencia en una función Fn::Transform pueden procesar el contenido de cualquiera de los elementos del mismo nivel (incluidos los elementos secundarios) de dicha función Fn::Transform en la plantilla.

Por ejemplo, en la siguiente plantilla de ejemplo, AWS::Include puede procesar todas las propiedades MyBucket, en función de la ubicación de la función Fn::Transform que lo contiene. MyMacro puede procesar el contenido de toda la plantilla debido a su inclusión en la sección 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 cambios y macros de CloudFormation

Para crear o actualizar una pila utilizando una plantilla que hace referencia a macros, normalmente debe crear un conjunto de cambios y ejecutarlo. Un conjunto de cambios describe las acciones que CloudFormation realizará en función de la plantilla procesada. El procesamiento de macros puede añadir numerosos recursos que usted podría desconocer. Para asegurarse de estar al tanto de todos los cambios hechos por las macros, sugerimos usar conjuntos de cambios. Después de revisar el conjunto de cambios, puede ejecutarlo para aplicar realmente los cambios.

Una macro puede añadir recursos de IAM a su plantilla. Para estos recursos, CloudFormation necesita que reconozca sus capacidades. Dado que CloudFormation no puede saber qué recursos se agregan antes de procesar su plantilla, es posible que tenga que reconocer las capacidades de IAM al crear el conjunto de cambios, en función de si las macros a las que se hace referencia contienen recursos de IAM. De este modo, al ejecutar el conjunto de cambios, CloudFormation tiene las capacidades necesarias para crear recursos de IAM.

Si utiliza la AWS CLI, puede utilizar los comandos package y deploy para reducir el número de pasos para lanzar pilas desde plantillas que hacen referencia a macros. Para obtener más información, consulte Implementación de aplicaciones basadas en Lambda en la Guía para desarrolladores de AWS Lambda.

Fase de plantilla y macros de CloudFormation

La fase de una plantilla indica si se trata de la plantilla enviada por el usuario original o una plantilla en la que CloudFormation ha procesado las macros.

Utilice la plantilla procesada para la resolución de problemas de la pila. Si una plantilla no hace referencia a macros, las plantillas original y procesada son idénticas.

Puede utilizar la consola de CloudFormation o AWS CLI para ver la fase de la plantilla de una pila.

Ejemplos de macros

Además del tutorial Ejemplo de macro: creación y uso de una macro de esta guía, encontrará ejemplos de macros, incluido el código fuente y las plantillas, en nuestro repositorio de GitHub. Estos ejemplos se proporcionan “tal cual” para fines pedagógicos.

Véase también

AWS::CloudFormation::Macro

Sección de Transform para las plantillas de CloudFormation

Fn::Transform

Transformación AWS::Serverless

Transformación AWS::Include