All Products
Search
Document Center

Resource Orchestration Service:Structure of Terraform templates

Last Updated:Jan 18, 2024

Terraform is available as a managed service in Resource Orchestration Service (ROS). You can use Terraform templates to orchestrate Alibaba Cloud, Amazon Web Services (AWS), and Microsoft Azure resources. You can define resources and parameters and configure associations between resources in a Terraform template.

Structure

A Terraform template consists of 10 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:
    Value: null
    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 = "VPC name"
    }
    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 format version of the ROS Terraform template. Set the value to 2015-09-01.

(Required) Transform

The Terraform version that is compatible with ROS. Valid values:

  • Aliyun::Terraform-v0.12: Terraform v0.12

  • Aliyun::Terraform-v0.15: Terraform v0.15

  • Aliyun::Terraform-v1.0: Terraform v1.0

  • Aliyun::Terraform-v1.1: Terraform v1.1

  • Aliyun::Terraform-v1.2: Terraform v1.2

  • Aliyun::Terraform-v1.3: Terraform v1.3

  • Aliyun::Terraform-v1.4: Terraform v1.4

  • Aliyun::Terraform-v1.5: Terraform v1.5

Note

HashiCorp announced a transition from Mozilla Public License (MPL) 2.0 to Business Source License (BSL). The latest Terraform version that ROS supports is Terraform v1.5.7, which is the latest Terraform release under MPL 2.0.

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

  • When a new major or minor version of Terraform is released, ROS includes the new version number as a valid value of the Transform parameter.

  • Changes to Terraform patch versions do not affect the valid values of the Transform parameter.

  • When you continue to create a stack or when you update a stack, you can change the value of the Transform parameter. The original and new values of the Transform parameter must meet the conditions in the following table. Terraform v1.x is compatible with each other and can be used to substitute each other.

    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 UpdateAllowedTransforms parameter in the GetFeatureDetails operation to query the Transform versions that can be updated in ROS.

(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 the following special characters: ! " # $ % & ' ( ) * + , - . / : ; <=> ? @ [\] ^ _ ` {|} ~

    • 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 delimiter of the file path is a forward slash (/) and the value between two forward slashes cannot be empty or set to . or ...

  • File content

    • The provisioner, backend, and Terraform Cloud features are not supported.

    • The module source feature is supported. You can use only the modules that are provided by Alibaba Cloud or local modules. When you use a local module, only data in the Workspace section can be relatively referenced as the module source. The file content must start with a period and a forward slash (./) and cannot contain dollar signs ($) or percent signs(%). The delimiter of the file path is a forward slash (/) and the value between two forward slashes cannot be empty or set to . or ...

    • The Provider feature is supported.

      You must replace the variables in the following sample code with the actual information you want to use, and remove the angle brackets (< >). The following section lists the valid values of each variable:

      • <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>" {
          ...
      }
    • Specific configuration items of the Provider feature are restricted or forbidden. The following section lists the configuration items.

      • Restricted configuration items:

        • alicloud: shared_credentials_file

        • aws: assume_role_with_web_identity.web_identity_token_file and custom_ca_bundle

        • azurerm: client_id_file_path, client_certificate_path, client_secret_file_path, and oidc_token_file_path

        • fortios: cabundlefile and fmg_cabundlefile

        • fortimanager: cabundlefile

        • helm: kubernetes.config_path

        • kubernetes: config_path

          Note

          The configuration items are subject to the following rules:

          • The value must be a single-line string. For example, the value cannot be a reference to a variable.

          • When you separate variables with forward slashes (/), make sure that each variable can contain only letters, digits, hyphens (-), underscores (_), and periods (.). The variable cannot be empty or set to . or ...

          • If the first variable does not conform with the preceding rule after you separate the variables with forward slashes (/), make sure that the first variable is ., ${path.module}, ${path.root}, ${path.cwd}, or ${terraform.workspace}.

      • Prohibited configuration items:

        • aws: shared_config_files and shared_credentials_files

        • helm: plugins_path, registry_config_path, repository_config_path, repository_cache, kubernetes.config_paths, and kubernetes.exec

        • kubernetes: config_paths and exec

    • The resources and data sources of the Provider feature are supported. However, the terraform_remote_state data source, template.template_file data source, and template.template_dir resource are not supported.

    • Specific properties of resources or data sources are restricted. The following section lists the properties.

      • alicloud_file_crc64_checksum: filename

      • helm_template: repository_key_file, repository_cert_file, and repository_ca_file

        Note

        The configuration items are subject to the following rules:

        • The value must be a single-line string. For example, the value cannot be a reference to a variable.

        • When you separate variables with forward slashes (/), make sure that each variable can contain only letters, digits, hyphens (-), underscores (_), and periods (.). The variable cannot be empty or set to . or ...

        • If the first variable does not conform with the preceding rule after you separate the variables with forward slashes (/), make sure that the first variable is ., ${path.module}, ${path.root}, ${path.cwd}, or ${terraform.workspace}.

  • The templatefile function is not supported.

  • The path parameter in the file, fileexists, fileset, and filebase64 functions is subject to the following rules:

    • 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 with forward slashes (/), make sure that the first variable is ${path.module}, ${path.root}, ${path.cwd}, or ${terraform.workspace}.

    • When you separate variables with forward slashes (/), each variable that follows the first variable can contain only letters, digits, hyphens (-), underscores (_), and periods (.), and cannot be empty or set to . or ...

(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 a 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. The parameters in the .tf file do not need to 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 already defined in the Parameters section, ROS does not extract the parameters from the .tf file and uses the definitions in the Parameters section.

  • The type of the parameter in the Parameters section must be consistent with the type of the relevant parameter 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 when the type of the default value in the .tf file is C:

    • Valid values of A if C is not defined or C is null: String, Number, CommaDelimitedList, Json, Boolean, ALIYUN::OOS::Parameter::Value, and ALIYUN::OOS::SecretParameter::Value.

    • Valid values of A if C is a string: String, ALIYUN::OOS::Parameter::Value, and ALIYUN::OOS::SecretParameter::Value. If the default value in the .tf file can be converted to a number, a value of Number is also supported for A.

    • Valid values of A if C is a number: Number, String, ALIYUN::OOS::Parameter::Value, and ALIYUN::OOS::SecretParameter::Value.

    • Valid values of A if C is a boolean: Boolean, String, ALIYUN::OOS::Parameter::Value, and ALIYUN::OOS::SecretParameter::Value.

    • Valid values of A if C is a list (string): Json, CommaDelimitedList, String, ALIYUN::OOS::Parameter::Value, and ALIYUN::OOS::SecretParameter::Value.

    • Valid values of A if C is not one of the preceding types: Json, String, ALIYUN::OOS::Parameter::Value, and ALIYUN::OOS::SecretParameter::Value.

    string

    String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.

    number

    Number, String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.

    bool

    Boolean, String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.

    list (string)

    Json, CommaDelimitedList, String, ALIYUN::OOS::Parameter::Value, or ALIYUN::OOS::SecretParameter::Value.

    other types

    Json, String, ALIYUN::OOS::Parameter::Value, or 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 name: After parameters are extracted, the names of the parameters remain unchanged. 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, 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 stack ID.

    ALIYUN__StackName

    string

    ALIYUN::StackName

    The stack name.

    ALIYUN__TenantId

    string

    ALIYUN::TenantId

    The ID of the Alibaba Cloud account.

    ALIYUN__Region

    string

    ALIYUN::Region

    The region where the stack resides.

    ALIYUN__AccountId

    string

    ALIYUN::AccountId

    The ID of the executor account.

    ALIYUN__NoValue

    string

    ALIYUN::NoValue

    The value of the parameter for which ALIYUN::NoValue is configured is null.

    ALIYUN__ResourceGroupId

    string

    None

    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: The following table describes the extraction rule.

    Original parameter in the .tf file

    Extracted parameter in the Parameters section and parameter description

    type

    Type. The following rules apply:

    • If the value of the type parameter is any or the type parameter is left empty, ROS defines the Type parameter based on the default value of the type parameter:

      • If no default value is defined for the type parameter or the default value of the type parameter is null, ROS defines the Type parameter as String.

      • If the default value of the type parameter is a string, ROS defines the Type parameter as String.

      • If the default value of the type parameter is a number, ROS defines the Type parameter as Number.

      • If the default value of the type parameter is a boolean, ROS defines the Type parameter as Boolean.

      • If the default value of the type parameter is not one of the preceding types, ROS defines the Type parameter 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 left empty and the default value of the type parameter is a number, Terraform identifies the number 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 value of the type parameter is a string, ROS defines the Type parameter as String.

    • If the value of the type parameter is a number, ROS defines the Type parameter as Number.

    • If the value of the type parameter is a boolean, ROS defines the Type parameter as Boolean.

    • If the value of the type parameter is not one of the preceding types, ROS defines the Type parameter as Json.

    default

    Default.

    sensitive

    NoEcho.

    description

    • If the value of the description parameter is not a JSON string, ROS generates the Description parameter.

    • If the value of the description parameter is a JSON string, the value 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 value of the sensitive parameter is ignored. If the NoEcho parameter is left empty, the value of the sensitive parameter is used.

      • If the Default parameter is defined, the value of the default parameter is ignored. If the Default parameter is left empty, the value of the default parameter is used.

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

(Optional) Outputs

The output items of the Terraform template. The output items follow the same syntax as the output items of a 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. The output items in the .tf file do not need to 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 already 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: The following table describes the extraction rule.

    • Output item name: The names of the output items remain unchanged.

    • description parameter:

      • If the value of the description parameter is not a JSON string, ROS generates the Description parameter in the Outputs section.

      • If the value of the description parameter is a JSON string, the value must follow the same syntax as the Outputs section of the ROS template. If the value follow the same syntax, ROS generates the Description and Label parameters 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

The metadata of the Terraform template. For more information, 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

The mappings of the Terraform template. For more information, see Mappings.

Note

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

(Optional) Conditions

The conditions of the Terraform template. For more information, see Conditions.

Note

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

(Optional) Rules

The rules of the Terraform template. For more information, see Rules.

Note

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