Terraform类型模板是资源编排服务ROS(Resource Orchestration Service)托管Terraform后支持的模板,用于编排阿里云、AWS或Azure的资源。您可以在模板中定义资源、参数以及资源间的依赖关系。
模板结构
Terraform类型模板由8部分组成,模板结构如以下代码所示。
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}"
}
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功能,但只能为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
。 - 如果C未定义或默认值为null:
您可以根据需要,提取Terraform模板参数。如果.tf文件中定义的参数未在Parameters中定义,则ROS会自动从.tf文件中提取参数,并在Parameters中生成定义。
- 参数名:提取前后参数名不变。除了内置的伪参数外,参数名不能以
ALIYUN__
开头。 - 参数传递文件:不建议再使用.tfvars文件(Terraform用来传递参数值的文件)传递参数值,而是通过ROS参数进行传递。如果要使用.tfvars文件,只能使用.auto.tfvars文件或terraform.tfvars文件(其他.tfvars文件无效),且需要注意.tfvars文件与ROS参数之间的优先级。优先级从高到低如下:
- .auto.tfvars文件。
不建议使用多个文件。如果有多个文件,按文件名逆序排列,排前面的优先级高。例如:b.auto.tfvars比a.auto.tfvars优先级高。
- ROS参数。
- terraform.tfvars文件。
- .auto.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。 }
- 如果没有定义默认值或者默认值为null,则Type为
- 如果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文件中的参数类型的约束关系。
- 如果type为any或者未定义,则基于默认值推断:
- 提取后的参数示例:
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字段。
- 如果description不是
- 提取后的输出示例:
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
文件代替。
Mappings(可选)
关于模板映射的更多信息,请参见映射(Mappings)。
.mappings
文件,并且内容是一个有效的JSON字典,ROS会使用该字典覆盖Mappings字段。
Conditions(可选)
关于模板条件的更多信息,请参见条件(Conditions)。
.conditions
文件,并且内容是一个有效的JSON字典,ROS会使用该字典覆盖Conditions字段。
Rules(可选)
关于模板规则的更多信息,请参见规则(Rules)。
.rules
文件,并且内容是一个有效的JSON字典,ROS会使用该字典覆盖Rules字段。