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

Template structure

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:  
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":  
        }
      }
      EOT
    }
  modules/vpc/main.tf: |-
    variable "vpc_name" {
      type = string
      default = "tf_test"
      description = "the 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}"
    }

Template description

The following table describes the parameters of the outermost layer of a Terraform template.

Parameter Required Description
ROSTemplateFormatVersion Yes The template version supported by ROS. Valid value: 2015-09-01.
Transform Yes The Terraform version supported by ROS. Valid values:
  • Aliyun::Terraform-v0.12
  • Aliyun::Terraform-v0.15
  • Aliyun::Terraform-v1.0
Note
  • When a new version of Terraform is released, ROS includes the version number as a Transform parameter value.
  • Changes to Terraform patch versions do not affect the values of the Transform parameter.
  • When you create a Terraform template, you can specify values for parameters in the Parameters section. These values cannot be modified after the template is created.
Workspace Yes 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.
Description No The description of the Terraform template.
Parameters No Parameters of the Terraform template must have the same syntax as Parameters of the ROS template. For more information, see Parameters.

Take note of the following limits:

  • 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. For more information, see Extract Terraform template parameters.
    • If the parameters defined in the .tf file are also 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 those in the .tf file.

    For example, if a parameter type in the Parameters section is A, and the corresponding parameter type in the .tf file is B, the following rules are applicable:

    • If B is not defined, A can be String, Number, CommaDelimitedList, JSON, Boolean, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.
    • If B is defined as string, A can be String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.
    • If B is defined as number, A can be Number, String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.
    • If B is defined as bool, A can be Boolean, String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.
    • If B is defined as list (string), A can be CommaDelimitedList, String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.
    • If B is defined as one of the other types, A can be JSON, String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.
Outputs No Outputs of the Terraform template must have the same syntax as that of the Outputs section of the ROS template. For more information, see Outputs.

Take note of the following limits:

  • 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. For more information, see Extract Terraform template outputs.
    • If the outputs defined in the .tf file are also 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 field is invalid in the Outputs section.
  • We recommend that you set the Value field to null. In this case, the outputs of the Terraform template are returned.
Metadata No The template metadata.

For more information about Terraform template syntax, see Terraform Language Documentation.

Extract Terraform template parameters

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 remain unchanged before and after the extraction. Except for built-in pseudo parameters, the parameter names cannot start with ALIYUN__. For more information, see Use ROS pseudo parameters.

Note We recommend that you use ROS parameters instead of .tfvars files to pass parameter values. If you want to use .tfvars files, you can only use 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:

  • .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 higher priority than the file named a.auto.tfvars.

  • ROS parameters
  • terraform.tfvars files

The following table describes the extraction rules.

Field in the .tf file before extraction Field in the Parameters section after extraction
type Type. The following rules are applicable:
  • If type in the .tf file is not defined or is defined as string, Type in the Parameters section is defined as String.
    Notice We recommend that you define type if String is not your expected type.
  • If type in the .tf file is defined as number, Type in the Parameters section is defined as Number.
  • If type in the .tf file is defined as bool, Type in the Parameters section is defined as Boolean.
  • If type in the .tf file is defined as one of the other types, Type in the Parameters section is defined as JSON.
default Default
sensitive NoEcho
description
  • If description in the .tf file is not a JSON string, Description is generated in the Parameters section.
  • If description in the .tf file is a JSON string, the description content must have the same syntax as that of the Parameters section of the ROS template. The following rules are applicable:
    • Only valid fields are supported.
    • If NoEcho is defined, sensitive is not required. If NoEcho is not defined, sensitive is required.
    • If Default is defined, default is not required. If Default is not defined, default is required.
    • If Type is defined, the content of Type must be consistent with that of type. For more information about rules, see Parameter types in the Parameters section must be consistent with those in the .tf file in the Description column of Parameters in the Template structure section.

The following example shows template parameters after the extraction:

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: the name of the VPC
    Type: String

Extract Terraform template outputs

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. The following rules are applicable:

  • Output name: The names in the outputs remain unchanged.
  • description:
    • If description in the .tf file is not a JSON string, Description is generated in the Parameters section.
    • If description in the .tf file is a JSON string, the description content must have the same syntax as that of the Outputs section of the ROS template. Only the Description field is supported.

The following example shows the template outputs after the extraction:

Outputs:
  vpc_id:
    Value: null
    Description:
      en: VPC ID
      zh-cn:  
  vsw_id:
    Value: null
    Description:
      en: VSwitch ID
      zh-cn:  

Use ROS 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

Constraints on Workspace in a template

The Workspace section contains the paths and contents of files within the following constraints:

  • The Workspace section cannot be empty. It can contain up to 50 key-value pairs.
  • File path
    • A file path can be up to 1,024 character in length, and 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.
    • A file path can contain letters, digits, and special characters. Special characters include ! "#$%&'()*+,-./:;<=>?@ [ \ ] ^ _ ` { | } ~.
    • 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 and backends are not allowed. For more information, see Provisioners and Backends.
    • Module sources are allowed, but can only be relative references in a workspace. For more information, see Module Sources. 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, azurm, random, template, time, fortios, or fortimanager.
      • 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 contained in the providers are allowed. However, the terraform_remote_state data source and the template.template_dir resource are not allowed. terraform_remote_state is one of data sources. template.template_dir is one of resources.
    • 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. Special characters include - _ .. Each part cannot be empty, and cannot be only one period (.)or two periods (..).