Resource Orchestration Service:Structure of Terraform templates

Estructura

Una plantilla de Terraform consta de 10 secciones. El siguiente código de ejemplo muestra la estructura de la plantilla:

ROSTemplateFormatVersion: '2015-09-01'
Transform: 'Aliyun::Terraform-v1.5'
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}"
    }

(Obligatorio) ROSTemplateFormatVersion

Versión del formato de la plantilla de Terraform para ROS. Establezca el valor en 2015-09-01.

(Obligatorio) Transform

Versión de Terraform compatible con ROS. Valores válidos:

• Aliyun::Terraform-v0.12: Terraform versión 0.12

• Aliyun::Terraform-v0.15: Terraform versión 0.15

• Aliyun::Terraform-v1.0: Terraform versión 1.0

• Aliyun::Terraform-v1.1: Terraform versión 1.1

• Aliyun::Terraform-v1.2: Terraform versión 1.2

• Aliyun::Terraform-v1.3: Terraform versión 1.3

• Aliyun::Terraform-v1.4: Terraform versión 1.4

• Aliyun::Terraform-v1.5: Terraform versión 1.5

• Aliyun::OpenTofu-v1.6: OpenTofu versión 1.6

• Aliyun::OpenTofu-v1.7: OpenTofu versión 1.7

• Aliyun::OpenTofu-v1.8: OpenTofu versión 1.8

Antes de configurar la sección Transform, tenga en cuenta lo siguiente:

• Cuando se publica una nueva versión principal o secundaria de Terraform, ROS incluye el nuevo número de versión como un valor válido del parámetro Transform.

• Los cambios en las versiones de parche de Terraform no afectan los valores válidos del parámetro Transform.

• Al continuar con la creación de una pila o al actualizarla, puede modificar el valor del parámetro Transform. Los valores original y nuevo deben cumplir las condiciones de la siguiente tabla. Las versiones 1.x de Terraform son compatibles entre sí y pueden sustituirse mutuamente.

  Valor original	Nuevo valor
  Aliyun::Terraform-v1.0	Aliyun::Terraform-v1.1 o Aliyun::Terraform-v1.2
  Aliyun::Terraform-v1.1	Aliyun::Terraform-v1.0 o Aliyun::Terraform-v1.2
  Aliyun::Terraform-v1.2	Aliyun::Terraform-v1.0 o Aliyun::Terraform-v1.1

  Nota

  Puede utilizar el parámetro UpdateAllowedTransforms en la operación GetFeatureDetails para consultar las versiones de Transform que se pueden actualizar en ROS.

(Obligatorio) Workspace

Pares clave-valor de todos los módulos en un workspace de Terraform. En cada par, la clave representa la ruta de un archivo de módulo y el valor corresponde al contenido de dicho archivo.

Antes de configurar la sección Workspace, considere los siguientes puntos:

• La sección Workspace puede contener hasta 50 archivos y no puede estar vacía.

• Ruta del archivo

  • La ruta del archivo puede tener una longitud máxima de 1,024 caracteres. El nombre de una carpeta o archivo dentro de la ruta no debe exceder los 255 caracteres.

  • La ruta debe ser relativa; no puede comenzar con una barra diagonal (/) ni terminar con .json, .tfstate o .hcl. Si el nombre del archivo .tf termina en .debug.tf, ROS lo ignora y no utiliza Terraform para orquestarlo.

  • La ruta del archivo puede contener letras, dígitos y los siguientes caracteres especiales: ! " # $ % & ' ( ) * + , - . / : ; <=> ? @ [\] ^ _

  • La profundidad máxima de la ruta del archivo es 5. Por ejemplo, la profundidad de main.tf es 1, mientras que la de modules/vpc/main.tf es 3.

  • El delimitador de la ruta del archivo es la barra diagonal (/). El valor entre dos barras diagonales no puede estar vacío ni ser . o ...

• Contenido del archivo

  • Las funciones provisioner, backend y Terraform Cloud no son compatibles.

  • La función module source es compatible. Solo puede usar módulos proporcionados por Alibaba Cloud o módulos locales. Al emplear un módulo local, únicamente se pueden hacer referencias relativas a datos dentro de la sección Workspace como origen del módulo. El contenido del archivo debe comenzar con un punto y una barra diagonal (./) y no puede contener signos de dólar ($) ni signos de porcentaje (%). El delimitador de la ruta del archivo es la barra diagonal (/) y el valor entre dos barras diagonales no puede estar vacío ni ser . o ...

  • La función Provider es compatible.

    Debe reemplazar las variables del siguiente código de ejemplo con la información real que desea utilizar y eliminar los corchetes angulares (< >). A continuación se listan los valores válidos para cada variable:

    • <provider>: alicloud, aws, azurerm, random, template, time, fortios, fortimanager, helm y kubernetes.

    • <host>: registry.terraform.io. También puede dejar esta variable vacía.

    • <namespace>: hashicorp, aliyun y fortinetdev. También puede dejar esta variable vacía.

    terraform {
        required_providers {
            <provider> = {
                source = "<host>/<namespace>/<provider>"
                ...
            }
        }
    }
    
    provider "<provider>" {
        ...
    }

  • Ciertos elementos de configuración de la función Provider están restringidos o prohibidos. A continuación se detallan estos elementos.

    • Elementos de configuración restringidos:

      • alicloud: shared_credentials_file

      • aws: assume_role_with_web_identity.web_identity_token_file y custom_ca_bundle

      • azurerm: client_id_file_path, client_certificate_path, client_secret_file_path y oidc_token_file_path

      • fortios: cabundlefile y fmg_cabundlefile

      • fortimanager: cabundlefile

      • helm: kubernetes.config_path

      • kubernetes: config_path

        Nota

        Estos elementos de configuración están sujetos a las siguientes reglas:

        • El valor debe ser una cadena de una sola línea. Por ejemplo, no puede ser una referencia a una variable.

        • Al separar variables con barras diagonales (/), asegúrese de que cada variable contenga solo letras, dígitos, guiones (-), guiones bajos (_) y puntos (.). La variable no puede estar vacía ni ser . o ...

        • Si la primera variable no cumple con la regla anterior después de separarlas con barras diagonales (/), asegúrese de que dicha variable sea ., ${path.module}, ${path.root}, ${path.cwd} o ${terraform.workspace}.

    • Elementos de configuración prohibidos:

      • aws: shared_config_files y shared_credentials_files

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

      • kubernetes: config_paths y exec

  • Se admiten los resources y data sources de la función Provider. Sin embargo, no son compatibles el terraform_remote_state data source, template.template_file data source ni el template.template_dir resource.

  • Ciertas propiedades de resources o data sources tienen restricciones. A continuación se enumeran dichas propiedades.

    • alicloud_file_crc64_checksum: filename

    • helm_template: repository_key_file, repository_cert_file y repository_ca_file

      Nota

      Estos elementos de configuración están sujetos a las siguientes reglas:

      • El valor debe ser una cadena de una sola línea. Por ejemplo, no puede ser una referencia a una variable.

      • Al separar variables con barras diagonales (/), asegúrese de que cada variable contenga solo letras, dígitos, guiones (-), guiones bajos (_) y puntos (.). La variable no puede estar vacía ni ser . o ...

      • Si la primera variable no cumple con la regla anterior después de separarlas con barras diagonales (/), asegúrese de que dicha variable sea ., ${path.module}, ${path.root}, ${path.cwd} o ${terraform.workspace}.

• La función templatefile no es compatible.

• El parámetro path en las funciones file, fileexists, fileset y filebase64 está sujeto a las siguientes reglas:

  • Este parámetro es obligatorio.

  • El valor debe ser una cadena de una sola línea. Por ejemplo, no puede ser una referencia a una variable.

  • Al separar variables con barras diagonales (/), asegúrese de que la primera variable sea ${path.module}, ${path.root}, ${path.cwd} o ${terraform.workspace}.

  • Al separar variables con barras diagonales (/), cada variable posterior a la primera solo puede contener letras, dígitos, guiones (-), guiones bajos (_) y puntos (.), y no puede estar vacía ni ser . o ...

(Opcional) Description

Descripción de la plantilla de Terraform.

(Opcional) Parameters

Parámetros de la plantilla de Terraform. Estos siguen la misma sintaxis que los parámetros de una plantilla de ROS. Para obtener más información, consulte Parameters.

Antes de configurar la sección Parameters, tenga en cuenta lo siguiente:

• Los parámetros definidos en la sección Parameters deben estar declarados en el archivo .tf. No obstante, los parámetros del archivo .tf no requieren definición obligatoria en la sección Parameters.

  • Si los parámetros definidos en el archivo .tf no aparecen en la sección Parameters, ROS los extrae automáticamente del archivo .tf y genera sus definiciones en dicha sección.

  • Si los parámetros del archivo .tf ya están definidos en la sección Parameters, ROS no los extrae del archivo .tf y utiliza las definiciones existentes en la sección Parameters.

• El tipo de parámetro en la sección Parameters debe coincidir con el tipo del parámetro correspondiente en el archivo .tf.

  Por ejemplo, si un tipo de parámetro en la sección Parameters es A y el tipo correspondiente en el archivo .tf es B, la siguiente tabla describe las restricciones entre el Tipo de parámetro A y el Tipo de parámetro B.

  Tabla 1: Restricciones entre los tipos de parámetros en la sección Parameters y el archivo .tf

  Tipo de parámetro B en el archivo .tf	Tipo de parámetro A en la sección Parameters
  any o vacío	Valores válidos de A cuando el tipo del valor predeterminado en el archivo .tf es C: Valores válidos de A si C no está definido o es nulo: String, Number, CommaDelimitedList, Json, Boolean, ALIYUN::OOS::Parameter::Value y ALIYUN::OOS::SecretParameter::Value. Valores válidos de A si C es una cadena: String, ALIYUN::OOS::Parameter::Value y ALIYUN::OOS::SecretParameter::Value. Si el valor predeterminado en el archivo .tf se puede convertir a número, también se admite el valor Number para A. Valores válidos de A si C es un número: Number, String, ALIYUN::OOS::Parameter::Value y ALIYUN::OOS::SecretParameter::Value. Valores válidos de A si C es un booleano: Boolean, String, ALIYUN::OOS::Parameter::Value y ALIYUN::OOS::SecretParameter::Value. Valores válidos de A si C es una lista (cadena): Json, CommaDelimitedList, String, ALIYUN::OOS::Parameter::Value y ALIYUN::OOS::SecretParameter::Value. Valores válidos de A si C no es ninguno de los tipos anteriores: Json, String, ALIYUN::OOS::Parameter::Value y ALIYUN::OOS::SecretParameter::Value.
  string	String, ALIYUN::OOS::Parameter::Value o ALIYUN::OOS::SecretParameter::Value.
  number	Number, String, ALIYUN::OOS::Parameter::Value o ALIYUN::OOS::SecretParameter::Value.
  bool	Boolean, String, ALIYUN::OOS::Parameter::Value o ALIYUN::OOS::SecretParameter::Value.
  list (string)	Json, CommaDelimitedList, String, ALIYUN::OOS::Parameter::Value o ALIYUN::OOS::SecretParameter::Value.
  otros tipos	Json, String, ALIYUN::OOS::Parameter::Value o ALIYUN::OOS::SecretParameter::Value.

Puede extraer los parámetros de una plantilla de Terraform según sus necesidades empresariales. Si los parámetros definidos en el archivo .tf no se encuentran en la sección Parameters, ROS los extrae automáticamente del archivo .tf y genera las definiciones correspondientes en la sección Parameters.

• Nombre del parámetro: Tras la extracción, los nombres de los parámetros permanecen sin cambios. Excepto los pseudoparámetros integrados, ningún nombre de parámetro puede comenzar con ALIYUN__.

• Archivo de paso de parámetros: Se recomienda utilizar parámetros de ROS en lugar de archivos .tfvars para pasar valores de parámetros. Los archivos .tfvars son archivos de definición de variables en Terraform. Si desea usarlos, solo puede emplear archivos .auto.tfvars o .terraform.tfvars. Debe considerar las prioridades de los archivos .tfvars frente a los parámetros de ROS. A continuación se describen las prioridades en orden descendente:

  1. Archivos .auto.tfvars.

     Se recomienda no utilizar múltiples archivos .auto.tfvars. Si usa varios, ordénelos alfabéticamente de forma inversa según sus nombres. El primer archivo tiene la mayor prioridad. Por ejemplo, el archivo b.auto.tfvars tiene mayor prioridad que a.auto.tfvars.

  2. Parámetros de ROS.

  3. Archivos terraform.tfvars.

• Pseudoparámetro: Puede definir los siguientes parámetros en el archivo .tf para utilizar pseudoparámetros de ROS. Para obtener más información, consulte Pseudo parameters.

  Nombre del parámetro en el archivo .tf	Tipo de parámetro en el archivo .tf	Nombre del pseudoparámetro en ROS	Descripción
  ALIYUN__StackId	string	ALIYUN::StackId	ID de la pila.
  ALIYUN__StackName	string	ALIYUN::StackName	Nombre de la pila.
  ALIYUN__TenantId	string	ALIYUN::TenantId	ID de la cuenta de Alibaba Cloud.
  ALIYUN__Region	string	ALIYUN::Region	Región donde reside la pila.
  ALIYUN__AccountId	string	ALIYUN::AccountId	ID de la cuenta del ejecutor.
  ALIYUN__NoValue	string	ALIYUN::NoValue	El valor del parámetro configurado como ALIYUN::NoValue es nulo.
  ALIYUN__ResourceGroupId	string	Ninguna	Resource group al que pertenece la pila.
  ALIYUN__Tags	map(string)	Ninguna	Etiquetas agregadas a la pila. Key especifica la clave de la etiqueta y Value especifica el valor de la etiqueta.

• Regla de extracción: La siguiente tabla describe la regla de extracción.

  Parámetro original en el archivo .tf	Parámetro extraído en la sección Parameters y descripción del parámetro
  type	Type. Se aplican las siguientes reglas: Si el valor del parámetro type es any o si el parámetro type se deja vacío, ROS define el parámetro Type basándose en el valor predeterminado del parámetro type: Si no hay valor predeterminado definido para el parámetro type o si este es nulo, ROS define el parámetro Type como String. Si el valor predeterminado del parámetro type es una cadena, ROS define el parámetro Type como String. Si el valor predeterminado del parámetro type es un número, ROS define el parámetro Type como Number. Si el valor predeterminado del parámetro type es un booleano, ROS define el parámetro Type como Boolean. Si el valor predeterminado del parámetro type no es ninguno de los tipos anteriores, ROS define el parámetro Type como Json. Importante Se recomienda definir el parámetro type para evitar que el tipo predeterminado (string) difiera del tipo esperado. Si el parámetro type se deja vacío y su valor predeterminado es un número, Terraform identifica dicho número como una cadena y ROS define el parámetro Type como String. variable "i" { default = 1 // Terraform identifica el valor predeterminado 1 como la cadena "1", y ROS define el parámetro Type como String. } variable "f" { default = 1.1 // Terraform identifica el valor predeterminado 1.1 como la cadena "1.1", y ROS define el parámetro Type como String. } variable "l" { default = [1.1] // Terraform identifica el valor predeterminado [1.1] como la cadena ["1.1"], y ROS define el parámetro Type como Json. } Si el valor del parámetro type es una cadena, ROS define el parámetro Type como String. Si el valor del parámetro type es un número, ROS define el parámetro Type como Number. Si el valor del parámetro type es un booleano, ROS define el parámetro Type como Boolean. Si el valor del parámetro type no es ninguno de los tipos anteriores, ROS define el parámetro Type como Json.
  default	Default.
  sensitive	NoEcho.
  description	Si el valor del parámetro description no es una cadena JSON, ROS genera el parámetro Description. Si el valor del parámetro description es una cadena JSON, el valor debe seguir la misma sintaxis que la sección Parameters de la plantilla de ROS. Se aplican las siguientes reglas: Solo se admiten parámetros válidos. Si se define el parámetro NoEcho, se ignora el valor del parámetro sensitive. Si el parámetro NoEcho se deja vacío, se utiliza el valor del parámetro sensitive. Si se define el parámetro Default, se ignora el valor del parámetro default. Si el parámetro Default se deja vacío, se utiliza el valor del parámetro default. Si se define el parámetro Type, su valor debe coincidir con el valor del parámetro type. Para obtener más información, consulte Constraints between parameter types in the Parameters section and the .tf file.

• Código de ejemplo de parámetros extraídos:

  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

(Opcional) Outputs

Elementos de salida de la plantilla de Terraform. Estos elementos siguen la misma sintaxis que los elementos de salida de una plantilla de ROS.

Antes de configurar la sección Outputs, tenga en cuenta lo siguiente:

• Los elementos de salida en la sección Outputs deben estar definidos en el archivo .tf. Los elementos de salida del archivo .tf no requieren definición obligatoria en la sección Outputs.

  • Si los elementos de salida definidos en el archivo .tf no aparecen en la sección Outputs, ROS los extrae automáticamente del archivo .tf y genera sus definiciones en dicha sección.

  • Si los elementos de salida del archivo .tf ya están definidos en la sección Outputs, ROS no los extrae del archivo .tf y utiliza las definiciones existentes en la sección Outputs.

• El parámetro Condition no es compatible en la sección Outputs.

• Se recomienda establecer el parámetro Value en null para devolver los elementos de salida de la plantilla de Terraform.

Puede extraer los elementos de salida de una plantilla de Terraform según sus necesidades empresariales. Si los elementos de salida definidos en el archivo .tf no se encuentran en la sección Outputs, ROS los extrae automáticamente del archivo .tf y genera las definiciones correspondientes en la sección Outputs.

• Regla de extracción: La siguiente tabla describe la regla de extracción.

  • Nombre del elemento de salida: Los nombres de los elementos de salida permanecen sin cambios.

  • Parámetro description:

    • Si el valor del parámetro description no es una cadena JSON, ROS genera el parámetro Description en la sección Outputs.

    • Si el valor del parámetro description es una cadena JSON, el valor debe seguir la misma sintaxis que la sección Outputs de la plantilla de ROS. Si el valor cumple con esta sintaxis, ROS genera los parámetros Description y Label en la sección Outputs.

• Código de ejemplo de elementos de salida extraídos:

  Outputs:
    vpc_id:
      Value: null
      Description:
        en: VPC ID
         
    vsw_id:
      Value: null
      Description:
        en: VSwitch ID
         

(Opcional) Metadata

Metadatos de la plantilla de Terraform. Para obtener más información, consulte Metadata.

(Opcional) Mappings

Asignaciones de la plantilla de Terraform. Para obtener más información, consulte Mappings.

(Opcional) Conditions

Condiciones de la plantilla de Terraform. Para obtener más información, consulte Conditions.

(Opcional) Rules

Reglas de la plantilla de Terraform. Para obtener más información, consulte Rules.