Descripción general de macros de CloudFormation - AWS CloudFormation
Cómo crear pilas directamenteConsideracionesAlcance y permisos de la cuenta de macro

Descripción general de 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, debe crear lo siguiente:

  • Una función de 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 de Lambda desde plantillas de CloudFormation. Este recurso especifica el ARN de la función de 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 el recurso AWS::CloudFormation::Macro y, a continuación, cree otra pila a partir de la plantilla. AWS Actualmente, CloudFormation StackSets no es compatible con la creación o la actualización de conjuntos de pilas con permisos administrados por servicios a partir de plantillas que hacen referencia a macros.

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

  • Para procesar una sección o un fragmento 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 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.

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 de Lambda subyacente de la macro, que devuelve el contenido de la plantilla procesada.

Cómo crear pilas directamente

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.

Para crear o actualizar una pila directamente desde una plantilla procesada, sin antes haber revisado los cambios propuestos en un conjunto de cambios, especifique la capacidad CAPABILITY_AUTO_EXPAND durante una solicitud CreateStack o UpdateStack. Solo debe crear pilas directamente desde una plantilla de pila que contiene macros si sabe qué procesamiento realiza la macro. No puede utilizar conjuntos de cambios con macros de conjuntos de pilas y debe actualizar el conjunto de pilas directamente.

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

importante

Si la plantilla del conjunto de pilas hace referencia a una o más macros, debe crear el conjunto de pilas directamente desde la plantilla procesada, sin revisar primero los cambios resultantes en un conjunto de cambios. El procesamiento de macros puede añadir numerosos recursos que usted podría desconocer. Antes de crear o actualizar un conjunto de pilas a partir de una plantilla que haga referencia directamente a macros, asegúrese de saber qué procesamiento realiza cada macro.

Para reducir la cantidad de pasos para lanzar pilas desde plantillas que hagan referencia a macros, puede usar los comandos package y deploy de la AWS CLI. Para obtener más información, consulte Carga de artefactos locales en un bucket de S3 con la AWS CLI y Crear una pila que incluya transformaciones.

Consideraciones

Cuando trabaje con macros, tenga en cuenta las siguientes notas y limitaciones:

  • Las macros se admiten únicamente en Regiones de AWS donde Lambda está disponible. Para ver una lista de las regiones en las que Lambda está disponible, consulte Puntos de conexión y cuotas de AWS Lambda.

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

  • Cualquier fragmento de plantilla procesado debe pasar las comprobaciones de validación para una operación de creación de pila, actualización de pila, creación de conjunto de pilas o actualización de conjunto de pilas.

  • 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, consulte Orden de evaluación de macro.

  • Cuando se utiliza la característica de restauración de actualizaciones, 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 dentro de otras macros no funciona porque no procesamos las macros de forma recursiva.

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

  • Actualmente, StackSets no es compatible con la creación o la actualización de conjuntos de pilas con permisos administrados por servicios a partir de plantillas que hacen referencia a macros de CloudFormation.

Alcance y permisos de la cuenta de macro

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.

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

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 Administrar permisos en AWS Lambda en la Guía para desarrolladores de AWS Lambda y Acciones, recursos y claves de condición para AWS Lambda en la Referencia de autorizaciones de servicio.