All Products
Search

This Product

    Resource Orchestration Service:Develop a module

    Document Center

    Resource Orchestration Service:Develop a module

    Last Updated:Dec 21, 2023

    Similar to a template, a module is a JSON or YAML text file that is encoded in UTF-8. This topic describes the basic concepts related to modules, including the naming convention, limits, and structure.

    Naming convention

    Modules adhere to the following four-part naming convention: MODULE::Organization::Service::Usecase.

    • MODULE: This is a fixed value.

    • Organization: the name of your organization.

      • The name must be at least two characters in length and can contain letters and digits.

      • The name cannot contain the following lowercase strings: alicloud, alibaba, or aliyun.

      • The name cannot start with the following lowercase string: acs.

      • The name cannot be set to one of the following lowercase strings: ros, dev, test, or debug.

    • Service: the name of the service.

      The name must be at least two characters in length and can contain letters and digits.

    • Usecase: the name of the resource.

      The name must be at least two characters in length and can contain letters and digits.

    Note

    If you set Organization to SHARE when you create a module, you must set Service to the ID of the current Alibaba Cloud account. For example, you can specify MODULE::SHARE::123456789::Usecase in this scenario.

    A custom module for which Organization is set to SHARE is named a shared module. Other users can view and use your shared module, but cannot modify or delete it.

    Limits

    • You cannot specify Transform and Workspace in a module.

    • You can specify only empty Rules in a module.

    • You can nest custom modules up to three levels of depth. If you use a public module together with custom modules, the custom modules remain three levels of depth.

      The following figure shows only public modules that are nested four levels of depth. ModuleA resides in Level 1, ModuleB resides in Level 2, ModuleC resides in Level 3, and ModuleD resides in Level 4.

      image.png

    Module structure

    ROSTemplateFormatVersion: '2015-09-01'
Description: The description of the module. The Description section provides information such as the scenarios, architecture, and method to use the module. 
Metadata: 
# The metadata of the module. The Metadata section provides information such as layouts for visualizations. 
Parameters: 
# The parameters of the module. When you use a module, you can specify parameter values from the template or module that contains the module. 
Mappings: 
# The mappings of the module, which are in a nested structure. 
Conditions: 
# The conditions of the module, which specify whether the system can create resources. 
Resources: 
# The details of resources or child modules that are contained in the module. The details include properties and associations. 
Outputs: 
# The outputs of the module. The outputs can be used by the template or module that contains the module.

    (Required) ROSTemplateFormatVersion

    The module section conforms to the requirements that are the same as those on the template section. For more information, see (Required) ROSTemplateFormatVersion.

    (Optional) Description

    The module section conforms to the requirements that are the same as those on the template section. For more information, see (Optional) Description.

    We recommend that you specify Description. You can specify multiple languages in Description. The description can help users use a module in a proper way. The Module Content tab on the module details page displays the description. The following example provides an example on how to specify multiple languages in Description:

    Description:
  en: |-
    This is a demo.

    (Optional) Metadata

    The module section conforms to the requirements that are the same as those on the template section. For more information, see (Optional) Metadata.

    When ROS performs a stack operation and processes and generates a template, the Metadata section in the module is ignored.

    To ensure proper use of a module, we recommend that you add Metadata to the module. The Metadata section of a module is fully copied to the sample template displayed on the Sample Template tab of the module details page. This optimizes the display effect of the template.

    (Optional) Parameters

    The module section conforms to the requirements that are the same as those on the template section. For more information, see (Optional) Parameters.

    Module parameters do not support constraint enforcement, including the Type, AllowedValues, AllowedPattern, MaxLength, MinLength, MaxValue, and MinValue parameters.

    If a module parameter is left empty and has a default value specified by Default, the default value is used when ROS performs a stack operation and processes and generates a template.

    Limit: The parameter name cannot contain periods (.) or colons (:).

    Recommended configurations:

    • To ensure proper use of a module, you can configure module parameter properties that are as comprehensive as template parameter properties.

      • The Properties tab on the module details page displays all properties in a one-to-one correspondence with the module parameters. The data in the Type, Required, Description, and Constraint columns of each property is generated based on the parameter properties configured in the module content.

      • The Sample Template tab on the module details page displays a sample template of the module. In the template, the Parameters section is generated based on the parameter properties configured in the module content. This ensures the validity of parameter settings and optimizes the display effect of the template.

    • You can configure properties that support multilingual configurations for module parameters, such as the Description and Label properties.

    (Optional) Mappings

    The module section conforms to the requirements that are the same as those on the template section. For more information, see (Optional) Mappings.

    Limit: The fully-qualified names of mappings cannot be duplicated. For more information about fully-qualified names, see Reference conditions in a module.

    (Optional) Conditions

    The module section conforms to the requirements that are the same as those on the template section. For more information, see (Optional) Conditions.

    Limits:

    • The condition name cannot contain ampersands (&).

    • The fully-qualified names of conditions cannot be duplicated. For more information about fully-qualified names, see Reference conditions in a module.

    (Optional) Resources

    The module section conforms to the requirements that are the same as those on the template section. For more information, see (Optional) Resources.

    You can set DependsOn of a resource to an asterisk (*). In this case, when ROS performs a stack operation and processes and generates a template, the resource depends on all resources for which DependsOn is not set to an asterisk (*).

    Limits:

    • The logical name of a resource cannot contain periods (.).

    • You cannot use the ALIYUN::ROS::Stack, ALIYUN::ROS::StackGroup, and ALIYUN::ROS::StackInstances resource types in the Resources section.

    • You cannot use the Fn::GetStackOutput function in the Resources section.

    • You cannot specify Metadata and Count for child modules.

    • You must specify Version for child modules.

    • The fully-qualified logical names of resources or modules cannot be duplicated. For more information about fully-qualified logical names, see Reference resources in a module.

    • You can use only public modules or other shared modules in a shared module.

    (Optional) Outputs

    The module section conforms to the requirements that are the same as those on the template section. For more information, see (Optional) Outputs.

    Limits:

    • The output name cannot contain periods (.).

    • You cannot use the Fn::GetStackOutput function in the Outputs section.

    Recommended configuration: You can specify Description for each output.

    • The Return Values tab on the module details page displays all return values in a one-to-one correspondence with the outputs configured in the module content. The data in the Description column of return values is generated based on Description specified for the outputs in the module content.

    • The Sample Template tab on the module details page displays a sample template of the module. In the template, the Outputs section is generated based on the outputs configured in the module content. This optimizes the display effect of the template.