Resource Orchestration Service (ROS) allows you to use Terraform templates to manage resources. You can use the Terraform templates to orchestrate Alibaba Cloud, AWS, and Azure resources. You can also use these templates to specify resource parameters and configure dependencies between resources.

Template structure

A Terraform template consists of seven parts. The following code shows the template structure.

Note For more information about the Terraform template structure, 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"
      description = "Name of the VPC"
    }
    resource "alicloud_vpc" "vpc" {
      name       = var.vpc_name
      cidr_block = "172.16.0.0/12"
    }
    output "vpc_id" {
      value = "${alicloud_vpc.vpc.id}"
    }

ROSTemplateFormatVersion (Required)

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

Transform (Required)

The Terraform version supported by ROS. Valid values:

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

Before you specify the Transform parameter, take note of the following items:

  • When a new version of Terraform is released, ROS includes the version number as a value of the Transform parameter.
  • Changes to Terraform patch versions do not affect the valid values of the Transform parameter.
  • If the original and changed values of the Transform parameter meet the conditions in the following table, you can modify the Transform parameter when you continue to create stacks in the Creation Failed state or update stacks. Otherwise, the Transform parameter cannot be modified.
    Original value Changed value
    Aliyun::Terraform-v1.0 Aliyun::Terraform-v1.1
    Aliyun::Terraform-v1.1 Aliyun::Terraform-v1.0
    Note You can call the GetFeatureDetails operation to query the versions to which each Transform version can be updated. Such versions are indicated by the UpdateAllowedTransforms parameter.

Workspace (Required)

The key-value pairs of all modules in a Terraform workspace. In a key-value pair, the key is the file path of a module, 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 key-value pairs and cannot be empty.
  • File path
    • A file path can be up to 1,024 characters in length. The name of a folder or file in a path can be up to 255 characters in length.
    • A file path must be a relative path, and cannot start with a forward slash (/) or end with .json, .tfstate, or .hcl. If a .tf file ends with .debug.tf, ROS ignores the file and does not use Terraform to orchestrate the file.
    • A file path can contain letters, digits, and the following special characters: ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~.
    • The maximum depth of a 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, and cannot be only one period (.) or two periods (..).
  • File content
    • Provisioners, backends, and Terraform Cloud are not allowed.
    • Module sources are allowed, but can only be references in the Workspace section. A module source must start with ./. The value between two forward slashes (/) cannot be empty, and cannot be only one period (.) or two periods (..).
    • Providers are allowed within the following constraints:
      • In the following code, <provider> can only be alicloud, aws, azurerm, random, template, time, fortios, fortimanager, helm, or kubernetes.
      • In the following code, <host> can only be registry.terraform.io or can be left undefined.
      • In the following code, <namespace> can only be hashicorp, aliyun, or fortinetdev, or can be left undefined.
      terraform {
          required_providers {
              <provider> = {
                  source = "<host>/<namespace>/<provider>"
                  ...
              }
          }
      }
      
      provider "<provider>" {
          ...
      }
    • Resources and data sources that are contained in providers are allowed. However, the terraform_remote_state data source and the template.template_dir resource are not allowed.
    • The path value for the file, fileexists, fileset, filebase64, and templatefile functions must meet the following requirements:
      • This path value is required.
      • The path value must be a string that is not wrapped and cannot be a reference to a variable.
      • If the path value is separated by forward slashes (/), the first part must be ${path.module}, ${path.root}, ${path.cwd}, or ${terraform.workspace}.
      • If the path value is separated by forward slashes (/), each part except for the first part can contain only letters, digits, and special characters, but cannot be empty, be only one period (.), or be only two periods (..). The following special characters are supported: - _ ..

Description (Optional)

The description of the Terraform template.

Parameters (Optional)

The Parameters section of the Terraform template must have the same syntax as the Parameters section of the 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 a .tf file, but the parameters in the .tf file may not be defined in the Parameters section.
    • If the parameters 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 defined in the .tf file are defined in the Parameters section, ROS does not extract the parameters from the .tf file, and the existing definitions in the Parameters section are used.
  • Parameter types in the Parameters section must be consistent with corresponding parameter types in the .tf file.

    For example, a parameter type in the Parameters section is A, and the corresponding 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 parameter types in the .tf file
    Parameter Type B in the .tf file Parameter Type A in the Parameters section
    Undefined For example, the type of the default value is C in the .tf file. The following rules apply:
    • If C is not defined or the default value is null, A can be String, Number, CommaDelimitedList, Json, Boolean, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.
    • If C is defined as string, A can be String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.
    • If C is defined as number, A can be Number, String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.
    • If C is defined as bool, A can be Boolean, String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.
    • If C is defined as list (string), A can be Json, CommaDelimitedList, String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.
    • If C is defined as a type other than the preceding types, A can be Json, String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.
    string If B is defined as string, A can be String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.
    number If B is defined as number, A can be Number, String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.
    bool If B is defined as bool, A can be Boolean, String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.
    list (string) If B is defined as list (string), A can be Json, CommaDelimitedList, String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.
    Other types If B is defined as a type other than the preceding types, A can be Json, String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.

You can extract the parameters of the Terraform template based on your business requirements. If the parameters 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. Except for built-in pseudo parameters, the parameter names cannot start with ALIYUN__.
  • Parameter passing files: We recommend that you use ROS parameters instead of .tfvars files to pass parameter values. If you want to use .tfvars files, you can use only the .auto.tfvars files or the terraform.tfvars files. Take note of the priorities of .tfvars files and ROS parameters. The following list 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, the files are sorted in reverse alphabetical order of their names. 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 parameters: If the following parameters are defined in the .tf file, you can use ROS pseudo parameters. For more information, see Pseudo parameters.
    Parameter name in the .tf file Parameter type in the .tf file ROS pseudo parameter name
    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
  • The following table describes the extraction rules.
    Parameter in the .tf file before extraction Parameter in the Parameters section after extraction
    type Type. The following rules apply:
    • If the type parameter is not defined, the Type parameter is defined based on the default value:
      • 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 BOOLEAN 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.
      Notice
      • If String is not your expected type, we recommend that you define the type parameter.
      • If the type parameter is not defined and the default value is a number, Terraform treats the number as a string, and therefore ROS defines the Type parameter as String.
        variable "i" {
          default = 1      // Terraform treats the default value 1 as a string: "1", and therefore ROS defines the Type parameter as String. 
        }
        variable "f" {
          default = 1.1    // Terraform treats the default value 1.1 as a string: "1.1", and therefore ROS defines the Type parameter as String. 
        }
        
        variable "l" {
          default = [1.1]  // Terraform treats the default value [1.1] as a string: ["1.1"], and therefore ROS defines the Type parameter as Json. 
        }
    • If the type parameter is defined as string, the Type parameter is defined as String.
    • If the type parameter is defined as number, the Type parameter is defined as Number.
    • If the type parameter is defined as bool, the Type parameter is defined as Boolean.
    • If the type parameter is defined as 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 defined as a JSON string, the Description parameter is generated in the Parameters section.
    • If the description parameter is defined as a JSON string, the description content must have the same syntax as the description content in 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 not defined, the sensitive parameter is required.
      • If the Default parameter is defined, the default parameter is not required. If the Default parameter is not defined, the default parameter is required.
      • If the Type parameter is defined, the setting of the Type parameter must be consistent with that of the type parameter. For more information, see the Table 1 table.
  • Example of parameters after they are extracted:
    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: Name of the VPC
        Type: String

Outputs (Optional)

The Outputs section of the Terraform template must have the same syntax as the Outputs section of the ROS template.

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

  • The outputs in the Outputs section must be defined in a .tf file, but the outputs in the .tf file may not be defined in the Outputs section.
    • If the outputs defined in the .tf file are not defined in the Outputs section, ROS automatically extracts the outputs from the .tf file and generates definitions in the Outputs section.
    • If the outputs defined in the .tf file are defined in the Outputs section, ROS does not extract the outputs from the .tf file, and the existing definitions in the Outputs section are used.
  • The Condition parameter is invalid in the Outputs section.
  • We recommend that you set the Value parameter to null. This way, the outputs of the Terraform template are returned.

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

  • Extraction rules:
    • Output names: The names in the outputs remain unchanged.
    • The description parameter:
      • If the description parameter is not defined as a JSON string, the Description parameter is generated in the Outputs section.
      • If the description parameter is defined as a JSON string, the description content must have the same syntax as the description content in the Outputs section of the ROS template. Only the Description parameter is supported.
  • Example of outputs after they are extracted:
    Outputs:
      vpc_id:
        Value: null
        Description:
          en: VPC ID
           
      vsw_id:
        Value: null
        Description:
          en: VSwitch ID
           

Metadata (Optional)

The template metadata.