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

模板结构

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:
    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}"
    }

模板说明

Terraform类型模板第一层只能包含下表所示的参数:

参数 是否必选 说明
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版本。
说明
  • ROS会随Terraform版本发布增加Transform参数的取值。
  • Terraform小版本变动(版本号x.y.z中的z发生变化)不影响Transform的取值。
  • 您可以在创建Terraform模板时指定Terraform类型模板的参数(Parameters)的取值,但在创建模板后不能修改Terraform类型模板的参数。
Workspace Terraform Workspace中所有模块的键值对。键为模块文件路径,值为模块文件内容。
Description Terraform类型模板的描述信息。
Parameters Terraform类型模板的参数,与ROS类型模板参数(Parameters)语法相同。更多信息,请参见参数(Parameters)

使用限制如下:

  • Parameters中的参数必须在.tf文件中定义,但.tf文件中的参数可以不在Parameters中定义。
    • 如果.tf文件中定义的参数未在Parameters中定义,则ROS会自动从.tf文件中提取参数,并在Parameters中生成定义。更多信息,请参见提取Terraform模板参数
    • 如果.tf文件中定义的参数已经在Parameters中定义,则不会提取参数,使用Parameters中已有的定义。
  • Parameters中的参数类型必须与.tf文件中的参数类型一致。

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

    • 如果B未定义,则A允许为String、Number、CommaDelimitedList、Json、Boolean、ALIYUN::OOS::Parameter::Value或ALIYUN::OOS::SecretParameter::Value。
    • 如果B为string,则A允许为String、ALIYUN::OOS::Parameter::Value或ALIYUN::OOS::SecretParameter::Value。
    • 如果B为number,则A允许为Number、String、ALIYUN::OOS::Parameter::Value或ALIYUN::OOS::SecretParameter::Value。
    • 如果B为bool,则A允许为Boolean、String、ALIYUN::OOS::Parameter::Value或ALIYUN::OOS::SecretParameter::Value。
    • 如果B为list(string),则A允许为CommaDelimitedList、String、ALIYUN::OOS::Parameter::Value或ALIYUN::OOS::SecretParameter::Value。
    • 如果B为其他类型,则A允许为Json、String、ALIYUN::OOS::Parameter::Value或ALIYUN::OOS::SecretParameter::Value。
Outputs Terraform类型模板的输出,与ROS类型模板输出(Outputs)语法相同。更多信息,请参见输出(Outputs)

使用限制如下:

  • Outputs中的输出必须在.tf文件中定义,但.tf文件中的输出可以不在Outputs中定义。
    • 如果.tf文件中定义的输出未在Outputs中定义,则ROS会自动从.tf文件中提取输出,并在Outputs中生成定义。更多信息,请参见提取Terraform模板输出
    • 如果.tf文件中定义的输出已经在Outputs中定义,则不会提取输出,而是使用Outputs中已有的定义。
  • Outputs中无法使用Condition字段。
  • Value字段建议设置为null,实际会返回Terraform的输出。
Metadata 模板元数据。

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

提取Terraform模板参数

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

提取前后参数名不变。除了内置的伪参数外,参数名不能以ALIYUN__开头。更多信息,请参见使用ROS伪参数

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

优先级从高到低如下:

  • .auto.tfvars文件。

    不建议使用多个文件。

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

  • ROS参数。
  • terraform.tfvars文件。

提取规则如下:

.tf文件中参数原有字段 提取后的Parameters中参数的字段及说明
type Type。规则如下:
  • 如果type未定义或为string,则Type为String。
    注意 强烈建议对类型进行定义,避免默认类型(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参数说明列的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

提取Terraform模板输出

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

  • 输出名称:保持不变。
  • description字段:
    • 如果description不是Json字符串,则对应生成Description字段。
    • 如果description是Json字符串,则要求其内容与ROS类型模板输出(Outputs)语法相同,目前只支持Description字段。

提取后的示例模板输出部分如下:

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

使用ROS伪参数

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

.tf文件中参数名 .tf文件中参数类型 ROS伪参数名
ALIYUN__StackId string ALIYUN::StackId
ALIYUN__StackName string ALIYUN::StackName
ALIYUN__TenantId string ALIYUN::TenantId
ALIYUN__Region string ALIYUN::Region
ALIYUN__AccountId string ALIYUN::AccountId
ALIYUN__NoValue string ALIYUN::NoValue

模板中Workspace的限制条件

Workspace包含文件路径和文件内容,限制条件如下:

  • Workspace内容不能为空,且最多指定50个文件。
  • 文件路径
    • 最长为1024个字符,路径中每个文件夹或文件的名字最长为255个字符。
    • 文件路径必须是相对路径,不能以正斜线(/)开头,不能以.json.tfstate.hcl结尾。
    • 可包含英文字母、数字或特殊字符!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~
    • 最大深度为5。例如:main.tf深度为1,modules/vpc/main.tf深度为3。
    • 路径分隔符正斜线(/)之间的值不能为空、...
  • 文件内容
    • 不能使用Provisioner功能Backend功能
    • 可以使用Module Source功能,但只能为Workspace内的相对引用。必须以./开头,路径分隔符正斜线(/)之间的值不能为空、...
    • 可以使用Provider功能,但有所限制,具体规则如下:
      • 下方代码中<provider>处只能为:alicloud、aws、azurerm、random、template、time、fortios或fortimanager。
      • 下方代码中<host>处只能为:registry.terraform.io或未定义。
      • 下方代码中<namespace>处只能为:hashicorp、aliyun、fortinetdev或未定义。
      terraform {
          required_providers {
              <provider> = {
                  source = "<host>/<namespace>/<provider>"
                  ...
              }
          }
      }
      
      provider "<provider>" {
          ...
      }
    • 可以使用Provider中包含的ResourceDataSource,不能使用terraform_remote_stateDataSource的一种)、template.template_dirResource的一种)。
    • 函数filefileexistsfilesetfilebase64templatefile的path参数限制如下:
      • 必须存在。
      • 必须是不跨行的字符串,不能是变量的引用等。
      • 使用正斜线(/)分割后,第一个分词必须是${path.module}${path.root}${path.cwd}${terraform.workspace}
      • 使用正斜线(/)分割后,从第二个分词开始,每个分词中只能包含英文字母、数字或特殊字符-_.,不能是空、...