How to get started with modules - Resource Orchestration Service

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 and v10.
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 the MODULE::My::VPC::SampleVpcPrivate child module is set to 192.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 the MODULE::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.

Note

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 and Workspace sections to the template.
- You cannot add the Metadata and Count 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 and Rules 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.
Note
If 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.