Creación de una definición de macro de CloudFormation - AWS CloudFormation
Mapeo de eventosFormato de respuestaCreación de una definición de macroAlcance de la plantilla de macroOrden de evaluación de macro

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.

Mapeo de eventos

Cuando CloudFormation invoca la función de Lambda de una macro, envía una solicitud en formato JSON con la siguiente estructura:

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

  • region

    La región en la que la reside la macro.

  • accountId

    El ID de la cuenta desde la que la macro invoca la función de Lambda.

  • fragment

    El contenido de la plantilla disponible para el procesamiento personalizado, en formato JSON.

    • Para las macros incluidas en la sección de plantilla Transform, esto es toda la plantilla, a excepción de la sección Transform.

    • Para macros incluidas en una llamada de función intrínseca Fn::Transform, esto incluye todos los nodos secundarios (y sus hijos) en función de la ubicación de la función intrínseca dentro de la plantilla, excepto para la función Fn::Transform. Para obtener más información, consulte Alcance de la plantilla de macro.

  • transformId

    El nombre de la macro que invoca esta función.

  • params

    Para las llamadas de la función Fn::Transform, todos los parámetros especificados para la función. CloudFormation no evalúa estos parámetros antes de transferirlos a la función.

    Para macros incluidas en la sección de plantilla Transform, esta sección está vacía.

  • requestId

    El ID de la solicitud que invoca esta función.

  • templateParameterValues

    Todos los parámetros especificados en la sección Parameters de la plantilla. CloudFormation evalúa estos parámetros antes de transferirlos a la función.

Formato de respuesta

CloudFormation espera que la función de Lambda devuelva una respuesta con el siguiente formato JSON:

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

  • requestId

    El ID de la solicitud que invoca esta función. Debe coincidir con el ID de la solicitud que proporciona CloudFormation al invocar la función.

  • status

    El estado de la solicitud (no distingue entre mayúsculas y minúsculas). Debe definirse en success. CloudFormation trata todas las demás respuestas como error.

  • fragment

    El contenido de la plantilla procesada para que CloudFormation lo incluya en la plantilla procesada, incluidos los elementos secundarios. CloudFormation sustituye el contenido de la plantilla que se transfiere a la función de Lambda con el fragmento de código de plantilla que recibe en la respuesta de Lambda.

    El contenido de la plantilla procesada tiene que ser un formato JSON válido, y su inclusión en la plantilla procesada debe generar una plantilla válida.

    Si la función no cambia realmente el contenido de la plantilla que CloudFormation le pasa, pero el usuario sigue necesitando incluir ese contenido en la plantilla procesada, la función debe devolver dicho contenido de plantilla a CloudFormation en su respuesta.

  • errorMessage

    El mensaje de error que explica por qué falló la transformación. CloudFormation muestra este mensaje de error en el panel Events (Eventos) de la página Stack details (Detalles de la pila) para la pila.

    Por ejemplo:

    Error creating change set: Transform
                            Cuenta de AWS account
                            number::macro name failed with:
                            error message string.

Creación de una definición de macro

Crear una definición de macro de CloudFormation

  1. Cree una función de Lambda que se encargue del procesamiento del contenido de la plantilla. Puede procesar cualquier parte de una plantilla, incluso la plantilla completa.

  2. Cree una plantilla de CloudFormation que contenga un tipo de recurso AWS::CloudFormation::Macro y especifique las propiedades Name y FunctionName. La propiedad FunctionName debe contener el ARN de la función de Lambda para invocar cuándo CloudFormation ejecuta la macro.

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

  4. Cree una pila utilizando la plantilla con la macro de la cuenta en la que desee utilizarla. O cree un conjunto de pilas con permisos autoadministrados mediante la plantilla con la macro en la cuenta de administrador y, a continuación, cree instancias de pilas en las cuentas de destino.

  5. 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.

Alcance de la plantilla de macro

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

Orden de evaluación de macro

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