Module structure and requirements

A module consists of two main pieces:

Creating the module template fragment

The starting point for developing a module is the template fragment. The template fragment is a file that contains the information that defines the resources for CloudFormation to provision during stack operations, including:

Currently, CloudFormation supports template fragments written in JSON or YAML.

For example, the following template fragment creates an S3 bucket resource, and sets the AccessControl property to Private and the resource DeletionPolicy to Retain. In addition, the template fragment defines a module-level parameter, VersioningConfigurationParam, whose values is used to set the VersioningConfiguration status of the S3 bucket.

{
    "AWSTemplateFormatVersion": "2010-09-09",
    "Description": "A sample S3 Bucket module (AWS::SampleS3::Bucket::MODULE)",
    "Parameters": {
        "VersioningConfigurationParam": {
            "Description": "Versioning configuration",
            "Type": "String"
        }
    },
    "Resources": {
        "S3BucketName": {
            "Type": "AWS::S3::Bucket",
            "Properties": {
                "AccessControl": "Private",
                "VersioningConfiguration": {
                    "Status": {
                        "Ref": "VersioningConfigurationParam"
                    }
                }
            },
            "DeletionPolicy": "Retain"
        }
    }
}

You can author template fragments manually, or use any tool that generates CloudFormation templates. For example, you can use the AWS Cloud Development Kit (AWS CDK) to synthesize one or more AWS CDK constructs to produce a CloudFormation template, and then use that template as the basis for a module. For more information about the CDK, see the AWS Cloud Development Kit (AWS CDK).

Considerations when authoring the template fragment

Keep in mind the following considerations when developing modules:

Nesting modules

Modules can contain other modules. You can nest modules up to three levels deep. To include a module in your module, reference it in the Resources section of your template fragment, as you would any other resource. For an example, see Specifying properties on resources in a child module from the parent module in the CloudFormation User Guide.

Macros and modules

CloudFormation doesn't support inclusion of modules in macros. A module can't contain a macro.

For more information on macros, see Using macros to perform custom processing in the CloudFormation User Guide.

Defining parameters in a module

Much like template parameters, module parameters enable the user to input custom values to a 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 define a module parameter as you would a template parameter. For detailed information about parameter requirements and definition, see Parameters in the CloudFormation User Guide.

Dynamic references aren't resolved when the module is processed by CloudFormation, but when the individual resources are created or updated during stack operations.

Module parameters don't count toward the parameter maximum for template parameters. For information on template parameters and their limits, see Parameters in the CloudFormation User Guide.

Parameters specified in the module are not propagated to parameters at the template level. However, you can create template-level parameters that reference module-level parameters.

For information on how users can specify parameter values in modules, see Using parameters to specify module values in the CloudFormation User Guide.

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.

Specifying policies on resources contained in a module

If you specify the following resource policy attributes at the module level, CloudFormation applies the policy attribute to all resources contained in the module:

Policy attributes specified at a resource level override any specified at the module level.

You can't specify the following resource policy attributes at the module level:

If you use a DependsOn attribute to specify that a resource in your template depends on a module, CloudFormation will finish provisioning all resources in the module before provisioning the dependent resource.

For more information on resource policies, see Resource attribute reference in the CloudFormation User Guide.

Generating the module schema

The module schema is generated from the template fragment, and defines the contract to which the module adheres, including defining the input it accepts and the possible resources it resolves to when included in a template.

To generate the module schema, use the validate command once you've authored your template fragment.

For example, suppose you created a module package and used the template fragment above. The validate command would result in the following module schema:

{
  "typeName": "AWS::SampleS3::Bucket::MODULE",
  "properties": {
    "VersioningConfigurationParam": {
      "description": "Version Configuration",
      "type": "string"
    }
  },
  "resources": {
    "type": "object",
    "properties": {
      "S3Bucket": {
        "$ref": "aws-s3-bucket.json"
      }
    },
    "additionalProperties": false
  }
}

For more information, see Develop a module.

Model requirements for publishing a public module

If you want to make your module publicly available to all CloudFormation users, you can publish it to the CloudFormation registry. In order to publish your module, it must meet the following model requirements. Before publishing, use TestType to confirm your module meets these requirements.

For more information on publishing public extensions, see Publishing extensions to make them available for public use.

Specifying publisher metadata for public third-party resources

For any third-party public resources you include in your public module, you must specify additional publisher information. This enables CloudFormation to determine the resource type specified, and which versions of that resource the module supports. Specify the following properties in a Metadata element in your resource definition:

For example, the following module snippet adds a resource to the module. The module uses a type alias, Module::DDB::Table, for the resource type, but also includes the original type name, Mongodb::DDB::Table, so that CloudFormation can determine if the resource type is enabled in the user's account. The snippet also includes publisher ID information, in case multiple publishers have published public resource types of the same name, in addition to which major versions of the resource type that the module supports.

Resources:
  SampleDDB:
    Type: Module::DDB::Table
    Properties:
       TableName: xx
       IndexName: xxx
    Metadata:
      PublisherId: dfdxfdfwed
      RegionalPublisherId:
        us-east-1: c34ntbnrb1
        us-west-2: eer332gfdf
      OrignalTypeName:
         Mongodb::DDB::Table
      SupportMajorVersions: [1, 2, 3]
    .....