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

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版本。

Transform使用说明如下：

ROS会随Terraform版本发布增加Transform参数的取值。
Terraform小版本变动（版本号x.y.z中的z发生变化）不影响Transform的取值。

满足如下条件时，Transform参数可以通过资源栈继续创建功能或更新功能修改，否则不能修改。

初始值	修改后的值
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中包含的Resources和Data Sources，不能使用terraform_remote_state（Data Sources的一种）、template.template_dir（Resources的一种）。
- 函数file、fileexists、fileset、filebase64和templatefile的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：`String`、`Number`、`CommaDelimitedList`、`Json`、`Boolean`、`ALIYUN::OOS::Parameter::Value`或`ALIYUN::OOS::SecretParameter::Value`。如果C为string：`String`、`ALIYUN::OOS::Parameter::Value`或`ALIYUN::OOS::SecretParameter::Value`。如果C为number：`Number`、`String`、`ALIYUN::OOS::Parameter::Value`或`ALIYUN::OOS::SecretParameter::Value`。如果C为bool：`Boolean`、`String`、`ALIYUN::OOS::Parameter::Value`或`ALIYUN::OOS::SecretParameter::Value`。如果C为list（string）：`Json`、`CommaDelimitedList`、`String`、`ALIYUN::OOS::Parameter::Value`或`ALIYUN::OOS::SecretParameter::Value`。如果C为其他类型：`Json`、`String`、`ALIYUN::OOS::Parameter::Value`或`ALIYUN::OOS::SecretParameter::Value`。
string	`String`、`ALIYUN::OOS::Parameter::Value`或`ALIYUN::OOS::SecretParameter::Value`。
number	`Number`、`String`、`ALIYUN::OOS::Parameter::Value`或`ALIYUN::OOS::SecretParameter::Value`。
bool	`Boolean`、`String`、`ALIYUN::OOS::Parameter::Value`或`ALIYUN::OOS::SecretParameter::Value`。
list（string）	`Json`、`CommaDelimitedList`、`String`、`ALIYUN::OOS::Parameter::Value`或`ALIYUN::OOS::SecretParameter::Value`。
其他类型	`Json`、`String`、`ALIYUN::OOS::Parameter::Value`或`ALIYUN::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字段。