# Create reusable resource configurations that can be included across templates with CloudFormation modules
*Modules* are a way for you to package resource configurations for inclusion across stack templates, in a transparent, manageable, and repeatable way. Modules can encapsulate common service configurations and best practices as modular, customizable building blocks for you to include in your stack templates. Modules enable you to include resource configurations that incorporate best practices, expert domain knowledge, and accepted guidelines (for areas such as security, compliance, governance, and industry regulations) in your templates, without having to acquire deep knowledge of the intricacies of the resource implementation.
For example, a domain expert in networking could create a module that contains built-in security groups and ingress/egress rules that adhere to security guidelines. You could then include that module in your template to provision secure networking infrastructure in your stack—without having to spend time figuring out how VPCs, subnets, security groups, and gateways work. And because modules are versioned, if security guidelines change over time, the module author can create a new version of the module that incorporates those changes.
Characteristics of using modules in your templates include:
+ **Predictability** – A module must adhere to the schema it registers in the CloudFormation registry, so you know what resources it can resolve to once you include it in your template.
+ **Reusability** – You can use the same module across multiple templates and accounts.
+ **Traceability** – CloudFormation retains knowledge of which resources in a stack were provisioned from a module, enabling you to easily understand the source of resource changes.
+ **Manageability** – Once you've registered a module, you can manage it through the CloudFormation registry, including versioning and account and regional availability.
A module can contain:
+ One or more resources to be provisioned from the module, along with any associated data, such as outputs or conditions.
+ Any module parameters, which enable you to specify custom values whenever the module is used.
For information about developing modules, see [Developing modules](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/modules.html) in the *CloudFormation CLI User Guide*.
**Topics**
+ [
## Considerations when using modules
](#module-considerations)
+ [
# Understand module versioning
](module-versioning.md)
+ [
# Use modules from the CloudFormation private registry
](modules-using.md)
+ [
# Use parameters to specify module values
](module-using-params.md)
+ [
# Reference module resources in CloudFormation templates
](module-ref-resources.md)
## Considerations when using modules
+ There is no additional charge for using modules. You pay only for the resources those modules resolve to in your stacks.
+ CloudFormation quotas, such as the maximum number of resources allowed in a stack, or the maximum size of the template body, apply to the processed template whether the resources included in that template come from modules or not. For more information, see [Understand CloudFormation quotas](cloudformation-limits.md).
+ Tags you specify at the stack level are assigned to the individual resources derived from the module.
+ Helper scripts specified at the module level don't propagate to the individual resources contained in the module when CloudFormation processes the template.
+ Outputs specified in the module are propagated to outputs at the template level.
Each output will be assigned a logical ID that's a concatenation of the module logical name and the output name as defined in the module. For more information, see [Get exported outputs from a deployed CloudFormation stack](using-cfn-stack-exports.md).
+ Parameters specified in the module aren't propagated to parameters at the template level.
However, you can create template-level parameters that reference module-level parameters. For more information, see [Use parameters to specify module values](module-using-params.md).
# Understand module versioning
The CloudFormation registry acts as a repository where you can register and manage modules for use within your AWS account and Region. You can register modules from various sources, including AWS, third-party publishers, and your own custom extensions, within your account and Region. For more information, see [Managing extensions with the CloudFormation registry](registry.md).
Modules can have different versions, so you can specify which version of a module you want to use. This versioning capability is particularly useful when you need to update or modify a module without breaking existing stacks that depend on it.
Keep in mind the following considerations when using multiple versions of a module:
+ During stack operations, CloudFormation uses whatever version of the module that's currently registered as the default version in the AWS account and Region in which the stack operation is being performed. This includes modules that are nested in other modules.
Therefore, be aware that if you have different versions of the same module registered as the default version in different accounts or Regions, using the same template may result in different results.
+ During stack operations, CloudFormation uses whatever version of the resource that's currently registered as the default version in the AWS account and Region in which the stack operation is being performed. This includes the resources generated by including modules.
+ Changing the default version of a module doesn't initiate any stack update operation. However, the next time you perform a stack operation with any template containing that module, such as a stack update, CloudFormation will use the new default version in the operation.
The one exception to this is performing a stack update with the **use previous template** option specified, as described below.
+ For stack update operations, if you specify the **use previous template** option, CloudFormation uses the previous processed template for the stack update, and doesn't reprocess the module for any changes you might have made to it.
+ To guarantee uniform results, if you are including modules in a stack template for use with stack sets, you should ensure that the same version of the module is set as the default version in all the accounts and Regions in which you are planning to deploy your stack instances. This includes for modules that are nested in other modules. For more information, see [Managing stacks across accounts and Regions with StackSets](what-is-cfnstacksets.md).
## Requirements for activating third-party public modules
To successfully activate a third-party public module in your account and Region, the following must be true for each third-party public extension (resource or module) included in the module:
+ **Extension activation** – The extension must be activated in the account and Region you want to use it in. For more information, see [Use third-party public extensions from the CloudFormation registry](registry-public.md).
+ **Alias registration** – If the extension in the module uses a type name alias, the extension must be registered in your account and Region using the same type name alias. For more information, see [Use aliases to refer to extensions](registry-public.md#registry-public-enable-alias).
+ **Version compatibility** – The extension version currently activated must be one of the supported major versions of that extension specified in the module.
If you do not have the correct third-party public extensions and extension versions activated, CloudFormation will fail the operation with an error listing the extensions and versions that need to be activated before the module can be successfully activated.
# Use modules from the CloudFormation private registry
This topic explains how to use modules in CloudFormation templates. Think of modules as pre-made bundles of resources that you can add to your templates.
To use a module, the steps are as follows:
+ **Register the module** – You register modules in the CloudFormation registry as private extensions. Make sure it's registered in the AWS account and Region you’re working in. For more information, see [CloudFormation registry concepts](registry-concepts.md).
+ **Include it in your template** – Add the module to the [Resources](resources-section-structure.md) section of your CloudFormation template, just like you would with other resources. You'll also need to provide any required properties for the module.
+ **Create or update the stack** – When you initiate a stack operation, CloudFormation generates a processed template that resolves any included modules into the appropriate resources.
+ **Preview changes** – Before making changes, you can use a change set to see what resources will be added or changed. For more information, see [Update CloudFormation stacks using change sets](using-cfn-updating-stacks-changesets.md).
Consider the following example: you have a template that contains both resources and modules. The template contains one individual resource, `ResourceA`, as well as a module, `ModuleParent`. That module contains two resources, `ResourceB` and `ResourceC`, as well as a nested module, `ModuleChild`. `ModuleChild` contains a single resource, `ResourceD`. If you create a stack from this template, CloudFormation processes the template and resolves the modules to the appropriate resources. The resulting stack has four resources: `ResourceA`, `ResourceB`, `ResourceC`, and `ResourceD`.
![\[During a stack operation, CloudFormation resolves the two modules included in the stack template into the appropriate four resources.\]](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/images/modules-resource-inclusion.png)
CloudFormation keeps track of which resources in a stack were created from modules. You can view this information on the **Events**, **Resources**, and **Drifts** tabs for a given stack, and it's also included in change set previews.
Modules are distinguishable from resources in a template because they adhere to the following four-part naming convention, as opposed to the typical three-part convention used by resources:
```
organization::service::use-case::MODULE
```
# Use parameters to specify module values
In CloudFormation, you can use template parameters to customize your stacks by providing input values during stack creation or update. These parameters allow you to change certain aspects of the stack based on your needs. For more information about defining template parameters, see [CloudFormation template Parameters syntax](parameters-section-structure.md).
Similarly, modules can also have parameters. These module parameters allow you to input custom values to the module from the template (or another module) that's using it. The module can then use these custom values to set property values for the resources it contains.
You can also define template parameters that set module properties, so that you can input values that get passed to the module at the time of the stack operation.
If a module contains a nested module that has its own module parameters, you can either:
+ Specify the values for the nested module's parameters directly in the parent module.
+ Define corresponding module parameters in the parent module that enable the nested module's parameters to be set by the template (or module) in which the parent module is contained.
## Using template parameters to specify module parameter values
The following example shows how to define template parameters that pass values to a module.
This template containing `My::S3::SampleBucket::MODULE` defines a template parameter, `BucketName`, that enables the user to specify an S3 bucket name during the stack operation.
```
# 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
```
## Specifying properties on resources in a child module from the parent module
The following example illustrates how to specify parameter values in a module that's nested within another module.
This first module, `My::S3::SampleBucketPrivate::MODULE`, will be the child module. It defines two parameters: `BucketName` and `AccessControl`. The values specified for these parameters are used to specify the `BucketName` and `AccessControl` properties of the `AWS::S3::Bucket` resource the module contains. Below is the template fragment for `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
```
Next, the previous module is nested within a parent module, `My::S3::SampleBucket::MODULE`. The parent module, `My::S3::SampleBucket::MODULE`, sets the child module parameters in the following ways:
+ It sets the `AccessControl` parameter of `My::S3::SampleBucketPrivate::MODULE` to `Private`.
+ For `BucketName`, it defines a module parameter, which will enable the bucket name to be specified in the template (or module) that contains `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
```
## Specifying constraints for module parameters
Module parameters don't support constraint enforcement. To perform constraint checking on a module parameter, create a template parameter with the desired constraints. Then, reference that template parameter in your module parameter. For more information about defining template parameters, see [CloudFormation template Parameters syntax](parameters-section-structure.md).
# Reference module resources in CloudFormation templates
In CloudFormation templates, you often need to set properties on one resource based on the name or property of another resource. For more information, see [Referencing resources](resources-section-structure.md#using-cross-resource-references).
To reference a resource contained within a module in your CloudFormation template, you must combine two logical names:
+ The logical name you gave to the module itself when you included it in your template.
+ The logical name of the specific resource within that module.
You can combine these two logical names with or without using a period (.) between them. For example, if the module's logical name is `MyModule` and the resource's logical name is `MyBucket`, you can refer to that resource as either `MyModule.MyBucket` or `MyModuleMyBucket`.
To find the logical names of resources inside a module, you can consult the module's schema, which is available in the CloudFormation registry or by using the [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DescribeType.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DescribeType.html) operation. The schema lists all the resources and their logical names that are part of the module.
Once you have the full logical name, you can use CloudFormation functions like `GetAtt` and `Ref` to access property values on module resources.
For example, you have a `My::S3::SampleBucket::MODULE` module that contains an `AWS::S3::Bucket` resource with the logical name `S3Bucket`. To refer to the name of this bucket using the `Ref` function, you combine the module's name in your template (`MyBucket`) with the logical name of the resource in the module (`S3Bucket`). The full logical name is either `MyBucket.S3Bucket` or `MyBucketS3Bucket`.
**Example template**
The following example template creates an S3 bucket using the `My::S3::SampleBucket::MODULE` module. It also create an Amazon SQS queue and set its name to be the same as the bucket name from the module. Additionally, the template outputs the Amazon Resource Name (ARN) of the created S3 bucket.
```
# 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: !GetAtt MyBucket.S3Bucket.Arn
```