You can use a module in another module or a template. This topic describes how to use a module and the considerations for using a module.
Prerequisites
If you want to use a custom module, make sure that the module is registered in the desired account. For more information, see Create a custom module and View a custom module.
You can directly use out-of-the-box public modules that are provided by Resource Orchestration Service (ROS). For more information, see View a public module.
Specify configurations for a module
To use a module, you must consider the module as a resource and perform the following operations:
Include the module in the
Resources
section of your template or module.Specify a version for the module.
Specify the required configurations for the module.
Specify a version for a module
Specify a version for a module by using Version
. Valid values of Version
:
Custom value: the custom version of the module in the
v+Number
format. Examples:v1
andv10
.When you use a public module, we recommend that you specify a custom value for Version.
default
: the default version of the module.If you do not delete the module, the default version remains available.
You can specify the default version for a custom module by calling a ROS API operation or by using the ROS console. For more information, see SetResourceType and Change the default version of a module.
When you use a custom module, we recommend that you set Version to default.
latest
: the latest version of the module.If you do not delete the module, the latest version remains available.
When you create a new version for a module or delete the latest version from a module, the latest version of the module changes.
When you develop or debug a module, we recommend that you set Version to latest.
Specify a property for a module
Module parameters can help you pass custom values to a module from the template or module that contains it. Then, the module can use the values to configure properties for its resources or child modules. If a module parameter is not specified and has a default value specified by Default
, the default value is used.
Specify a module property by using a template parameter
You can specify custom values for template parameters and use the template parameters to configure properties for a module. This way, the custom values are passed to the module. For more information about how to define template parameters, see Parameters.
You can pass a custom value from a template parameter to a module property. In this example, a template that contains the MODULE::My::VPC::SampleVpc
resource and the VpcName
template parameter is used. The VpcName template parameter is used to specify the VpcName property in the module.
ROSTemplateFormatVersion: '2015-09-01'
Parameters:
VpcName:
Description: Name for your sample vpc
Type: String
Resources:
MyVpc:
Type: MODULE::My::VPC::SampleVpc
Version: default
Properties:
VpcName:
Ref: VpcName
Specify properties of a child module from the parent module
If a parent module and its child module contain the same parameter, you can specify the parameter value for the child module from the parent module.
In this example, MODULE::My::VPC::SampleVpcPrivate
is used as a child module. In the module, the VpcName
and CidrBlock
parameters are specified to configure the VpcName
and CidrBlock
properties of the ALIYUN::ECS::VPC
resource. The following sample code provides an example of the child module:
ROSTemplateFormatVersion: '2015-09-01'
Description: A sample vpc.
Parameters:
VpcName:
Description: Name for the vpc
Type: String
CidrBlock:
Description: Cidr block for the vpc
Type: String
Resources:
Vpc:
Type: ALIYUN::ECS::VPC
Properties:
VpcName:
Ref: VpcName
CidrBlock:
Ref: CidrBlock
The MODULE::My::VPC::SampleVpcPrivate
module is nested in the MODULE::My::VPC::SampleVpc
module. In the MODULE::My::VPC::SampleVpc
parent module, the following configurations are added to specify the parameters of the child module. The sample code below the configurations provides an example of the parent module.
The
CidrBlock
parameter of theMODULE::My::VPC::SampleVpcPrivate
child module is set to192.168.0.0/16
.For the
VpcName
parameter, a module parameter is defined. This way, you can specify the VPC name in a template or module that contains theMODULE::My::VPC::SampleVpc
module.
ROSTemplateFormatVersion: '2015-09-01'
Description: A sample vpc.
Parameters:
VpcName:
Description: Name for the vpc
Type: String
Resources:
MyVpc:
Type: MODULE::My::VPC::SampleVpcPrivate
Version: default
Properties:
VpcName:
Ref: VpcName
CidrBlock: 192.168.0.0/16
Specify constraints for a module parameter
Module parameters do not support constraint enforcement. To check constraints for a module parameter, you must create a template parameter that is configured with the constraints, and reference the template parameter in your module parameter.
Specify a condition for a module
Module conditions are specified in the same manner as resource conditions. The conditions of a module are passed to all resources and child modules in the module. For more information about how to define conditions, see Conditions.
Specify a dependency for a module
Module dependencies are specified in the same manner as resource dependencies. The dependencies of a module are passed to all resources and child modules in the module. For more information about how to define dependencies, see DependsOn.
Specify a deletion policy for a module
The deletion policy for modules is specified in the same manner as the deletion policy for resources. The deletion policy for a module is passed to all resources and child modules that are contained in the module and not configured with deletion policies. For more information about how to define deletion policies, see DeletionPolicy.
Reference configurations of a module
Reference resources in a module
You can use fully-qualified logical names to reference resources that are contained in a module. The fully-qualified logical name of a resource in a module is combined with the following elements:
Element 1: the logical name specified for the module in the template or module that contains the module.
Element 2: the logical name specified for the resource in the module.
You can separate the elements in a fully-qualified logical name with periods (.). Examples: ModuleLogicalName.ResourceLogicalName
and ParentModuleLogicalName.ChildModuleLogicalName.ResourceLogicalName
.
This way, you can use the Fn::GetAtt
, Ref
, and Fn::Sub
built-in functions to access the resources in the Resources section of a module or the property values of a module resource. For more information, see Resources.
// Fn::GetAtt example
GetAtt Example1:
Fn::GetAtt:
- ModuleLogicalName.ResourceLogicalName
- AttributeName
GetAtt Example2:
Fn::GetAtt:
- ModuleLogicalName.ChildModuleLogicalName.ResourceLogicalName
- AttributeName
// Ref example
Ref Example1:
Ref: ModuleLogicalName.ResourceLogicalName
Ref Example2:
Ref: ModuleLogicalName.ChildModuleLogicalName.ResourceLogicalName
// Fn::Sub example
Sub Example1:
Fn::Sub: "${ModuleLogicalName.ResourceLogicalName}"
Sub Example2:
Fn::Sub: "${ModuleLogicalName.ResourceLogicalName.AttributeName}"
Sub Example3:
Fn::Sub: "${ModuleLogicalName.ChildModuleLogicalName.ResourceLogicalName}"
Sub Example4:
Fn::Sub: "${ModuleLogicalName.ChildModuleLogicalName.ResourceLogicalName.AttributeName}"
In this example, the following configurations are added:
A template references a property of a module resource as the property of a resource in the template itself.
A template references an output of a module resource as an output in the template itself.
The ALIYUN::ECS::VPC
resource whose logical name is Vpc
is contained in the MODULE::My::VPC::SampleVpc
module. To use the Ref
built-in function to reference the resource ID and use the Fn::GetAtt
built-in function to reference the resource output, you must combine the logical name of the module in the template with the logical name of the resource in the module to obtain the fully-qualified logical name of the resource. In this example, MyVpc
is combined with Vpc
to obtain MyVpc.Vpc
.
To obtain the logical name of a resource in a module, you can view the module in the ROS console. For more information, see View a custom module and View a public module.
Parameters:
VpcName:
Description: Name for your sample vpc
Type: String
Resources:
MyVpc:
Type: MODULE::My::VPC::SampleVpc
Version: default
Properties:
VpcName:
Ref: VpcName
MyVsw:
Type: ALIYUN::ECS::VSwitch
Properties:
VpcId:
Ref: MyVpc.Vpc
CidrBlock: 192.168.1.0/24
ZoneId:
Fn::Select:
- '0'
- Fn::GetAZs:
Ref: ALIYUN::Region
VSwitchName: sample_vsw
Outputs:
VpcId:
Value:
Fn::GetAtt:
- MyVpc.Vpc
- VpcId
Reference outputs in a module
You can consider a module as a resource and module outputs as resource properties, and use the Fn::GetAtt
and Fn::Sub
built-in functions to access the outputs contained in the module. For more information, see Outputs.
// Fn::GetAtt example
GetAtt Example1:
Fn::GetAtt:
- ModuleLogicalName
- OutputName
GetAtt Example2:
Fn::GetAtt:
- ModuleLogicalName.ChildModuleLogicalName
- OutputName
// Fn::Sub example
Sub Example1:
Fn::Sub: "${ModuleLogicalName.OutputName}"
Sub Example2:
Fn::Sub: "${ModuleLogicalName.ChildModuleLogicalName.OutputName}"
Reference conditions in a module
You can consider a module as a namespace to obtain the fully-qualified name of the module, and use the Fn::If
, Fn::Or
, Fn::And
, and Fn::Not
built-in functions to access the conditions contained in the module. For more information, see Conditions.
// Fn::If example
If Example1:
Fn::If:
- ModuleLogicalName.ConditionName
- Value for true
- Value for false
If Example2:
Fn::If:
- ModuleLogicalName.ChildModuleLogicalName.ConditionName
- Value for true
- Value for false
// Fn::Or example
Or Example:
Fn::Or:
- ModuleLogicalName.ConditionName
- ModuleLogicalName.ChildModuleLogicalName.ConditionName
// Fn::And example
And Example:
Fn::And:
- ModuleLogicalName.ConditionName
- ModuleLogicalName.ChildModuleLogicalName.ConditionName
// Fn::Not example
Not Example1:
Fn::Not: ModuleLogicalName.ConditionName
Not Example2:
Fn::Not: ModuleLogicalName.ChildModuleLogicalName.ConditionName
Reference mappings in a module
You can consider a module as a namespace to obtain the fully-qualified name of the module, and use the Fn::FindInMap
built-in function to access the mappings contained in the module. For more information, see Mappings.
// Fn::FindInMap example
FindInMap Example1:
Fn::FindInMap:
- ModuleLogicalName.MappingName
- Key
- SubKey
FindInMap Example2:
Fn::FindInMap:
- ModuleLogicalName.ChildModuleLogicalName.MappingName
- Key
- SubKey
Depend on resources in a module
To depend on resources that are contained in a module, you must use the fully-qualified logical names of the resources.
Resource1:
DependsOn: ModuleLogicalName.ResourceLogicalName
Resource2:
DependsOn: ModuleLogicalName.ChildModuleLogicalName.ResourceLogicalName
Depend on a module
If a resource depends on a module or a module depends on another module, all resources in the dependent module and the child modules of the dependent module work as dependencies of the resource or module. To depend on a module, you must use the fully-qualified logical name of the module.
Resource1:
DependsOn: ModuleLogicalName
Resource2:
DependsOn: ModuleLogicalName.ChildModuleLogicalName
Considerations
The following section describes the considerations for using modules:
Modules are free of charge. You are charged only for the resources that are resolved from the module to the stack.
If a template contains a module, the following limits are imposed on the template:
The name of a parameter cannot contain the combination of a period and a colon (
.:
).The logical name of a resource cannot contain periods (
.
).The name of an output cannot contain periods (
.
).The name of a condition cannot contain ampersands (
&
).You cannot add the
Transform
andWorkspace
sections to the template.You cannot add the
Metadata
andCount
sections to the module.The fully-qualified logical names of resources and modules, and the fully-qualified names of conditions and mappings must be unique.
ROS quotas, such as the maximum number of resources allowed in a stack and maximum size of a template file, apply to the processed template regardless of whether the resources in the template are created from modules. For more information, see Limits.
The tags and the resource groups that you configure for a stack are propagated to each stack resource created from the module.
When the template is processed, the data in the
Metadata
andRules
sections of the module is ignored.When the module is processed, dynamic references are not resolved. Dynamic references are resolved when a single resource is created or updated during a stack operation. For more information about dynamic references, see Step 2: Create a ROS template.
Outputs in the module are not propagated to outputs in the template. You can create a template output and reference it in the module output. For more information, see Reference outputs of a module.
Parameters in the module are not propagated to parameters in the template. You can create a template parameter and reference it in the module parameter. For more information, see Specify a module property by using a template parameter.
If you change the default version of the module for which Version is set to
default
, no stack update operation is initiated.However, the next time you use a template that contains the module to perform a stack operation, such as a stack update, ROS uses the new default version during the operation.
If you create a new version for the module or delete the latest version from the module for which Version is set to
latest
, no stack update operation is initiated.However, the next time you use a template that contains the module to perform a stack operation, such as a stack update, ROS uses the new latest version during the operation.
During stack operations, ROS uses modules that are registered in the current account, including modules that are nested in other modules.
If you use a module that has multiple versions deployed across accounts, different results are returned to the accounts even if you use the same template.
To ensure consistency, if you want to include a module in a stack template to use the module for a stack group, you must use the same module across all accounts within which you want to deploy stack instances. This includes modules that are nested in other modules. For more information, see Stack groups.
NoteIf you want to expand modules in the account to which the stack group belongs, you must select Whether to Expand Modules in Current Account in the ROS console when you create or update the stack group.