Terraform類型模板結構有哪些 - Resource Orchestration Service

Terraform類型模板是Resource Orchestration Service服務ROS（Resource Orchestration Service）託管Terraform後支援的模板，用於編排阿里雲、AWS或Azure的資源。您可以在模板中定義資源、參數以及資源間的依賴關係。

模板結構

Terraform類型模板由10部分組成，模板結構如以下代碼所示。

說明

關於Terraform類型模板組成部分的更多資訊，請參見模板文法。

ROSTemplateFormatVersion: '2015-09-01'
Transform: 'Aliyun::Terraform-v1.5'
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版本。
Aliyun::OpenTofu-v1.6：OpenTofu 1.6版本。
Aliyun::OpenTofu-v1.7：OpenTofu 1.7版本。
Aliyun::OpenTofu-v1.8：OpenTofu 1.8版本。

說明

由於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中包含的Resources和Data Sources，不能使用terraform_remote_state（Data Sources的一種）、template.template_dir（Resources的一種）、template.template_file（Data Sources的一種）。
- 部分Resources或Data 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。
函數file、fileexists、fileset和filebase64的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`。如果預設值可以轉化為數字，則A還允許`Number`。如果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欄位。