Uso de macros de AWS CloudFormation para realizar un procesamiento personalizado en plantillas - AWS CloudFormation

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Uso de macros de AWS CloudFormation para realizar un procesamiento personalizado en 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 AWS CloudFormation:

Cómo funcionan las macros de AWS 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:

  • Una función de AWS Lambda para realizar el procesamiento de la plantilla. Esta función de Lambda acepta un fragmento de código o bien la totalidad de la plantilla, así como los parámetros adicionales que se definan. Devuelve el fragmento de código de plantilla procesados o toda la plantilla como respuesta.

  • Un recurso del tipo AWS::CloudFormation::Macro, para que los usuarios puedan llamar a la función Lambda desde plantillas de AWS CloudFormation. Este recurso especifica el ARN de la función Lambda para invocar esta macro y propiedades opcionales adicionales para ayudar con la depuración. Para crear este recurso dentro de una cuenta, cree una plantilla de pila que incluya un recurso AWS::CloudFormation::Macro y, a continuación, cree otra pila a partir de la plantilla.

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

  • Para procesar una sección o fragmento de código de una plantilla, consulte la macro en una función Fn::Transform que se encuentre ubicada en relación con el contenido de la plantilla que desea transformar. Cuando utilice Fn::Transform, también puede transferir todos los parámetros especificados que requiera.

  • Para procesar una plantilla completa, consulte la macro en la sección Transform de la plantilla.

A continuación, se suele crear un conjunto de cambios y, a continuación, ejecutarlo. (El procesamiento de macros puede añadir numerosos recursos que usted podría desconocer. Para asegurarse de que es consciente de todos los cambios que las macros han introducido, le recomendamos que utilice conjuntos de cambios.) AWS CloudFormation transfiere el contenido de la plantilla adicional especificada, junto con los parámetros adicionales detallados, a la función Lambda indicada en el recurso de la macro. La función 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, AWS 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.


            Utilice la función intrínseca Fn::Transform o la sección Transform de la plantilla, para pasar el contenido de la plantilla y sus parámetros asociados a la función Lambda subyacente de la macro, que devuelve el contenido de la plantilla procesada.
nota

Si se siente cómodo creando o actualizando una pila directamente desde una plantilla procesada, sin antes haber revisado los cambios propuestos en un conjunto de cambios, puede hacerlo especificando la capacidad CAPABILITY_AUTO_EXPAND durante una solicitud UpdateStack o CreateStack. Solo debe crear pilas directamente desde una plantilla de pila que contiene macros si sabe qué procesamiento realiza la macro.

Además, los conjuntos de cambios no admiten actualmente pilas anidadas. Si desea crear una pila a partir de una plantilla de pila que contiene macros y pilas anidadas, debe crear la pila directamente a partir de la plantilla utilizando esta capacidad.

Para obtener más información, consulte CreateStack o UpdateStack en la AWS CloudFormation API Reference.

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

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

Interfaz de la función de macro de AWS CloudFormation

Para macros, AWS CloudFormation invoca las funciones Lambda subyacentes con el siguiente mapeo de eventos. AWS 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" : { ... } }
  • 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 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 Ámbito de las macros de AWS CloudFormation.

  • transformId

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

  • params

    Para las llamadas de función Fn::Transform, todos los parámetros especificados para la función. AWS 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 Parámetros de la plantilla. AWS CloudFormation evalúa estos parámetros antes de transferirlos a la función.

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

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

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

  • status

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

  • fragment

    El contenido de la plantilla procesada para AWS CloudFormation para incluir en la plantilla procesada, incluidos los hermanos. AWS CloudFormation sustituye el contenido de la plantilla que se transfiere a la función Lambda con el fragmento de código de plantilla que recibe en la respuesta de la 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 AWS 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 AWS 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 Eventos de la página Detalles de la pila de la pila.

    Por ejemplo, "Error al crear un conjunto de cambios: Transformación de número de cuenta de AWS።error del nombre de la macro con: cadena de mensaje de error".

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

Ámbito y permisos de la cuenta de macro de AWS 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 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 Lambda.


                    Al permitir el acceso entre cuentas en la función Lambda, AWS le permite crear macros en varias cuentas que hacen referencia a esa función.

Para obtener más información, consulte Información general de la administración de permisos de acceso a los recursos de AWS Lambda en la AWS Lambda Developer Guide.

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

Para que AWS CloudFormation ejecute correctamente una macro incluida en una plantilla, el usuario debe tener permisos Invoke para la función Lambda subyacente. Para evitar posibles transmisiones de privilegios, AWS CloudFormation representa al usuario al ejecutar la macro. Para obtener más información, consulte la sección Modelo de permisos de Lambda en la AWS Lambda Developer Guide y la sección 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 AWS CloudFormation. No se necesitan permisos especiales para utilizarlas y están disponibles desde cualquier cuenta en AWS CloudFormation.

Depuración de macros de AWS CloudFormation

Para ayudar en la depuración, también puede especificar las propiedades LogGroupName y LogRoleArn al crear el tipo de recurso AWS::CloudFormation::Macro para su macro. Estas propiedades le permiten especificar el grupo de registros de CloudWatch al que AWS CloudFormation envía la información de registro de errores al invocar la función AWS Lambda subyacente de la macro y el rol que AWS 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 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 AWS CloudFormation. No se cobra por usarlas.

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

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

  • Las macros se admiten únicamente en las regiones en las que AWS Lambda está disponible. Para obtener una lista de las regiones en las que Lambda está disponible, consulte http://docs.aws.amazon.com/general/latest/gr/rande.html#lambda_region.

  • Todos los fragmentos de código de plantilla procesados tienen que ser un JSON válido.

  • Todos los fragmentos de código de plantilla procesados tienen que pasar comprobaciones de validación para crear una pila o actualizar una operación de pila.

  • AWS CloudFormation resuelve en primer lugar las macros y, a continuación, procesa la plantilla. La plantilla obtenida tiene que ser un JSON válido y no debe superar el límite de tamaño de la plantilla.

  • Debido al orden en que CloudFormation procesa los elementos de una plantilla, una macro no puede incluir módulos en el contenido de la plantilla procesada que devuelve a CloudFormation. Para obtener más información sobre los módulos, consulte Desarrollo de módulos en la Guía del usuario de CloudFormation CLI.

  • Cuando se utiliza la característica de restauración de actualizaciones, AWS CloudFormation utiliza una copia de la plantilla original. Se restaura en la plantilla original incluso si el fragmento de código incluido se ha cambiado.

  • La inclusión de macros en macros no funciona ya que las macros no se procesan de manera iterativa.

  • La función intrínseca Fn::ImportValue no es compatible actualmente en las macros.

  • Las funciones intrínsecas incluidas en la plantilla se evalúan después de cualquier macro. Por lo tanto, el contenido de plantilla procesado que su macro devuelve puede incluir llamadas a funciones intrínsecas, y se evalúan como de costumbre.

  • Las macros de AWS CloudFormation no se admiten en conjuntos de pilas.

  • Los conjuntos de cambios actualmente no admiten pilas anidadas. Si desea crear o actualizar una pila mediante una plantilla de pilas que contiene macros y pilas anidadas, tiene que crear o actualizar la pila directamente. Para ello, utilice la acción CreateStack o UpdateStack y especifique la capacidad CAPABILITY_AUTO_EXPAND.

Para crear una definición de macro de AWS CloudFormation

  1. Desarrolle una función AWS Lambda que procese plantillas de AWS CloudFormation.

    La función Lambda que crea realiza el procesamiento del contenido de la plantilla. Su función puede procesar cualquier parte de una plantilla, incluida la plantilla entera. Para obtener más información acerca del mapeo de eventos que la función debe cumplir, consulte Interfaz de la función de macro de AWS CloudFormation. Para obtener más información sobre consideraciones adicionales al crear macros, consulte Consideraciones sobre la creación de definiciones de macros de AWS CloudFormation.

  2. Crear una plantilla que contenga un AWS:: CloudFormation:: Macro tipo de recurso.

    • Tiene que especificar las propiedades Name y FunctionName. La propiedad FunctionName especifica el ARN de la función Lambda para invocar cuándo AWS CloudFormation ejecuta la macro.

    • Para ayudar en la depuración, también puede especificar las propiedades LogGroupName y LogRoleArn.

  3. Cree una pila a partir de la plantilla que contiene la macro en la cuenta que desee.

    Una vez que AWS CloudFormation haya creado correctamente la pila que contiene la definición de la macro, esta estará disponible para su uso en dicha cuenta.

Uso de macros de AWS CloudFormation en sus plantillas

Una vez que AWS CloudFormation haya creado correctamente la pila que contiene la definición de la macro, esta estará disponible para su uso en dicha cuenta. Una macro se utiliza consultándola en la plantilla de pila, en la ubicación adecuada relevante para el contenido de la plantilla que desea procesar.

Orden de evaluación de macros de AWS CloudFormation

Puede consultar varias macros de una determinada plantilla, incluidas transformaciones alojadas por AWS 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 basada siguiendo el 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 muestra de plantilla de abajo, AWS CloudFormation evalúa primero la macro PolicyAdder, ya que es la macro que está anidada más profundamente en la plantilla. Después AWS CloudFormation evalúa MyMacro antes de evaluar AWS::Serverless, ya que está en la lista antes que 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: MyBucket Tags: [{"key":"value"}] 'Fn::Transform': - Name: PolicyAdder CorsConfiguration:[] MyEc2Instance: Type: 'AWS::EC2::Instance' Properties: ImageID: "ami-123"

Ámbito de las macros de AWS 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 secundarios (incluidos los elementos secundarios) de dicha función Fn::Transform en la plantilla.

Por ejemplo, en la muestra de plantilla de abajo, 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: 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 cambios y macros de AWS 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 garantizar que es consciente de todos los cambios introducidos por las macros, le recomendamos que utilice 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, AWS CloudFormation necesita que reconozca sus capacidades. Dado que AWS CloudFormation no puede saber qué recursos se añaden 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, AWS CloudFormation tiene las capacidades necesarias para crear recursos de IAM.

nota

Si se siente cómodo creando o actualizando una pila directamente desde una plantilla procesada, sin antes haber revisado los cambios propuestos en un conjunto de cambios, puede hacerlo especificando la capacidad CAPABILITY_AUTO_EXPAND durante una solicitud UpdateStack o CreateStack. Solo debe crear pilas directamente desde una plantilla de pila que contiene macros si sabe qué procesamiento realiza la macro.

Además, los conjuntos de cambios no admiten actualmente pilas anidadas. Si desea crear una pila a partir de una plantilla de pila que contiene macros y pilas anidadas, debe crear la pila directamente a partir de la plantilla utilizando esta capacidad.

Para obtener más información, consulte CreateStack o UpdateStack en la AWS CloudFormation API Reference.

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 Aplicaciones de AWS Lambda en la AWS Lambda Developer Guide.

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 AWS CloudFormation ha procesado las macros.

  • Original: la plantilla que el usuario envió originalmente para crear o actualizar la pila.

  • Processed: La plantilla AWS CloudFormation utilizada para crear o actualizar la pila después de procesar todas las macros de referencia. La plantilla procesada se formatea como JSON, incluso si la plantilla original tenía el formato YAML.

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 AWS CloudFormation o AWS CLI para ver la fase de la plantilla de una pila.

nota

El tamaño máximo de una plantilla de pila procesada es de 51.200 bytes cuando se pasa directamente a una solicitud ValidateTemplate, CreateStack, UpdateStack o 460.800 bytes cuando se pasa como un objeto S3 utilizando una URL de plantilla de Amazon S3. Sin embargo, durante el procesamiento, CloudFormation actualiza el estado temporal de la plantilla, ya que procesa en serie las macros contenidas en la plantilla. Por este motivo, el tamaño de la plantilla durante el procesamiento puede superar temporalmente el tamaño máximo permitido de una plantilla totalmente procesada. CloudFormation permite algún búfer para estas plantillas en proceso. Sin embargo, debería diseñar las plantillas y macros teniendo en cuenta el tamaño máximo permitido para una plantilla de pila procesada.

Si CloudFormation devuelve un error Transformation data limit exceeded al procesar su plantilla, significa que la plantilla ha superado el tamaño máximo de plantilla que CloudFormation permite durante el procesamiento.

Para resolver este problema, realice lo siguiente:

  • Reestructure la plantilla en varias plantillas para evitar superar el tamaño máximo de las plantillas en proceso. Por ejemplo:

  • Reduzca el tamaño de fragmento de plantilla devuelto por una determinado macro. CloudFormation no modifica el contenido de los fragmentos devuelto por macros.

Para utilizar una macro de AWS CloudFormation en la plantilla

nota

Para que AWS CloudFormation ejecute correctamente una macro a la que se hace referencia en una plantilla, el usuario debe tener permisos Invoke para la función Lambda subyacente. Para obtener más información, consulte Información general de la administración de permisos de acceso a los recursos de AWS Lambda en la AWS Lambda Developer Guide.

  1. Incluya una referencia a la macro en la plantilla.

    • Para procesar un fragmento de código de una plantilla, haga referencia a la macro en una función Fn::Transform que se encuentre ubicada en relación con el contenido de la plantilla que desea procesar.

    • Para procesar la plantilla completa, consulte la macro en la sección Transform de la plantilla.

  2. Cree un conjunto de cambios con la plantilla.

  3. Revise y ejecute el conjunto de cambios.

Ejemplos de macros

Además del Ejemplo de macro: creación y uso de una macro tutorial de esta guía, encontrará ejemplos de macros, incluido el código fuente y plantillas, en la sección Ejemplos de macros del repositorio Amazon Web Services - Labs en GitHub. Estos ejemplos se proporcionan "tal cual" para fines pedagógicos.

Véase también

AWS::CloudFormation::Macro

Transform

Fn::Transform

Transformación AWS::Serverless

Transformación AWS::Include