💾 Archived View for cfdocs.wetterberg.nu › modules.gemini captured on 2024-05-12 at 15:29:40. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2021-12-03)
-=-=-=-=-=-=-
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:
A module can contain:
For information on developing module types, see Developing module types in the *CloudFormation Command Line Interface User Guide*.
To use a module, make sure it is registered in the account and region in which you want to use it. You register modules in the CloudFormation registry as private extensions. Then, treat it much as you would an individual resource:
When you initiate a stack operation, CloudFormation generates a processed template that resolves any included modules into the appropriate resources. Use change sets to preview the resources to be added or updated prior to actually executing the stack operation.
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*.
{P Image}
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 is 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::usecase::MODULE`
Modules can include module parameters. Much like template parameters, module parameters enable you to input custom values to your module from the template (or module) that contains it. The module can then use these values to set properties of the resources it contains.
You can also define template parameters that in turn set module properties, so that users can input values that get passed to the module at the time of the stack operation. For more information about defining template parameters, see Parameters.
Likewise, if a module contains a nested module that includes module parameters, you can:
The following example shows how to define template parameters that pass values to a module.
Here, the 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"
}
}
}
}
}
The following example illustrates how to specify parameter values in a module that is 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:
// 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"
}
}
}
}
Module parameters do not support Type or Constraint enforcement. To perform type or constraint checking on a module parameter, create a template parameter with the desired constraints, then reference that template parameter in your module parameter.
Resources in a module can be referenced by logical name. The fully-qualified logical name of a resource contained in a module can be constructed by combining:
In this way, you can use `GetAtt` and `Ref` intrinsic functions to access property values on module resources.
In the following example, the template references a property in a module to set a corresponding property on a resource in the template itself.
Suppose that the `My::S3::SampleBucket::MODULE` module contains an `AWS::S3::Bucket` resource with the logical name of `S3Bucket`. To reference the bucket name of this resource using the `Ref` intrinsic function, combine the logical name given the module in the template, `MyBucket`, with the logical name of the resource in the module, `S3Bucket`, to get the fully qualified logical name of the resource: `MyBucketS3Bucket`.
The logical names of resources contained in a module are specified in the module's schema. You can access that schema in the following ways:
// 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"
}
}
},
"someQueueToMakeItExciting" : {
"Type" : "AWS::SQS::Queue",
"Properties": {
"QueueName":
{ "Fn::GetAtt" : [ "MyBucketS3Bucket", "BucketName" ] }
}
}
}
}
Using parameters to specify module values
You register and manage the modules in your account and region using the CloudFormation registry. For more information, see Using the AWS CloudFormation registry.
Using the AWS CloudFormation registry
You can register multiple versions of the same module in a given account and region. Keep in mind the following considerations:
Specifying which version of an extension to use
For more information on registering new versions of a module, or changing the default version of a module, see Using the AWS CloudFormation registry.