全部产品
Search
文档中心

资源编排:Terraform类型模板结构

更新时间:Dec 14, 2023

Terraform类型模板是资源编排服务ROS(Resource Orchestration Service)托管Terraform后支持的模板,用于编排阿里云、AWS或Azure的资源。您可以在模板中定义资源、参数以及资源间的依赖关系。

模板结构

Terraform类型模板由10部分组成,模板结构如以下代码所示。

说明

关于Terraform类型模板组成部分的更多信息,请参见模板语法

ROSTemplateFormatVersion: '2015-09-01'
Transform: 'Aliyun::Terraform-v1.0'
Parameters:
  subnet_mask:
    Type: Number
    Description:
      en: Subnet mask of VSwitch
      zh-cn: 交换机子网掩码
    Label:
      en: Subnet mask
      zh-cn: 子网掩码
    MinValue: 13
    MaxValue: 31
    Default: 21
Outputs:
  vpc_id:
    Value: null
    Description:
      en: VPC ID
      zh-cn: 专有网络ID
Workspace:
  main.tf: |-
    variable "zone_id" {
      type        = string
      description = <<EOT
      {
        "AssociationProperty": "ALIYUN::ECS::Instance::ZoneId",
        "Description": {
          "en": "Zone of VSwitch",
          "zh-cn": "交换机所在可用区"
        },
        "Label": {
          "en": "Zone",
          "zh-cn": "可用区"
        }
      }
      EOT
    }
    variable "subnet_mask" {
      type              = number
    }
    module "my_vpc" {
      source            = "./modules/vpc"
    }
    resource "alicloud_vswitch" "vsw" {
      vpc_id            = "${module.my_vpc.vpc_id}"
      cidr_block        = "172.16.0.0/${var.subnet_mask}"
      availability_zone = var.zone_id
    }
    output "vsw_id" {
      value       = "${alicloud_vswitch.vsw.id}"
      description = <<EOT
      {
        "Description": {
          "en": "VSwitch ID",
          "zh-cn": "交换机ID"
        }
      }
      EOT
    }
  modules/vpc/main.tf: |-
    variable "vpc_name" {
      type        = string
      default     = "tf_test"
      description = "专有网络名称"
    }
    resource "alicloud_vpc" "vpc" {
      name        = var.vpc_name
      cidr_block  = "172.16.0.0/12"
    }
    output "vpc_id" {
      value       = "${alicloud_vpc.vpc.id}"
    }

ROSTemplateFormatVersion(必选)

ROS支持的模板版本号。取值:2015-09-01。

Transform(必选)

ROS支持的Terraform版本。取值:

  • Aliyun::Terraform-v0.12:Terraform 0.12版本。

  • Aliyun::Terraform-v0.15:Terraform 0.15版本。

  • Aliyun::Terraform-v1.0:Terraform 1.0版本。

  • Aliyun::Terraform-v1.1:Terraform 1.1版本。

  • Aliyun::Terraform-v1.2:Terraform 1.2版本。

  • Aliyun::Terraform-v1.3:Terraform 1.3版本。

  • Aliyun::Terraform-v1.4:Terraform 1.4版本。

  • Aliyun::Terraform-v1.5:Terraform 1.5版本。

说明

由于HashiCorp宣布从Mozilla公共许可证v2.0(MPL2.0)过渡到商业源代码许可证(BSL),目前ROS支持的Terraform最新版本为v1.5.7(MPL2.0许可下的最后一个官方版本)。

Transform使用说明如下:

  • ROS会随Terraform版本发布增加Transform参数的取值。

  • Terraform小版本变动(版本号x.y.z中的z发生变化)不影响Transform的取值。

  • 满足如下条件时,Transform参数可以通过资源栈继续创建功能或更新功能修改,否则不能修改。Terraform 1.x 版本相互兼容,可以进行修改。

    初始值

    修改后的值

    Aliyun::Terraform-v1.0

    Aliyun::Terraform-v1.1或Aliyun::Terraform-v1.2

    Aliyun::Terraform-v1.1

    Aliyun::Terraform-v1.0或Aliyun::Terraform-v1.2

    Aliyun::Terraform-v1.2

    Aliyun::Terraform-v1.0或Aliyun::Terraform-v1.1

    说明

    您可以调用GetFeatureDetails接口,获取每个Transform版本允许更新到的版本(UpdateAllowedTransforms参数)。

Workspace(必选)

Terraform Workspace中所有模块的键值对。键为模块文件路径,值为模块文件内容。

Workspace使用说明如下:

  • Workspace内容不能为空,且最多指定50个文件。

  • 文件路径

    • 最长为1024个字符,路径中每个文件夹或文件的名字最长为255个字符。

    • 文件路径必须是相对路径,不能以正斜线(/)开头,不能以.json.tfstate.hcl结尾。如果.tf文件以.debug.tf结尾,则该文件会被ROS忽略,不参与Terraform编排。

    • 可包含英文字母、数字或特殊字符!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~

    • 最大深度为5。例如:main.tf深度为1,modules/vpc/main.tf深度为3。

    • 路径分隔符正斜线(/)之间的值不能为空、...

  • 文件内容

    • 不能使用Provisioner功能Backend功能Terraform Cloud功能

    • 可以使用Module Source功能,仅支持使用阿里云官方提供的module以及local module,使用local module时source只能为Workspace内的相对引用,必须以./开头,不能包含$%,路径分隔符正斜线(/)之间的值不能为空、...

    • 可以使用Provider功能

      以下代码示例中可变参数均需替换为您实际的相关信息,尖括号(<>)在最终代码中不保留。涉及替换的可变参数取值如下:

      • <provider>:alicloud、aws、azurerm、random、template、time、fortios、fortimanager、helm或kubernetes。

      • <host>:registry.terraform.io或未定义。

      • <namespace>:hashicorp、aliyun、fortinetdev或未定义。

      terraform {
          required_providers {
              <provider> = {
                  source = "<host>/<namespace>/<provider>"
                  ...
              }
          }
      }
      
      provider "<provider>" {
          ...
      }
    • Provider部分配置项受限使用或禁止使用。具体如下:

      • 受限使用的配置项:

        • alicloud:shared_credentials_file。

        • aws:assume_role_with_web_identity.web_identity_token_file、custom_ca_bundle。

        • azurerm:client_id_file_path、client_certificate_path、client_secret_file_path、oidc_token_file_path。

        • fortios:cabundlefile、fmg_cabundlefile。

        • fortimanager:cabundlefile。

        • helm:kubernetes.config_path。

        • kubernetes:config_path。

          说明

          限制如下:

          • 必须是不跨行的字符串,不能是其他形式,例如:变量的引用。

          • 使用正斜线(/)分隔后,每个分词中只能包含英文字母、数字或特殊字符-_.,不能是空、...

          • 使用正斜线(/)分隔后,第一个分词如果不满足上述规则,则必须是.${path.module}${path.root}${path.cwd}${terraform.workspace}其中之一。

      • 禁止使用的配置项:

        • aws:shared_config_files、shared_credentials_files。

        • helm:plugins_path、registry_config_path、repository_config_path、repository_cache、kubernetes.config_paths、kubernetes.exec。

        • kubernetes:config_paths、exec。

    • 可以使用Provider中包含的ResourcesData Sources,不能使用terraform_remote_stateData Sources的一种)、template.template_dirResources的一种)、template.template_file(Data Sources的一种)。

    • 部分ResourcesData Sources的属性受限使用。具体如下:

      • alicloud_file_crc64_checksum:filename。

      • helm_template:repository_key_file、repository_cert_file、repository_ca_file。

        说明

        限制如下:

        • 必须是不跨行的字符串,不能是其他形式,例如:变量的引用。

        • 使用正斜线(/)分隔后,每个分词中只能包含英文字母、数字或特殊字符-_.,不能是空、...

        • 使用正斜线(/)分隔后,第一个分词如果不满足上述规则,则必须是.${path.module}${path.root}${path.cwd}${terraform.workspace}其中之一。

  • 不能使用函数templatefile

  • 函数filefileexistsfilesetfilebase64的path参数限制如下:

    • 必须存在。

    • 必须是不跨行的字符串,不能是其他形式,例如:变量的引用。

    • 使用正斜线(/)分隔后,第一个分词必须是${path.module}${path.root}${path.cwd}${terraform.workspace}

    • 使用正斜线(/)分隔后,从第二个分词开始,每个分词中只能包含英文字母、数字或特殊字符-_.,不能是空、...

Description(可选)

Terraform类型模板的描述信息。

Parameters(可选)

Terraform类型模板的参数,与ROS类型模板参数(Parameters)语法相同。更多信息,请参见概览

Parameters使用说明如下:

  • Parameters中的参数必须在.tf文件中定义,但.tf文件中的参数可以不在Parameters中定义。

    • 如果.tf文件中定义的参数未在Parameters中定义,则ROS会自动从.tf文件中提取参数,并在Parameters中生成定义。

    • 如果.tf文件中定义的参数已经在Parameters中定义,则不会提取参数,使用Parameters中已有的定义。

  • Parameters中的参数类型必须与.tf文件中的参数类型一致。

    假定Parameters中参数类型为A,.tf文件中的参数类型为B,其约束关系如下表所示。

    表 1. Parameters与.tf文件中的参数类型的约束关系

    .tf文件中的参数类型(B)

    Parameters中的参数类型(A)

    any或者未定义

    假定.tf文件中的参数的默认值的类型为C,A的取值如下:

    • 如果C未定义或默认值为null:StringNumberCommaDelimitedListJsonBooleanALIYUN::OOS::Parameter::ValueALIYUN::OOS::SecretParameter::Value

    • 如果C为string:StringALIYUN::OOS::Parameter::ValueALIYUN::OOS::SecretParameter::Value。如果默认值可以转化为数字,则A还允许Number

    • 如果C为number:NumberStringALIYUN::OOS::Parameter::ValueALIYUN::OOS::SecretParameter::Value

    • 如果C为bool:BooleanStringALIYUN::OOS::Parameter::ValueALIYUN::OOS::SecretParameter::Value

    • 如果C为list(string):JsonCommaDelimitedListStringALIYUN::OOS::Parameter::ValueALIYUN::OOS::SecretParameter::Value

    • 如果C为其他类型:JsonStringALIYUN::OOS::Parameter::ValueALIYUN::OOS::SecretParameter::Value

    string

    StringALIYUN::OOS::Parameter::ValueALIYUN::OOS::SecretParameter::Value

    number

    NumberStringALIYUN::OOS::Parameter::ValueALIYUN::OOS::SecretParameter::Value

    bool

    BooleanStringALIYUN::OOS::Parameter::ValueALIYUN::OOS::SecretParameter::Value

    list(string)

    JsonCommaDelimitedListStringALIYUN::OOS::Parameter::ValueALIYUN::OOS::SecretParameter::Value

    其他类型

    JsonStringALIYUN::OOS::Parameter::ValueALIYUN::OOS::SecretParameter::Value

您可以根据需要,提取Terraform模板参数。如果.tf文件中定义的参数未在Parameters中定义,则ROS会自动从.tf文件中提取参数,并在Parameters中生成定义。

  • 参数名:提取前后参数名不变。除了内置的伪参数外,参数名不能以ALIYUN__开头。

  • 参数传递文件:不建议再使用.tfvars文件(Terraform用来传递参数值的文件)传递参数值,而是通过ROS参数进行传递。如果要使用.tfvars文件,只能使用.auto.tfvars文件或terraform.tfvars文件(其他.tfvars文件无效),且需要注意.tfvars文件与ROS参数之间的优先级。优先级从高到低如下:

    1. .auto.tfvars文件。

      不建议使用多个文件。如果有多个文件,按文件名逆序排列,排前面的优先级高。例如:b.auto.tfvars比a.auto.tfvars优先级高。

    2. ROS参数。

    3. terraform.tfvars文件。

  • 伪参数:通过在.tf文件中定义如下参数,您可以使用ROS相应的伪参数(Pseudo parameters)

    .tf文件中参数名

    .tf文件中参数类型

    ROS伪参数名

    说明

    ALIYUN__StackId

    string

    ALIYUN::StackId

    资源栈ID。

    ALIYUN__StackName

    string

    ALIYUN::StackName

    资源栈名称。

    ALIYUN__TenantId

    string

    ALIYUN::TenantId

    当前账号的阿里云账号ID。

    ALIYUN__Region

    string

    ALIYUN::Region

    资源栈所在地域。

    ALIYUN__AccountId

    string

    ALIYUN::AccountId

    执行者账号ID。

    ALIYUN__NoValue

    string

    ALIYUN::NoValue

    取值为null。

    ALIYUN__ResourceGroupId

    string

    资源栈所属资源组。

    ALIYUN__Tags

    map(string)

    资源栈关联的标签。Key为标签键,Value为标签值。

  • 提取规则:

    .tf文件中参数原有字段

    提取后的Parameters中参数的字段及说明

    type

    Type。规则如下:

    • 如果type为any或者未定义,则基于默认值推断:

      • 如果没有定义默认值或者默认值为null,则Type为String

      • 如果默认值为string类型,则Type为String

      • 如果默认值为number类型,则Type为Number

      • 如果默认值为bool类型,则Type为Boolean

      • 如果默认值为其他类型,则Type为Json

      重要
      • 强烈建议对类型进行定义,避免默认类型(string)与预期不一致。

      • 如果type未定义且默认值形式为数值时,Terraform会把它识别为字符串,ROS推断出的类型(Type)为String。

        variable "i" {
          default = 1      //会被识别为字符串:"1",ROS推断类型为String。
        }
        variable "f" {
          default = 1.1    //会被识别为字符串:"1.1",ROS推断类型为String。
        }
        
        variable "l" {
          default = [1.1]  //会被识别为字符串:["1.1"],ROS推断类型为Json。
        }
    • 如果type为string,则Type为String

    • 如果type为number,则Type为Number

    • 如果type为bool,则Type为Boolean

    • 如果type为其他类型,则Type为Json

    default

    Default

    sensitive

    NoEcho

    description

    • 如果description不是Json字符串,则生成Description。

    • 如果description是Json字符串,则要求其内容与ROS类型模板参数(Parameters)语法相同,限制如下:

      • 不能包含不支持的字段。

      • 如果NoEcho已定义,则不再使用sensitive;如果NoEcho未定义,则使用sensitive。

      • 如果Default已定义,则不再使用default;如果Default未定义,则使用default。

      • 如果Type已定义,则必须与type一致。更多信息,请参见Parameters与.tf文件中的参数类型的约束关系

  • 提取后的参数示例:

    Parameters:
      subnet_mask:
        Description:
          en: Subnet mask of VSwitch
          zh-cn: 交换机子网掩码
        Label:
          en: Subnet mask
          zh-cn: 子网掩码
        MaxValue: 31
        MinValue: 13
        Default: 21
        Type: Number
      zone_id:
        AssociationProperty: 'ALIYUN::ECS::Instance::ZoneId'
        Description:
          en: Zone of VSwitch
          zh-cn: 交换机所在可用区
        Label:
          en: Zone
          zh-cn: 可用区
        Type: String
      vpc_name:
        Default: tf_test
        Description: 专有网络名称
        Type: String

Outputs(可选)

Terraform类型模板的输出,与ROS类型模板输出(Outputs)语法相同。

Outputs使用说明如下:

  • Outputs中的输出必须在.tf文件中定义,但.tf文件中的输出可以不在Outputs中定义。

    • 如果.tf文件中定义的输出未在Outputs中定义,则ROS会自动从.tf文件中提取输出,并在Outputs中生成定义。

    • 如果.tf文件中定义的输出已经在Outputs中定义,则不会提取输出,而是使用Outputs中已有的定义。

  • Outputs中无法使用Condition字段。

  • Value字段建议设置为null,实际会返回Terraform的输出。

您可以根据需要,提取Terraform模板输出。如果.tf文件中定义的输出未在Outputs中定义,则ROS会自动从.tf文件中提取输出,并在Outputs中生成定义。

  • 提取规则:

    • 输出名称:保持不变。

    • description字段:

      • 如果description不是Json字符串,则对应生成Description字段。

      • 如果description是Json字符串,则要求其内容与ROS类型模板输出(Outputs)语法相同,目前支持Description、Label字段。

  • 提取后的输出示例:

    Outputs:
      vpc_id:
        Value: null
        Description:
          en: VPC ID
          zh-cn: 专有网络ID
      vsw_id:
        Value: null
        Description:
          en: VSwitch ID
          zh-cn: 交换机ID

Metadata(可选)

关于模板元数据的更多信息,请参见元数据(Metadata)

说明

如果仅在控制台使用Metadata,您可以通过在Workspace中添加.metadata文件代替。

Mappings(可选)

关于模板映射的更多信息,请参见映射(Mappings)

说明

如果在Workspace中添加了.mappings文件,并且内容是一个有效的JSON字典,ROS会使用该字典覆盖Mappings字段。

Conditions(可选)

关于模板条件的更多信息,请参见条件(Conditions)

说明

如果在Workspace中添加了.conditions文件,并且内容是一个有效的JSON字典,ROS会使用该字典覆盖Conditions字段。

Rules(可选)

关于模板规则的更多信息,请参见规则(Rules)

说明

如果在Workspace中添加了.rules文件,并且内容是一个有效的JSON字典,ROS会使用该字典覆盖Rules字段。