AWS::CloudFormation::ModuleVersion - Amazon CloudFormation
SyntaxPropertiesReturn valuesRemarksExamples
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

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 Amazon Web Services 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 Amazon 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

Pattern: ^[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}::MODULE

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's, the user needs to have GetObject permissions for the package. For more information, see Actions, Resources, and Condition Keys for Amazon S3 in the Amazon 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 extension.

Description

The description of the extension.

DocumentationUrl

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

IsDefaultVersion

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

This applies only to private extensions you have registered in your account, and extensions published by Amazon. For public third-party extensions, whether they are activated in your account, CloudFormation returns null.

Schema

The schema that defines the extension.

For more information about extension schemas, see Resource Provider Schema in the CloudFormation CLI User Guide.

TimeCreated

When the specified private extension version was registered or activated in your account.

VersionId

The ID of this version of the module.

Visibility

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

Valid values include:

  • PRIVATE: The extension is only visible and usable within the account in which it is registered. Amazon CloudFormation marks any extensions you register as PRIVATE.

  • PUBLIC: The extension 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 Amazon CloudFormation API Reference.

  • You can't 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's 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