Resource Orchestration Service:Structure of Terraform templates

Structure

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

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

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.

(Optional) Mappings

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

(Optional) Conditions

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

(Optional) Rules

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