Terraform is supported as a hosted service in Resource Orchestration Service (ROS). You can use Terraform templates to orchestrate Alibaba Cloud, AWS, and Azure resources. You can define resources, parameters, and the dependencies between resources in a Terraform template.

Structure

A Terraform template consists of eight sections. The following sample code shows the template structure:

Note For more information about the structure of Terraform templates, see Terraform Language Documentation.
ROSTemplateFormatVersion: '2015-09-01'
Transform: 'Aliyun::Terraform-v1.0'
Parameters:
  subnet_mask:
    Type: Number
    Description:
      en: Subnet mask of VSwitch
       
    Label:
      en: Subnet mask
       
    MinValue: 13
    MaxValue: 31
    Default: 21
Outputs:
  vpc_id:
    Description:
      en: VPC ID
       
Workspace:
  main.tf: |-
    variable "zone_id" {
      type = string
      description = <<EOT
      {
        "AssociationProperty": "ALIYUN::ECS::Instance::ZoneId",
        "Description": {
          "en": "Zone of VSwitch",
           
        },
        "Label": {
          "en": "Zone",
           
        }
      }
      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",
           
        }
      }
      EOT
    }
  modules/vpc/main.tf: |-
    variable "vpc_name" {
      type = string
      default = "tf_test"
       
    }
    resource "alicloud_vpc" "vpc" {
      name       = var.vpc_name
      cidr_block = "172.16.0.0/12"
    }
    output "vpc_id" {
      value = "${alicloud_vpc.vpc.id}"
    }

(Required) ROSTemplateFormatVersion

The template version that is supported by ROS. In this example, the template version is 2015-09-01.

(Required) Transform

The Terraform version that is supported by ROS. Valid values:

  • Aliyun::Terraform-v0.12: corresponds to Terraform v0.12.
  • Aliyun::Terraform-v0.15: corresponds to Terraform v0.15.
  • Aliyun::Terraform-v1.0: corresponds to Terraform v1.0.
  • Aliyun::Terraform-v1.1: corresponds to Terraform v1.1.
  • Aliyun::Terraform-v1.2: corresponds to Terraform v1.2.

Before you configure the Transform section, take note of the following items:

  • When a new major or minor version of Terraform is released, ROS adds the version number as a value of the Transform parameter.
  • When a patch version of Terraform is changed, the value of the Transform parameter remains unchanged.
  • When you continue to create a stack or update a stack, you can replace the original value of the Transform parameter with a new value only if the original and new values meet the conditions in the following table.
    Original value New value
    Aliyun::Terraform-v1.0 Aliyun::Terraform-v1.1 or Aliyun::Terraform-v1.2
    Aliyun::Terraform-v1.1 Aliyun::Terraform-v1.0 or Aliyun::Terraform-v1.2
    Aliyun::Terraform-v1.2 Aliyun::Terraform-v1.0 or Aliyun::Terraform-v1.1
    Note You can use the value of the UpdateAllowedTransforms parameter in the response data of the GetFeatureDetails operation to query the versions to which Transform can be updated.

(Required) Workspace

The key-value pairs of all modules in a Terraform workspace. In a key-value pair, the key is the path of a module file and the value is the content of the module file.

Before you configure the Workspace section, take note of the following items:

  • The Workspace section can contain up to 50 files and cannot be empty.
  • File path
    • The file path can be up to 1,024 characters in length. The name of a folder or a file in the path can be up to 255 characters in length.
    • The file path must be a relative path and cannot start with a forward slash (/) or end with .json, .tfstate, or .hcl. If the name of the .tf file ends with .debug.tf, ROS ignores the file and does not use Terraform to orchestrate the file.
    • The file path can contain letters, digits, and special characters. The following special characters are supported: ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~.
    • The maximum depth of the file path is 5. For example, the depth of main.tf is 1, and the depth of modules/vpc/main.tf is 3.
    • The value between two forward slashes (/) cannot be empty, or contain one period (.) or two periods (..).
  • File content
    • The provisioner, backend, and Terraform Cloud features are not supported.
    • The module source feature is supported only for references in the Workspace section. The file content must start with ./. The file content cannot contain dollar signs ($) or percent signs (%). The value between two forward slashes (/) cannot be empty, or contain one period (.) or two periods (..).
    • The provider feature is supported.

      You must replace the variables in the following sample code with the actual information and remove the angle brackets (< >) in the final code. The following section lists the variables and the valid values:

      • <provider>: alicloud, aws, azurerm, random, template, time, fortios, fortimanager, helm, and kubernetes.
      • <host>: registry.terraform.io. You can also leave this variable empty.
      • <namespace>: hashicorp, aliyun, and fortinetdev. You can also leave this variable empty.
      terraform {
          required_providers {
              <provider> = {
                  source = "<host>/<namespace>/<provider>"
                  ...
              }
          }
      }
      
      provider "<provider>" {
          ...
      }
    • The resources and data sources of providers are supported. However, the terraform_remote_state data source and the template.template_dir resource are not supported.
    • The path parameter in the file, fileexists, fileset, filebase64, and templatefile functions must meet the following requirements:
      • This parameter is required.
      • The value must be a single-line string. For example, the value cannot be a reference to a variable.
      • When you separate variables in the value with forward slashes (/), make sure that the first variable is ${path.module}, ${path.root}, ${path.cwd}, or ${terraform.workspace}.
      • When you separate variables in the value with forward slashes (/), each variable that follows the first variable can contain only letters, digits, hyphens (-), underscores (_), and periods (.), but cannot be empty or contain one period (.) or two periods (..).

(Optional) Description

The description of the Terraform template.

(Optional) Parameters

The parameters of the Terraform template. The parameters of a Terraform template follow the same syntax as the parameters of an ROS template. For more information, see Overview.

Before you configure the Parameters section, take note of the following items:

  • The parameters in the Parameters section must be defined in the .tf file, but the parameters in the .tf file may not be defined in the Parameters section.
    • If the parameters that are defined in the .tf file are not defined in the Parameters section, ROS automatically extracts the parameters from the .tf file and generates definitions in the Parameters section.
    • If the parameters that are defined in the .tf file are defined in the Parameters section, ROS does not extract the parameters from the .tf file and uses the definitions in the Parameters section.
  • The parameter types in the Parameters section must be consistent with the parameter types in the .tf file.

    For example, a parameter type in the Parameters section is A, and the relevant parameter type in the .tf file is B. The following table describes the constraints between Parameter Type A and Parameter Type B.

    Table 1. Constraints between parameter types in the Parameters section and the .tf file
    Parameter Type B in the .tf file Parameter Type A in the Parameters section
    any or empty Valid values of A if the type of the default value in the .tf file is C:
    • Valid values of A if C is empty or the default value is null: String, Number, CommaDelimitedList, Json, Boolean, ALIYUN::OOS::Parameter::Value, and ALIYUN::OOS::SecretParameter::Value
    • Valid values of A if C is set to string: String, ALIYUN::OOS::Parameter::Value, and ALIYUN::OOS::SecretParameter::Value
    • Valid values of A if C is set to number: Number, String, ALIYUN::OOS::Parameter::Value, and ALIYUN::OOS::SecretParameter::Value
    • Valid values of A if C is set to bool: Boolean, String, ALIYUN::OOS::Parameter::Value, and ALIYUN::OOS::SecretParameter::Value
    • Valid values of A if C is set to list (string): Json, CommaDelimitedList, String, ALIYUN::OOS::Parameter::Value, and ALIYUN::OOS::SecretParameter::Value
    • Valid values of A if C is set to a type other than the preceding types: Json, String, ALIYUN::OOS::Parameter::Value, and ALIYUN::OOS::SecretParameter::Value
    string String, ALIYUN::OOS::Parameter::Value, and ALIYUN::OOS::SecretParameter::Value
    number Number, String, ALIYUN::OOS::Parameter::Value, and ALIYUN::OOS::SecretParameter::Value
    bool Boolean, String, ALIYUN::OOS::Parameter::Value, and ALIYUN::OOS::SecretParameter::Value
    list (string) Json, CommaDelimitedList, String, ALIYUN::OOS::Parameter::Value, and ALIYUN::OOS::SecretParameter::Value
    other types Json, String, ALIYUN::OOS::Parameter::Value, and ALIYUN::OOS::SecretParameter::Value

You can extract the parameters of a Terraform template based on your business requirements. If the parameters that are defined in the .tf file are not defined in the Parameters section, ROS automatically extracts the parameters from the .tf file and generates definitions in the Parameters section.

  • Parameter names: The names of parameters remain unchanged after the parameters are extracted. The names of the parameters, except built-in pseudo parameters, cannot start with ALIYUN__.
  • Parameter passing file: We recommend that you use ROS parameters instead of .tfvars files to pass parameter values. .tfvars files are variable definitions files in Terraform. If you want to use .tfvars files, you can use only .auto.tfvars files or .terraform.tfvars files. You must take note of the priorities of .tfvars files and ROS parameters. The following section describes the priorities in descending order:
    1. .auto.tfvars files.

      We recommend that you do not use multiple .auto.tfvars files. If you use multiple .auto.tfvars files, sort the files in reverse alphabetical order based on the names of the files. The first file has the highest priority. For example, the file named b.auto.tfvars has a higher priority than the file named a.auto.tfvars.

    2. ROS parameters.
    3. terraform.tfvars files.
  • Pseudo parameter: You can define the following parameters in the .tf file to use ROS pseudo parameters. For more information about pseudo parameters, see Pseudo parameters.
    Parameter name in the .tf file Parameter type in the .tf file Pseudo parameter name in ROS Description
    ALIYUN__StackId string ALIYUN::StackId The ID of the stack.
    ALIYUN__StackName string ALIYUN::StackName The name of the stack.
    ALIYUN__TenantId string ALIYUN::TenantId The ID of the Alibaba Cloud account.
    ALIYUN__Region string ALIYUN::Region The ID of the region where the stack resides.
    ALIYUN__AccountId string ALIYUN::AccountId The ID of the execution account.
    ALIYUN__NoValue string ALIYUN::NoValue The value is null.
    ALIYUN__ResourceGroupId string None. The ID of the resource group to which the stack belongs.
    ALIYUN__Tags map(string) None. The tags that are added to the stack. Key specifies the tag key and Value specifies the tag value.
  • Extraction rule:
    Original parameter in the .tf file Extracted parameter in the Parameters section
    type Type. The following rules apply:
    • If the type parameter is set to any or is empty, the Type parameter is defined based on the default value of the type parameter:
      • If no default value is defined or the default value is null, the Type parameter is defined as String.
      • If the default value is of the string type, the Type parameter is defined as String.
      • If the default value is of the number type, the Type parameter is defined as Number.
      • If the default value is of the bool type, the Type parameter is defined as Boolean.
      • If the default value is of a type other than the preceding types, the Type parameter is defined as Json.
      Important
      • We recommend that you define the type parameter in case the default type (string) is not your expected type.
      • If the type parameter is empty and the default value is of the number type, Terraform identifies the default value of the type parameter as a string and ROS defines the Type parameter as String.
        variable "i" {
          default = 1      // Terraform identifies the default value 1 as the string "1", and ROS defines the Type parameter as String. 
        }
        variable "f" {
          default = 1.1    // Terraform identifies the default value 1.1 as the string "1.1", and ROS defines the Type parameter as String. 
        }
        
        variable "l" {
          default = [1.1]  // Terraform identifies the default value [1.1] as the string ["1.1"], and ROS defines the Type parameter as Json. 
        }
    • If the type parameter is set to string, the Type parameter is defined as String.
    • If the type parameter is set to number, the Type parameter is defined as Number.
    • If the type parameter is set to bool, the Type parameter is defined as Boolean.
    • If the type parameter is set to a type other than the preceding types, the Type parameter is defined as Json.
    default Default
    sensitive NoEcho
    description
    • If the description parameter is not set to a JSON string, the Description parameter is generated.
    • If the description parameter is set to a JSON string, the description content must follow the same syntax as the Parameters section of the ROS template. The following rules apply:
      • Only valid parameters are supported.
      • If the NoEcho parameter is defined, the sensitive parameter is not required. If the NoEcho parameter is empty, the sensitive parameter is required.
      • If the Default parameter is defined, the default parameter is not required. If the Default parameter is empty, the default parameter is required.
      • If the Type parameter is defined, the value of the Type parameter must be the same as the value of the type parameter. For more information, see Constraints between parameter types in the Parameters section and the .tf file.
  • Sample code of extracted parameters:
    Parameters:
      subnet_mask:
        Description:
          en: Subnet mask of VSwitch
           
        Label:
          en: Subnet mask
           
        MaxValue: 31
        MinValue: 13
        Default: 21
        Type: Number
      zone_id:
        AssociationProperty: 'ALIYUN::ECS::Instance::ZoneId'
        Description:
          en: Zone of VSwitch
           
        Label:
          en: Zone
           
        Type: String
      vpc_name:
        Default: tf_test
        Description: the name of the VPC
        Type: String

(Optional) Outputs

The output items of a Terraform template follow the same syntax as the output items of an ROS template.

Before you configure the Outputs section, take note of the following items:

  • The output items in the Outputs section must be defined in the .tf file, but the output items in the .tf file may not be defined in the Outputs section.
    • If the output items that are defined in the .tf file are not defined in the Outputs section, ROS automatically extracts the output items from the .tf file and generates definitions in the Outputs section.
    • If the output items that are defined in the .tf file are defined in the Outputs section, ROS does not extract the output items from the .tf file, and uses the definitions in the Outputs section.
  • The Condition parameter is not supported in the Outputs section.
  • We recommend that you set the Value parameter to null to return the output items of the Terraform template.

You can extract the output items of a Terraform template based on your business requirements. If the output items that are defined in the .tf file are not defined in the Outputs section, ROS automatically extracts the output items from the .tf file and generates definitions in the Outputs section.

  • Extraction rule:
    • Names of output items: The names of the output items remain unchanged.
    • description parameter:
      • If the description parameter is not set to a JSON string, the Description parameter is generated in the Outputs section.
      • If the description parameter is set to a JSON string, the description content must follow the same syntax as the Outputs section of the ROS template. Only the Description and Label parameters can be generated in the Outputs section.
  • Sample code of extracted output items:
    Outputs:
      vpc_id:
        Value: null
        Description:
          en: VPC ID
           
      vsw_id:
        Value: null
        Description:
          en: VSwitch ID
           

(Optional) Metadata

For more information about how to configure the Metadata section, see Metadata.

Note If you want to use the Metadata section only in the ROS console, you can add a .metadata file in the Workspace section.

(Optional) Mappings

For more information about the Mappings section, see Mappings.

Note If you add a .mappings file to the Workspace section and the file content is in the valid JSON dictionary format, ROS uses the file content to overwrite the configurations in the Mappings section.

(Optional) Conditions

For more information about the Conditions section, see Conditions.

Note If you add a .conditions file to the Workspace section and the file content is in the valid JSON dictionary format, ROS uses the file content to overwrite the configurations in the Conditions section.

(Optional) Rules

For more information about the Rules section, see Rules.

Note If you add a .rules file to the Workspace section and the file content is in the valid JSON dictionary format, ROS uses the file content to overwrite the configurations in the Rules section.