文档

模块开发

更新时间:

模块与模板基本相同,是一个JSON或YAML格式的文本文件,使用UTF-8编码。本文主要为您介绍模块的内容,包括模块名称、模块限制和模块结构。

模块名称

模块使用四段式命名约定:MODULE::Organization::Service::Usecase

  • MODULE:固定值。

  • Organization:组织名称。

    • 由大小写字母和数字组成,长度不小于2。

    • 小写形式不能包含alicloudalibabaaliyun

    • 小写形式不能以acs开头。

    • 小写形式不能等于rosdevtestdebug

  • Service:产品名称。

    由大小写字母和数字组成,长度不小于2。

  • Usecase:资源名称。

    由大小写字母和数字组成,长度不小于2。

说明

创建模块时,如果OrganizationSHARE,则Service必须为当前账号的主账号ID,例如MODULE::SHARE::123456789::Usecase

这种特殊的自定义模块也称为共享模块。其他用户可以查看和使用您的共享模块,但无法修改和删除它。

模块限制

  • 不能为模块指定TransformWorkspace

  • 不能为模块指定非空Rules

  • 自定义模块最大嵌套深度为3,使用公共模块不会增加嵌套深度。

    下图为公共模块嵌套深度示例,ModuleA深度为1,ModuleB深度为2,ModuleC深度为3,ModuleD深度为4。

    image.png

模块结构

ROSTemplateFormatVersion: '2015-09-01'
Description: 模块描述信息,可用于说明模块的适用场景、架构说明、使用方法等。
Metadata: 
# 模块的元数据信息,例如存放用于可视化的布局信息。
Parameters: 
# 模块参数,使用模块时,可以在模板或父模块中指定取值。
Mappings: 
# 映射,一种多层的映射结构。
Conditions: 
# 条件,主要用于控制资源是否创建。
Resources: 
# 模块所包含的资源或子模块,包括属性、依赖关系等。
Outputs: 
# 模块输出,可以被模板或父模块使用。

ROSTemplateFormatVersion(必选)

与模板要求一致,更多信息,请参见ROSTemplateFormatVersion(必选)

Description(可选)

与模板要求一致,更多信息,请参见Description(可选)

建议您添加此字段,并支持多语言。有助于模块使用者正确使用模块。模块描述会在模块详情页面的模块内容页签中展示。多语言示例如下:

Description:
  zh-cn: |-
    这是一个示例。
  en: |-
    This is a demo.

Metadata(可选)

与模板要求一致,更多信息,请参见Metadata(可选)

当执行资源栈操作并处理生成模板时,模块中的Metadata会被忽略。

建议您添加此字段,有助于模块使用者正确使用模块。Metadata会完整复制到模块详情页面的模板示例中,可以优化示例模板界面展示效果。

Parameters(可选)

与模板要求一致,更多信息,请参见Parameters(可选)

模块参数不支持约束强制执行。包括TypeAllowedValuesAllowedPatternMaxLengthMinLengthMaxValueMinValue

当执行资源栈操作并处理生成模板时,如果模块参数未指定,且该参数有默认值(Default),则会使用默认值。

使用限制:参数名称中不能包含字符:.:

建议如下:

  • 建议与编写模板一样全面设置参数属性,有助于模块使用者正确使用模块。

    • 模块详情页面的属性页签中展示的所有属性与模块参数一一对应。每个属性的类型是否必填描述约束均来自于参数属性。

    • 模块详情页面模板示例中的Parameters部分会基于参数属性生成,一方面可以保证参数设置的正确性,另一方面可以展示模板优化界面效果。

  • 建议支持多语言,包括DescriptionLabel等。

Mappings(可选)

与模板要求一致,更多信息,请参见Mappings(可选)

使用限制:映射完全限定名称不能重复。关于完全限定名称,请参见引用模块中的条件

Conditions(可选)

与模板要求一致,更多信息,请参见Conditions(可选)

使用限制:

  • 条件名称中不能包含字符:&

  • 条件完全限定名称不能重复。关于完全限定名称,请参见引用模块中的条件

Resources(可选)

与模板要求一致,更多信息,请参见Resources(可选)

您可以设置资源的DependsOn*,当执行资源栈操作并处理生成模板时,该资源会依赖于所有DependsOn不为*的资源。

使用限制:

  • 资源逻辑名称中不能包含字符:.

  • 不能使用资源类型ALIYUN::ROS::StackALIYUN::ROS::StackGroupALIYUN::ROS::StackInstances

  • 不能使用Fn::GetStackOutput函数。

  • 不能为子模块指定MetadataCount

  • 必须为子模块指定Version

  • 资源或模块完全限定逻辑名称不能重复。关于完全限定逻辑名称,请参见引用模块中的资源

  • 共享模块只能使用公共模块或其他共享模块。

Outputs(可选)

与模板要求一致,更多信息,请参见Outputs(可选)

使用限制:

  • 输出名称中不能包含字符:.

  • 不能使用Fn::GetStackOutput函数。

建议为每个输出指定Description

  • 模块详情页面的返回值页签中展示的所有返回值与模块输出一一对应,返回值的描述来自于输出的Description

  • 模块详情页面的模板示例中的Outputs部分会基于输出生成,可以优化示例模板界面展示效果。