How to get started with modules - Resource Orchestration Service

You can use a module in another module or a template. Learn how to configure module versions, properties, conditions, and dependencies.

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, treat it 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 pass custom values to a module from the containing template or module. The module uses these values to configure properties for its resources or child modules. If a module parameter is not specified, the value defined by Default is used.

Specify a module property by using a template parameter

You can specify custom values for template parameters and use them to configure properties for a module. For more information about how to define template parameters, see Parameters.

The following example uses a template that contains the MODULE::My::VPC::SampleVpc resource and the VpcName template parameter. The VpcName template parameter specifies 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. The following configurations specify the child module parameters in the parent module. The sample code that follows shows 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 enforce constraints on a module parameter, create a template parameter with the desired constraints and reference it in your module parameter.

Specify a condition for a module

Module conditions follow the same syntax 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 follow the same syntax 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

Module deletion policies follow the same syntax as resource deletion policies. A module's deletion policy is inherited by all resources and child modules that do not have their own deletion policies. For more information about how to define deletion policies, see DeletionPolicy.

Reference configurations of a module

Reference resources in a module

Use fully-qualified logical names to reference resources in a module. A fully-qualified logical name consists of 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.

You can then use the Fn::GetAtt, Ref, and Fn::Sub built-in functions to access resources in the Resources section of a module or 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

Treat a module as a resource and its outputs as resource properties. Use the Fn::GetAtt and Fn::Sub built-in functions to access module outputs. 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

Treat a module as a namespace to obtain its fully-qualified name, and use the Fn::If, Fn::Or, Fn::And, and Fn::Not built-in functions to access conditions 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

Treat a module as a namespace to obtain its fully-qualified name, and use the Fn::FindInMap built-in function to access mappings 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 in a module, use their fully-qualified logical names.

Resource1:
  DependsOn: ModuleLogicalName.ResourceLogicalName
Resource2:
  DependsOn: ModuleLogicalName.ChildModuleLogicalName.ResourceLogicalName

Depend on a module

When a resource or module depends on another module, all resources and child modules in the dependent module become dependencies. To depend on a module, use its fully-qualified logical name.

Resource1:
  DependsOn: ModuleLogicalName
Resource2:
  DependsOn: ModuleLogicalName.ChildModuleLogicalName

Considerations

Keep the following considerations in mind when you use 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.