Uso de módulos para encapsular y reutilizar configuraciones de recursos

Losmódulos son una forma de empaquetar configuraciones de recursos para su inclusión en plantillas de pila, de forma transparente, administrable y repetible. Los módulos pueden encapsular configuraciones de servicios comunes y prácticas recomendadas como componentes esenciales modulares y personalizables para que pueda incluirlos en las plantillas de pila. Los módulos le permiten incluir configuraciones de recursos que incorporan prácticas recomendadas, conocimientos de dominio experto y directrices aceptadas en sus plantillas (para áreas como seguridad, cumplimiento, gestión y regulaciones del sector), sin tener que adquirir un conocimiento profundo de las complejidades de la implementación de recursos.

Por ejemplo, un experto en redes podría crear un módulo que contenga grupos de seguridad integrados y reglas de entrada/salida que cumplan con las directrices de seguridad. A continuación, podría incluir ese módulo en la plantilla para aprovisionar una infraestructura de red segura en su pila, sin tener que dedicar tiempo a averiguar cómo funcionan las VPC, las subredes, los grupos de seguridad y las gateway. Y dado que los módulos están versionados, si las pautas de seguridad cambian con el tiempo, el autor del módulo podría crear una nueva versión del módulo que incorpore esos cambios.

Las características del uso de módulos en sus plantillas incluyen:

• Previsibilidad: un módulo debe cumplir con el esquema que registra en el registro de CloudFormation, para que sepa en qué recursos puede resolver una vez que lo incluya en la plantilla.

• Reutilización: puede utilizar el mismo módulo en varias plantillas y cuentas.

• Trazabilidad: CloudFormation retiene el conocimiento de qué recursos de una pila se aprovisionaron desde un módulo, lo que le permite comprender fácilmente el origen de los cambios en los recursos.

• Capacidad de gestión: una vez registrado un módulo, puede administrarlo a través del registro de CloudFormation, incluido el control de versiones y la disponibilidad de cuentas y regiones.

Un módulo puede contener:

• Uno o más recursos que se aprovisionarán desde el módulo, junto con cualquier dato asociado, como salidas o condiciones.

• Cualquier parámetro del módulo, que le permite especificar valores personalizados cada vez que se utiliza el módulo.

Para obtener información sobre el desarrollo de tipos de módulos, consulte Desarrollo de tipos de módulo en la Guía del usuario de la interfaz de línea de comandos de CloudFormation.

Uso de módulos en una plantilla

Para utilizar un módulo, asegúrese de que está registrado en la cuenta y región en la que desea usarlo. Para obtener más información, consulte Extensiones públicas y privadas. Registre los módulos en el registro de CloudFormation como extensiones privadas. A continuación, trátelo como si fuera un recurso individual:

• Inclúyalo en la sección Recursos de su plantilla.

• Especifique las propiedades necesarias para el módulo.

Al iniciar una operación de pila, CloudFormation genera una plantilla procesada que resuelve los módulos incluidos en los recursos apropiados. Utilice conjuntos de cambios para previsualizar los recursos que se agregarán o actualizarán antes de ejecutar realmente la operación de pila. Para obtener más información, consulte Actualización de pilas con conjuntos de cambios.

Considere el siguiente ejemplo: tiene una plantilla que contiene recursos y módulos. La plantilla contiene un recurso individual, ResourceA, así como un módulo, ModuleParent. Ese módulo contiene dos recursos, ResourceB y ResourceC, así como un módulo anidado, ModuleChild. ModuleChild contiene un único recurso, ResourceD. Si crea una pila a partir de esta plantilla, CloudFormation procesa la plantilla y resuelve los módulos a los recursos apropiados. La pila resultante tendrá cuatro recursos: ResourceA, ResourceB, ResourceCy ResourceD.

CloudFormation realiza un seguimiento de los recursos de una pila que se crearon a partir de módulos. Puede ver esta información en las pestañas Eventos, Recursos y Desviaciones de una pila determinada, y también se incluye en vistas previas de conjuntos de cambios.

Los módulos se distinguen de los recursos de una plantilla porque se adhieren a la siguiente convención de nomenclatura de cuatro partes, a diferencia de la típica convención de tres partes utilizada por los recursos:

organization::service::use-case::MODULE

Uso de parámetros para especificar valores de módulo

Los módulos pueden incluir parámetros de módulo. Al igual que los parámetros de plantilla, los parámetros del módulo le permiten introducir valores personalizados en su módulo desde la plantilla (o módulo) que lo contiene. A continuación, el módulo puede utilizar estos valores para establecer las propiedades de los recursos que contiene.

También puede definir parámetros de plantilla que, a su vez, establecen las propiedades del módulo, de modo que los usuarios puedan introducir valores que se pasan al módulo en el momento de la operación de pila. Para obtener más información sobre cómo definir parámetros de plantilla, consulte Parámetros.

Del mismo modo, si un módulo contiene un módulo anidado que incluye parámetros del módulo, puede:

• Especificar los valores de los parámetros del módulo anidado directamente en el módulo principal.

• Definir los parámetros correspondientes del módulo en el módulo principal que permitan que los parámetros del módulo anidado sean establecidos por la plantilla (o módulo) en la que está contenido el módulo principal.

Uso de parámetros de plantilla para especificar valores de parámetros del módulo

El siguiente ejemplo muestra cómo definir parámetros de plantilla que pasan valores a un módulo.

Aquí, la plantilla que contiene My::S3::SampleBucket::MODULE define un parámetro de plantilla BucketName, que permite al usuario especificar un nombre de bucket de S3 durante la operación de pila.

// Template containing My::S3::SampleBucket::MODULE
{
  "Parameters": {
    "BucketName": {
      "Description": "Name for your sample bucket",
      "Type": "String"
    }
  },
  "Resources": {
    "MyBucket": {
      "Type": "My::S3::SampleBucket::MODULE",
      "Properties": {
        "BucketName": {
          "Ref": "BucketName"
        }
      }
    }
  }
}

Especificación de propiedades en recursos de un módulo secundario desde el módulo principal

El ejemplo siguiente ilustra cómo especificar valores de parámetro en un módulo anidado dentro de otro módulo.

Este primer módulo, My::S3::SampleBucketPrivate::MODULE, será el módulo secundario. Define dos parámetros: BucketName y AccessControl. Los valores especificados para estos parámetros se utilizan para especificar las propiedades BucketName y AccessControl del recurso AWS::S3::Bucket que contiene el módulo. A continuación se muestra el fragmento de plantilla para My::S3::SampleBucketPrivate::MODULE.

// My::S3::SampleBucketPrivate::MODULE
{
    "AWSTemplateFormatVersion": "2010-09-09",
    "Description": "A sample S3 Bucket with Versioning and DeletionPolicy.",
    "Parameters": {
        "BucketName": {
            "Description": "Name for the bucket",
            "Type": "String"
        },
        "AccessControl": {
            "Description": "AccessControl for the bucket",
            "Type": "String"
        }
    },
    "Resources": {
        "S3Bucket": {
            "Type": "AWS::S3::Bucket",
            "Properties": {
                "BucketName": {
                    "Ref": "BucketName"
                },
                "AccessControl": {
                    "Ref": "AccessControl"
                },
                "DeletionPolicy": "Retain",
                "VersioningConfiguration": {
                    "Status": "Enabled"
                }
            }
        }
    }
}

A continuación, el módulo anterior se anida dentro de un módulo principal, My::S3::SampleBucket::MODULE. El módulo principal, My::S3::SampleBucket::MODULE, establece los parámetros del módulo secundario de las siguientes maneras:

• Establece el parámetro AccessControl de My::S3::SampleBucketPrivate::MODULE a Private.

• Para BucketName, define un parámetro de módulo, que permitirá que el nombre del bucket se especifique en la plantilla (o módulo) que contiene My::S3::SampleBucket::MODULE.

// My::S3::SampleBucket::MODULE
{
  "AWSTemplateFormatVersion": "2010-09-09",
  "Description": "A sample S3 Bucket. With Private AccessControl.",
  "Parameters": {
    "BucketName": {
      "Description": "Name for your sample bucket",
      "Type": "String"
    }
  },
  "Resources": {
    "MyBucket": {
      "Type": "My::S3::SampleBucketPrivate::MODULE",
      "Properties": {
        "BucketName": {
          "Ref": "BucketName"
        },
        "AccessControl" : "Private"
      }
    }
  }
}

Especificación de restricciones para parámetros de módulo

Los parámetros del módulo no admiten la restricción de ejecución. Para obtener más información, consulte Propiedades. Para comprobar el tipo o la restricción en un parámetro de módulo, cree un parámetro de plantilla con las restricciones deseadas y, a continuación, haga referencia a ese parámetro de plantilla en el parámetro del módulo.

Referencia de recursos en un módulo

Se puede hacer referencia a los recursos de un módulo por nombre lógico. El nombre lógico completo de un recurso contenido en un módulo se puede construir combinando:

• El nombre lógico especificado para el módulo en la plantilla (o módulo que lo contiene).

• El nombre lógico del recurso, especificado en el módulo.

El nombre lógico completo del recurso se puede especificar o no con un punto como delimitador. Por ejemplo, los dos nombres lógicos siguientes son válidos y funcionalmente equivalentes:

• ModuleLogicalName.ResourceLogicalName

• ModuleLogicalNameResourceLogicalName

De esta manera, puede usar las funciones intrínsecas GetAtt y Ref para acceder a los valores de propiedad en los recursos del módulo.

En el ejemplo siguiente, la plantilla hace referencia a una propiedad de un módulo para establecer una propiedad correspondiente en un recurso de la propia plantilla.

Supongamos que el módulo My::S3::SampleBucket::MODULE contiene un recurso AWS::S3::Bucket con el nombre lógico de S3Bucket. Para hacer referencia al nombre del bucket de este recurso mediante la función intrínseca Ref, combine el nombre lógico dado al módulo en la plantilla, MyBucket, con el nombre lógico del recurso en el módulo, S3Bucket, a fin de obtener el nombre lógico completo del recurso: MyBucket.S3Bucket o MyBucketS3Bucket.

Los nombres lógicos de los recursos contenidos en un módulo se especifican en el esquema del módulo. Puede acceder a ese esquema de las siguientes maneras:

• Encontrar el módulo en el registro de CloudFormation. La pestaña Esquema muestra el esquema del módulo.

• Uso de la operación DescribeType para devolver los detalles del módulo, que incluye el esquema.

// Template that uses My::S3::SampleBucket::MODULE
{
  "Parameters": {
    "BucketName": {
      "Description": "Name for your sample bucket",
      "Type": "String"
   }
 },
  "Resources": {
    "MyBucket": {
      "Type": "My::S3::SampleBucket::MODULE",
      "Properties": {
          "BucketName": {
            "Ref": "BucketName"
         }
      }
    },
    "exampleQueue": {
      "Type": "AWS::SQS::Queue",
      "Properties": {
          "QueueName": {
            "Ref": "MyBucket.S3Bucket"
          }
      }
    }
},
"Outputs": {
  "BucketArn": {
      "Value": {
          "Fn::GetAtt": [
             "MyBucket",
             "S3Bucket.Arn"
          ]
      }
    }
  }
}

Parameters:
  BucketName:
    Description: Name for your sample bucket
    Type: String
Resources:
  MyBucket:
    Type: My::S3::SampleBucket::MODULE
    Properties:
      BucketName: !Ref BucketName
  exampleQueue:
    Type: AWS::SQS::Queue
    Properties:
      QueueName: !Ref MyBucket.S3Bucket
Outputs:
  BucketArn:
    Value: !GetAtt MyBucket.S3Bucket.Arn

Consideraciones sobre el uso de módulos

• El uso de los módulos no conlleva ningún coste adicional. Usted paga sólo por los recursos a los que esos módulos resuelven en sus pilas.

• Las cuotas de CloudFormation, como el número máximo de recursos permitidos en una pila o el tamaño máximo del cuerpo de la plantilla, se aplican a la plantilla procesada independientemente de si los recursos incluidos en esa plantilla provienen de módulos o no. Para obtener más información, consulte Cuotas de AWS CloudFormation.

• Las etiquetas que especifique en el nivel de pila se asignan a los recursos individuales derivados del módulo.

• Los scripts auxiliares especificados en el nivel de módulo no se propagan a los recursos individuales contenidos en el módulo cuando CloudFormation procesa la plantilla.

• Las salidas especificadas en el módulo se propagan a las salidas a nivel de plantilla.

  A cada salida se le asignará un ID lógico, que es una concatenación del nombre lógico del módulo y el nombre de salida tal como se define en el módulo. Para obtener más información sobre salidas, consulte Salidas.

• Los parámetros especificados en el módulo no se propagan a parámetros a nivel de plantilla.

  Sin embargo, puede crear parámetros de nivel de plantilla que hagan referencia a parámetros de nivel de módulo. Para obtener más información, consulte Uso de parámetros para especificar valores de módulo.

Registro y control de versiones de módulos

Usted registra y gestiona los módulos de su cuenta y región mediante el registro de CloudFormation. Para obtener más información, consulte Uso del registro de AWS CloudFormation.

Puede registrar varias versiones del mismo módulo en una cuenta y región determinadas. Tenga en cuenta las siguientes consideraciones:

• Un módulo debe estar registrado en la cuenta y región en la que desea usarlo.

• Durante las operaciones de pila, CloudFormation utiliza cualquier versión del módulo que esté actualmente registrada como la versión predeterminada en la cuenta y región en la que se está realizando la operación de pila. Esto incluye módulos anidados en otros módulos.

  Por lo tanto, tenga en cuenta que si tiene diferentes versiones del mismo módulo registradas como la versión predeterminada en diferentes cuentas o regiones, el uso de la misma plantilla puede dar lugar a resultados diferentes.

  Para obtener más información, consulte Especificación de una versión de una extensión privada que se va a utilizar mediante la AWS CLI.

• Durante las operaciones de pila, CloudFormation utiliza cualquier versión del recurso que esté actualmente registrada como la versión predeterminada en la cuenta y región en la que se está realizando la operación de pila. Esto incluye los recursos generados mediante la inclusión de módulos.

• El cambio de la versión predeterminada de un módulo no inicia ninguna operación de actualización de pila. Sin embargo, la próxima vez que realice una operación de pila con cualquier plantilla que contenga ese módulo, como una actualización de pila, CloudFormation utilizará la nueva versión predeterminada en la operación.

  La única excepción a esto es realizar una actualización de pila con la opción usar plantilla anterior especificada, como se describe a continuación.

• Para las operaciones de actualización de pila, si especifica la opción usar plantilla anterior, CloudFormation utiliza la plantilla procesada anterior para la actualización de la pila y no vuelve a procesar el módulo para los cambios que pueda haber realizado en él.

• Para garantizar resultados uniformes, si incluye módulos en una plantilla de pila para su uso con conjuntos de pilas, debe asegurarse de que la misma versión del módulo esté establecida como la versión predeterminada en todas las cuentas y regiones en las que planea implementar las instancias de pila. Esto incluye los módulos que están anidados en otros módulos. Para obtener más información sobre conjuntos de pilas, consulte Trabajo con AWS CloudFormation StackSets.

Para obtener más información sobre cómo registrar nuevas versiones de un módulo o cambiar la versión predeterminada de un módulo, consulte Uso del registro de AWS CloudFormation.

Activación de módulos públicos para usarlos en su cuenta

Para activar correctamente un módulo público en su cuenta y región, debe cumplirse lo siguiente para cada extensión pública de terceros (recurso o módulo) incluida en el módulo:

• La extensión ya debe estar activada en su cuenta y región.

  Si la extensión del módulo usa un alias de nombre de tipo, la extensión debe estar registrada en su cuenta y región con el mismo alias de nombre de tipo. Para obtener más información, consulte Especificación de alias para hacer referencia a extensiones.

• La versión de la extensión actualmente activada debe ser una de las versiones principales admitidas de esa extensión especificadas en el módulo. Para obtener más información, consulte Module requirements for publishing a public module (Requisitos del módulo para publicar un módulo público) en la Guía del usuario de la CLI de CloudFormation.

Si no tiene activadas las extensiones públicas de terceros y las versiones de extensión correctas, se producirá un error en la operación de CloudFormation que enumera las extensiones o versiones que deben activarse antes de que el módulo se pueda activar correctamente.