AWS::CloudFormation::ModuleVersion - AWS CloudFormation

AWS::CloudFormation::ModuleVersion

Registers the specified version of the module with the CloudFormation service. Registering a module makes it available for use in CloudFormation templates in your AWS account and region.

To specify a module version as the default version, use the AWS::CloudFormation::ModuleDefaultVersion resource.

For more information using modules, see Using modules to encapsulate and reuse resource configurations and Registering extensions in the CloudFormation User Guide. For information on developing modules, see Developing modules in the CloudFormation CLI User Guide.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{ "Type" : "AWS::CloudFormation::ModuleVersion", "Properties" : { "ModuleName" : String, "ModulePackage" : String } }

YAML

Type: AWS::CloudFormation::ModuleVersion Properties: ModuleName: String ModulePackage: String

Properties

ModuleName

The name of the module being registered.

Required: Yes

Type: String

Minimum: 10

Maximum: 204

Pattern: [A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}(::MODULE){0,1}

Update requires: Replacement

ModulePackage

A URL to the S3 bucket containing the package that contains the template fragment and schema files for the module version to register.

Note

The user registering the module version must be able to access the module package in the S3 bucket. That is, the user needs to have GetObject permissions for the package. For more information, see Actions, Resources, and Condition Keys for Amazon S3 in the AWS Identity and Access Management User Guide.

Required: Yes

Type: String

Minimum: 1

Maximum: 4096

Update requires: Replacement

Return values

Ref

When you pass the logical ID of this resource to the intrinsic Ref function, Ref returns the Amazon Resource Name (ARN) of the module version.

For more information about using the Ref function, see Ref.

Fn::GetAtt

The Fn::GetAtt intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using the Fn::GetAtt intrinsic function, see Fn::GetAtt.

Arn

The Amazon Resource Name (ARN) of the module.

Description

The description of the module.

DocumentationUrl

The URL of a page providing detailed documentation for this module.

IsDefaultVersion

Whether the specified module version is set as the default version.

Schema

The schema that defines the module.

TimeCreated

When the specified module version was registered.

VersionId

The ID of this version of the module.

Visibility

The scope at which the module is visible and usable in CloudFormation operations.

Valid values include:

  • PRIVATE: The module is only visible and usable within the account in which it is registered.

  • PUBLIC: The module is publicly visible and usable within any Amazon account.

Remarks

Considerations when managing module versions:

  • The account in which you register the module version must have permission to access the S3 bucket in which the module package resides.

  • The first module version to be registered in an account and region remains the default version CloudFormation uses, unless and until you explicitly sets another version as the default. To specify a module version as the default version, use the AWS::CloudFormation::ModuleDefaultVersion resource.

  • If your template contains multiple versions of the same module, we strongly recommend using the DependsOn attribute to explicitly set the order in which the versions are registered.

  • If you delete an AWS::CloudFormation::ModuleVersion resource, either by deleting it from a stack or deleting the entire stack, CloudFormation marks the corresponding module version as DEPRECATED.

    If you attempt to delete an AWS::CloudFormation::ModuleVersion resource that represent the default version, the operation will fail if there are other active versions.

    For more information on deprecating module versions, see DeregisterType in the AWS CloudFormation API Reference.

  • You cannot edit a module version. Updating an AWS::CloudFormation::ModuleVersion resource results in a new module version being registered in the CloudFormation registry.

Examples

Registering a module version

The following example registers a module version. If this is the only version of the module registered in this account and region, CloudFormation sets this version as the default version.

JSON

{ "AWSTemplateFormatVersion": "2010-09-09", "Resources": { "ModuleVersion": { "Type": "AWS::CloudFormation::ModuleVersion", "Properties": { "ModuleName": "My::Sample::Test::MODULE", "ModulePackage": "s3://my-sample-moduleversion-bucket/sample-module-package-v1.zip" } } } }

YAML

AWSTemplateFormatVersion: 2010-09-09 Resources: ModuleVersion: Type: 'AWS::CloudFormation::ModuleVersion' Properties: ModuleName: 'My::Sample::Test::MODULE' ModulePackage: 's3://my-sample-moduleversion-bucket/sample-module-package-v1.zip'

Registering multiple module versions

The following example registers two versions of a module. Note the following:

  • The example uses the DependsOn attribute to ensure that CloudFormation provisions version one before version two.

  • CloudFormation sets version one of the module as the default version, as it is registered first. (This assumes no other versions of the module are currently registered in this account and Region.)

JSON

{ "AWSTemplateFormatVersion": "2010-09-09", "Resources": { "ModuleVersion1": { "Type": "AWS::CloudFormation::ModuleVersion", "Properties": { "ModuleName": "My::Sample::Test::MODULE", "ModulePackage": "s3://my-sample-moduleversion-bucket/sample-module-package-v1.zip" } }, "ModuleVersion2": { "Type": "AWS::CloudFormation::ModuleVersion", "Properties": { "ModuleName": "My::Sample::Test::MODULE", "ModulePackage": "s3://my-sample-moduleversion-bucket/sample-module-package-v2.zip" }, "DependsOn": "ModuleVersion1" } } }

YAML

AWSTemplateFormatVersion: 2010-09-09 Resources: ModuleVersion1: Type: 'AWS::CloudFormation::ModuleVersion' Properties: ModuleName: 'My::Sample::Test::MODULE' ModulePackage: 's3://my-sample-moduleversion-bucket/sample-module-package-v1.zip' ModuleVersion2: Type: 'AWS::CloudFormation::ModuleVersion' Properties: ModuleName: 'My::Sample::Test::MODULE' ModulePackage: 's3://my-sample-moduleversion-bucket/sample-module-package-v2.zip' DependsOn: ModuleVersion1