模板結(jié)構(gòu)

Terraform類型模板由10部分組成，模板結(jié)構(gòu)如以下代碼所示。

ROSTemplateFormatVersion: '2015-09-01'
Transform: 'Aliyun::Terraform-v1.5'
Parameters:
  subnet_mask:
    Type: Number
    Description:
      en: Subnet mask of VSwitch
      zh-cn: 交換機(jī)子網(wǎng)掩碼
    Label:
      en: Subnet mask
      zh-cn: 子網(wǎng)掩碼
    MinValue: 13
    MaxValue: 31
    Default: 21
Outputs:
  vpc_id:
    Value: null
    Description:
      en: VPC ID
      zh-cn: 專有網(wǎng)絡(luò)ID
Workspace:
  main.tf: |-
    variable "zone_id" {
      type        = string
      description = <<EOT
      {
        "AssociationProperty": "ALIYUN::ECS::Instance::ZoneId",
        "Description": {
          "en": "Zone of VSwitch",
          "zh-cn": "交換機(jī)所在可用區(qū)"
        },
        "Label": {
          "en": "Zone",
          "zh-cn": "可用區(qū)"
        }
      }
      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": "交換機(jī)ID"
        }
      }
      EOT
    }
  modules/vpc/main.tf: |-
    variable "vpc_name" {
      type        = string
      default     = "tf_test"
      description = "專有網(wǎng)絡(luò)名稱"
    }
    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支持的模板版本號(hào)。取值：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版本。

Transform使用說明如下：

• ROS會(huì)隨Terraform版本發(fā)布增加Transform參數(shù)的取值。

• Terraform小版本變動(dòng)（版本號(hào)x.y.z中的z發(fā)生變化）不影響Transform的取值。

• 滿足如下條件時(shí)，Transform參數(shù)可以通過資源棧繼續(xù)創(chuàng)建功能或更新功能修改，否則不能修改。Terraform 1.x 版本相互兼容，可以進(jìn)行修改。

  初始值	修改后的值
  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

  說明

  您可以調(diào)用GetFeatureDetails接口，獲取每個(gè)Transform版本允許更新到的版本（UpdateAllowedTransforms參數(shù)）。

Workspace（必選）

Terraform Workspace中所有模塊的鍵值對(duì)。鍵為模塊文件路徑，值為模塊文件內(nèi)容。

Workspace使用說明如下：

• Workspace內(nèi)容不能為空，且最多指定50個(gè)文件。

• 文件路徑

  • 最長(zhǎng)為1024個(gè)字符，路徑中每個(gè)文件夾或文件的名字最長(zhǎng)為255個(gè)字符。

  • 文件路徑必須是相對(duì)路徑，不能以正斜線（/）開頭，不能以.json、.tfstate或.hcl結(jié)尾。如果.tf文件以.debug.tf結(jié)尾，則該文件會(huì)被ROS忽略，不參與Terraform編排。

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

  • 最大深度為5。例如：main.tf深度為1，modules/vpc/main.tf深度為3。

  • 路徑分隔符正斜線（/）之間的值不能為空、.或..。

• 文件內(nèi)容

  • 不能使用Provisioner功能、Backend功能和Terraform Cloud功能。

  • 可以使用Module Source功能，僅支持使用阿里云官方提供的module以及l(fā)ocal module，使用local module時(shí)source只能為Workspace內(nèi)的相對(duì)引用，必須以./開頭，不能包含$和%，路徑分隔符正斜線（/）之間的值不能為空、.或..。

  • 可以使用Provider功能。

    以下代碼示例中可變參數(shù)均需替換為您實(shí)際的相關(guān)信息，尖括號(hào)（<>）在最終代碼中不保留。涉及替換的可變參數(shù)取值如下：

    • <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部分配置項(xiàng)受限使用或禁止使用。具體如下：

    • 受限使用的配置項(xiàng)：

      • 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。

        說明

        限制如下：

        • 必須是不跨行的字符串，不能是其他形式，例如：變量的引用。

        • 使用正斜線（/）分隔后，每個(gè)分詞中只能包含英文字母、數(shù)字或特殊字符-_.，不能是空、.或..。

        • 使用正斜線（/）分隔后，第一個(gè)分詞如果不滿足上述規(guī)則，則必須是.、${path.module}、${path.root}、${path.cwd}或${terraform.workspace}其中之一。

    • 禁止使用的配置項(xiàng)：

      • 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。

      說明

      限制如下：

      • 必須是不跨行的字符串，不能是其他形式，例如：變量的引用。

      • 使用正斜線（/）分隔后，每個(gè)分詞中只能包含英文字母、數(shù)字或特殊字符-_.，不能是空、.或..。

      • 使用正斜線（/）分隔后，第一個(gè)分詞如果不滿足上述規(guī)則，則必須是.、${path.module}、${path.root}、${path.cwd}或${terraform.workspace}其中之一。

• 不能使用函數(shù)templatefile。

• 函數(shù)file、fileexists、fileset和filebase64的path參數(shù)限制如下：

  • 必須存在。

  • 必須是不跨行的字符串，不能是其他形式，例如：變量的引用。

  • 使用正斜線（/）分隔后，第一個(gè)分詞必須是${path.module}、${path.root}、${path.cwd}或${terraform.workspace}。

  • 使用正斜線（/）分隔后，從第二個(gè)分詞開始，每個(gè)分詞中只能包含英文字母、數(shù)字或特殊字符-_.，不能是空、.或..。

Description（可選）

Terraform類型模板的描述信息。

Parameters（可選）

Terraform類型模板的參數(shù)，與ROS類型模板參數(shù)（Parameters）語法相同。更多信息，請(qǐng)參見概覽。

Parameters使用說明如下：

• Parameters中的參數(shù)必須在.tf文件中定義，但.tf文件中的參數(shù)可以不在Parameters中定義。

  • 如果.tf文件中定義的參數(shù)未在Parameters中定義，則ROS會(huì)自動(dòng)從.tf文件中提取參數(shù)，并在Parameters中生成定義。

  • 如果.tf文件中定義的參數(shù)已經(jīng)在Parameters中定義，則不會(huì)提取參數(shù)，使用Parameters中已有的定義。

• Parameters中的參數(shù)類型必須與.tf文件中的參數(shù)類型一致。

  假定Parameters中參數(shù)類型為A，.tf文件中的參數(shù)類型為B，其約束關(guān)系如下表所示。

  表 1. Parameters與.tf文件中的參數(shù)類型的約束關(guān)系

  .tf文件中的參數(shù)類型（B）	Parameters中的參數(shù)類型（A）
  any或者未定義	假定.tf文件中的參數(shù)的默認(rèn)值的類型為C，A的取值如下： 如果C未定義或默認(rèn)值為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。如果默認(rèn)值可以轉(zhuǎn)化為數(shù)字，則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。

您可以根據(jù)需要，提取Terraform模板參數(shù)。如果.tf文件中定義的參數(shù)未在Parameters中定義，則ROS會(huì)自動(dòng)從.tf文件中提取參數(shù)，并在Parameters中生成定義。

• 參數(shù)名：提取前后參數(shù)名不變。除了內(nèi)置的偽參數(shù)外，參數(shù)名不能以ALIYUN__開頭。

• 參數(shù)傳遞文件：不建議再使用.tfvars文件（Terraform用來傳遞參數(shù)值的文件）傳遞參數(shù)值，而是通過ROS參數(shù)進(jìn)行傳遞。如果要使用.tfvars文件，只能使用.auto.tfvars文件或terraform.tfvars文件（其他.tfvars文件無效），且需要注意.tfvars文件與ROS參數(shù)之間的優(yōu)先級(jí)。優(yōu)先級(jí)從高到低如下：

  1. .auto.tfvars文件。

     不建議使用多個(gè)文件。如果有多個(gè)文件，按文件名逆序排列，排前面的優(yōu)先級(jí)高。例如：b.auto.tfvars比a.auto.tfvars優(yōu)先級(jí)高。

  2. ROS參數(shù)。

  3. terraform.tfvars文件。

• 偽參數(shù)：通過在.tf文件中定義如下參數(shù)，您可以使用ROS相應(yīng)的偽參數(shù)（Pseudo parameters）。

  .tf文件中參數(shù)名	.tf文件中參數(shù)類型	ROS偽參數(shù)名	說明
  ALIYUN__StackId	string	ALIYUN::StackId	資源棧ID。
  ALIYUN__StackName	string	ALIYUN::StackName	資源棧名稱。
  ALIYUN__TenantId	string	ALIYUN::TenantId	當(dāng)前賬號(hào)的阿里云賬號(hào)ID。
  ALIYUN__Region	string	ALIYUN::Region	資源棧所在地域。
  ALIYUN__AccountId	string	ALIYUN::AccountId	執(zhí)行者賬號(hào)ID。
  ALIYUN__NoValue	string	ALIYUN::NoValue	取值為null。
  ALIYUN__ResourceGroupId	string	無	資源棧所屬資源組。
  ALIYUN__Tags	map(string)	無	資源棧關(guān)聯(lián)的標(biāo)簽。Key為標(biāo)簽鍵，Value為標(biāo)簽值。

• 提取規(guī)則：

  .tf文件中參數(shù)原有字段	提取后的Parameters中參數(shù)的字段及說明
  type	Type。規(guī)則如下： 如果type為any或者未定義，則基于默認(rèn)值推斷： 如果沒有定義默認(rèn)值或者默認(rèn)值為null，則Type為String。 如果默認(rèn)值為string類型，則Type為String。 如果默認(rèn)值為number類型，則Type為Number。 如果默認(rèn)值為bool類型，則Type為Boolean。 如果默認(rèn)值為其他類型，則Type為Json。 重要 強(qiáng)烈建議對(duì)類型進(jìn)行定義，避免默認(rèn)類型（string）與預(yù)期不一致。 如果type未定義且默認(rèn)值形式為數(shù)值時(shí)，Terraform會(huì)把它識(shí)別為字符串，ROS推斷出的類型（Type）為String。 variable "i" { default = 1 //會(huì)被識(shí)別為字符串："1"，ROS推斷類型為String。 } variable "f" { default = 1.1 //會(huì)被識(shí)別為字符串："1.1"，ROS推斷類型為String。 } variable "l" { default = [1.1] //會(huì)被識(shí)別為字符串：["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字符串，則要求其內(nèi)容與ROS類型模板參數(shù)（Parameters）語法相同，限制如下： 不能包含不支持的字段。 如果NoEcho已定義，則不再使用sensitive；如果NoEcho未定義，則使用sensitive。 如果Default已定義，則不再使用default；如果Default未定義，則使用default。 如果Type已定義，則必須與type一致。更多信息，請(qǐng)參見Parameters與.tf文件中的參數(shù)類型的約束關(guān)系。

• 提取后的參數(shù)示例：

  Parameters:
    subnet_mask:
      Description:
        en: Subnet mask of VSwitch
        zh-cn: 交換機(jī)子網(wǎng)掩碼
      Label:
        en: Subnet mask
        zh-cn: 子網(wǎng)掩碼
      MaxValue: 31
      MinValue: 13
      Default: 21
      Type: Number
    zone_id:
      AssociationProperty: 'ALIYUN::ECS::Instance::ZoneId'
      Description:
        en: Zone of VSwitch
        zh-cn: 交換機(jī)所在可用區(qū)
      Label:
        en: Zone
        zh-cn: 可用區(qū)
      Type: String
    vpc_name:
      Default: tf_test
      Description: 專有網(wǎng)絡(luò)名稱
      Type: String

Outputs（可選）

Terraform類型模板的輸出，與ROS類型模板輸出（Outputs）語法相同。

Outputs使用說明如下：

• Outputs中的輸出必須在.tf文件中定義，但.tf文件中的輸出可以不在Outputs中定義。

  • 如果.tf文件中定義的輸出未在Outputs中定義，則ROS會(huì)自動(dòng)從.tf文件中提取輸出，并在Outputs中生成定義。

  • 如果.tf文件中定義的輸出已經(jīng)在Outputs中定義，則不會(huì)提取輸出，而是使用Outputs中已有的定義。

• Outputs中無法使用Condition字段。

• Value字段建議設(shè)置為null，實(shí)際會(huì)返回Terraform的輸出。

您可以根據(jù)需要，提取Terraform模板輸出。如果.tf文件中定義的輸出未在Outputs中定義，則ROS會(huì)自動(dòng)從.tf文件中提取輸出，并在Outputs中生成定義。

• 提取規(guī)則：

  • 輸出名稱：保持不變。

  • description字段：

    • 如果description不是Json字符串，則對(duì)應(yīng)生成Description字段。

    • 如果description是Json字符串，則要求其內(nèi)容與ROS類型模板輸出（Outputs）語法相同，目前支持Description、Label字段。

• 提取后的輸出示例：

  Outputs:
    vpc_id:
      Value: null
      Description:
        en: VPC ID
        zh-cn: 專有網(wǎng)絡(luò)ID
    vsw_id:
      Value: null
      Description:
        en: VSwitch ID
        zh-cn: 交換機(jī)ID

Metadata（可選）

關(guān)于模板元數(shù)據(jù)的更多信息，請(qǐng)參見元數(shù)據(jù)（Metadata）。

Mappings（可選）

關(guān)于模板映射的更多信息，請(qǐng)參見映射（Mappings）。

Conditions（可選）

關(guān)于模板條件的更多信息，請(qǐng)參見條件（Conditions）。

Rules（可選）

關(guān)于模板規(guī)則的更多信息，請(qǐng)參見規(guī)則（Rules）。