Resource Orchestration Service:Structure of Terraform templates

Estrutura

Um modelo do Terraform é composto por 10 seções. O código de exemplo a seguir mostra a estrutura do modelo:

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}"
    }

(Obrigatório) ROSTemplateFormatVersion

A versão do formato do modelo do Terraform do ROS. Defina o valor como 2015-09-01.

(Obrigatório) Transform

A versão do Terraform compatível com o ROS. Valores válidos:

• Aliyun::Terraform-v0.12: versão 0.12 do Terraform

• Aliyun::Terraform-v0.15: versão 0.15 do Terraform

• Aliyun::Terraform-v1.0: versão 1.0 do Terraform

• Aliyun::Terraform-v1.1: versão 1.1 do Terraform

• Aliyun::Terraform-v1.2: versão 1.2 do Terraform

• Aliyun::Terraform-v1.3: versão 1.3 do Terraform

• Aliyun::Terraform-v1.4: versão 1.4 do Terraform

• Aliyun::Terraform-v1.5: versão 1.5 do Terraform

• Aliyun::OpenTofu-v1.6: versão 1.6 do OpenTofu

• Aliyun::OpenTofu-v1.7: versão 1.7 do OpenTofu

• Aliyun::OpenTofu-v1.8: versão 1.8 do OpenTofu

Antes de configure a seção Transform, atente-se aos seguintes pontos:

• Quando uma nova versão principal ou secundária do Terraform é lançada, o ROS inclui o novo número de versão como um valor válido do parâmetro Transform.

• Alterações nas versões de patch do Terraform não afetam os valores válidos do parâmetro Transform.

• Ao continuar a crie de uma stack ou ao atualize, você pode alterar o valor do parâmetro Transform. Os valores original e novo do parâmetro Transform devem atender às condições na tabela a seguir. As versões 1.x do Terraform são compatíveis entre si e podem ser usadas como substitutas umas das outras.

  Valor original	Novo valor
  Aliyun::Terraform-v1.0	Aliyun::Terraform-v1.1 ou Aliyun::Terraform-v1.2
  Aliyun::Terraform-v1.1	Aliyun::Terraform-v1.0 ou Aliyun::Terraform-v1.2
  Aliyun::Terraform-v1.2	Aliyun::Terraform-v1.0 ou Aliyun::Terraform-v1.1

  Nota

  Use o parâmetro UpdateAllowedTransforms na operação GetFeatureDetails para consultar as versões do Transform que podem ser atualizadas no ROS.

(Obrigatório) Workspace

Os pares de chave-valor de todos os módulos em um workspace do Terraform. Em um par de chave-valor, a chave é o caminho de um arquivo de módulo e o valor é o conteúdo do arquivo de módulo.

Antes de configure a seção Workspace, atente-se aos seguintes pontos:

• A seção Workspace pode conter até 50 arquivos e não pode estar vazia.

• Caminho do arquivo

  • O caminho do arquivo pode ter até 1.024 caracteres. O nome de uma pasta ou de um arquivo no caminho pode ter até 255 caracteres.

  • O caminho do arquivo deve ser relativo e não pode começar com barra (/) nem terminar com .json, .tfstate ou .hcl. Se o nome do arquivo .tf terminar com .debug.tf, o ROS ignora o arquivo e não usa o Terraform para orquestrá-lo.

  • O caminho do arquivo pode conter letras, dígitos e os seguintes caracteres especiais: ! " # $ % & ' ( ) * + , - . / : ; <=> ? @ [\] ^ _

  • A profundidade máxima do caminho do arquivo é 5. Por exemplo, a profundidade de main.tf é 1, e a profundidade de modules/vpc/main.tf é 3.

  • O delimitador do caminho do arquivo é a barra (/). O valor entre duas barras não pode estar vazio nem ser definido como . ou ...

• Conteúdo do arquivo

  • Os recursos provisioner, backend e Terraform Cloud não têm suporte.

  • O recurso module source tem suporte. Use apenas módulos fornecidos pelo alibaba cloud ou módulos locais. Ao usar um módulo local, apenas os dados na seção Workspace podem ser referenciados de forma relativa como a source do módulo. O conteúdo do arquivo deve começar com um ponto e uma barra (./) e não pode conter cifrões ($) ou sinais de percentual (%). O delimitador do caminho do arquivo é a barra (/). O valor entre duas barras não pode estar vazio nem ser definido como . ou ...

  • O recurso Provider tem suporte.

    Substitua as variáveis no código de exemplo a seguir pelas informações reais que deseja usar e remova os sinais de menor e maior que (< >). A seção a seguir lista os valores válidos de cada variável:

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

    • <host>: registry.terraform.io. Você também pode deixar essa variável vazia.

    • <namespace>: hashicorp, aliyun e fortinetdev. Você também pode deixar essa variável vazia.

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

  • Itens de configuração específicos do recurso Provider são restritos ou proibidos. A seção a seguir lista esses itens.

    • Itens de configuração restritos:

      • alicloud: shared_credentials_file

      • aws: assume_role_with_web_identity.web_identity_token_file e custom_ca_bundle

      • azurerm: client_id_file_path, client_certificate_path, client_secret_file_path e oidc_token_file_path

      • fortios: cabundlefile e fmg_cabundlefile

      • fortimanager: cabundlefile

      • helm: kubernetes.config_path

      • kubernetes: config_path

        Nota

        Os itens de configuração estão sujeitos às seguintes regras:

        • O valor deve ser uma string de linha única. Por exemplo, não pode ser uma referência a uma variável.

        • Ao separar variáveis com barras (/), certifique-se de que cada variável contenha apenas letras, dígitos, hyphens (-), underscores (_), and periods (.). A variável não pode estar vazia nem ser definida como . ou ...

        • Se a primeira variável não estiver em conformidade com a regra anterior após a separação das variáveis com barras (/), certifique-se de que ela seja ., ${path.module}, ${path.root}, ${path.cwd} ou ${terraform.workspace}.

    • Itens de configuração proibidos:

      • aws: shared_config_files e shared_credentials_files

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

      • kubernetes: config_paths e exec

  • Os resources e data sources do recurso Provider têm suporte. No entanto, o terraform_remote_state data source, o template.template_file data source e o template.template_dir resource não têm suporte.

  • Algumas propriedades de resources ou data sources são restritas. A seção a seguir lista essas propriedades.

    • alicloud_file_crc64_checksum: filename

    • helm_template: repository_key_file, repository_cert_file e repository_ca_file

      Nota

      Os itens de configuração estão sujeitos às seguintes regras:

      • O valor deve ser uma string de linha única. Por exemplo, não pode ser uma referência a uma variável.

      • Ao separar variáveis com barras (/), certifique-se de que cada variável contenha apenas letras, dígitos, hyphens (-), underscores (_), and periods (.). A variável não pode estar vazia nem ser definida como . ou ...

      • Se a primeira variável não estiver em conformidade com a regra anterior após a separação das variáveis com barras (/), certifique-se de que ela seja ., ${path.module}, ${path.root}, ${path.cwd} ou ${terraform.workspace}.

• A função templatefile não tem suporte.

• O parâmetro path nas funções file, fileexists, fileset e filebase64 obedece às seguintes regras:

  • Este parâmetro é obrigatório.

  • O valor deve ser uma string de linha única. Por exemplo, não pode ser uma referência a uma variável.

  • Ao separar variáveis com barras (/), certifique-se de que a primeira variável seja ${path.module}, ${path.root}, ${path.cwd} ou ${terraform.workspace}.

  • Ao separar variáveis com barras (/), cada variável subsequente à primeira pode conter apenas letras, dígitos, hyphens (-), underscores (_), and periods (.), e não pode estar vazia nem ser definida como . ou ...

(Opcional) Description

A descrição do modelo do Terraform.

(Opcional) Parameters

Os parâmetros do modelo do Terraform. Esses parâmetros seguem a mesma sintaxe dos parâmetros de um modelo do ROS. Para mais informações, consulte Parameters.

Antes de configure a seção Parameters, atente-se aos seguintes pontos:

• Os parâmetros na seção Parameters devem ser definidos no arquivo .tf. No entanto, os parâmetros no arquivo .tf não precisam ser definidos na seção Parameters.

  • Se os parâmetros definidos no arquivo .tf não estiverem na seção Parameters, o ROS extrai automaticamente esses parâmetros do arquivo .tf e gera as definições na seção Parameters.

  • Se os parâmetros definidos no arquivo .tf já estiverem na seção Parameters, o ROS não extrai os parâmetros do arquivo .tf e usa as definições da seção Parameters.

• O tipo do parâmetro na seção Parameters deve ser compatível com o tipo do parâmetro correspondente no arquivo .tf.

  Por exemplo, se um tipo de parâmetro na seção Parameters for A e o tipo de parâmetro correspondente no arquivo .tf for B, a tabela a seguir descreve as restrições entre o Tipo de Parâmetro A e o Tipo de Parâmetro B.

  Tabela 1: Restrições entre os tipos de parâmetros na seção Parameters e no arquivo .tf

  Tipo de Parâmetro B no arquivo .tf	Tipo de Parâmetro A na seção Parameters
  any ou vazio	Valores válidos de A quando o tipo do valor padrão no arquivo .tf é C: Valores válidos de A se C não estiver definido ou C for nulo: String, Number, CommaDelimitedList, Json, Boolean, ALIYUN::OOS::Parameter::Value e ALIYUN::OOS::SecretParameter::Value. Valores válidos de A se C for uma string: String, ALIYUN::OOS::Parameter::Value e ALIYUN::OOS::SecretParameter::Value. Se o valor padrão no arquivo .tf puder ser convertido em um número, um valor de Number também é aceito para A. Valores válidos de A se C for um número: Number, String, ALIYUN::OOS::Parameter::Value e ALIYUN::OOS::SecretParameter::Value. Valores válidos de A se C for um booleano: Boolean, String, ALIYUN::OOS::Parameter::Value e ALIYUN::OOS::SecretParameter::Value. Valores válidos de A se C for uma lista (string): Json, CommaDelimitedList, String, ALIYUN::OOS::Parameter::Value e ALIYUN::OOS::SecretParameter::Value. Valores válidos de A se C não for um dos tipos anteriores: Json, String, ALIYUN::OOS::Parameter::Value e ALIYUN::OOS::SecretParameter::Value.
  string	String, ALIYUN::OOS::Parameter::Value ou ALIYUN::OOS::SecretParameter::Value.
  number	Number, String, ALIYUN::OOS::Parameter::Value ou ALIYUN::OOS::SecretParameter::Value.
  bool	Boolean, String, ALIYUN::OOS::Parameter::Value ou ALIYUN::OOS::SecretParameter::Value.
  list (string)	Json, CommaDelimitedList, String, ALIYUN::OOS::Parameter::Value ou ALIYUN::OOS::SecretParameter::Value.
  outros tipos	Json, String, ALIYUN::OOS::Parameter::Value ou ALIYUN::OOS::SecretParameter::Value.

Extraia os parâmetros de um modelo do Terraform com base nos seus requisitos de negócios. Se os parâmetros definidos no arquivo .tf não estiverem na seção Parameters, o ROS extrai automaticamente esses parâmetros do arquivo .tf e gera as definições na seção Parameters.

• Nome do parâmetro: após a extração, os nomes dos parâmetros permanecem inalterados. Exceto pelos pseudoparâmetros integrados, os nomes não podem começar com ALIYUN__.

• Arquivo de passagem de parâmetros: recomendamos o uso de parâmetros do ROS em vez de arquivos .tfvars para passar valores de parâmetros. Os arquivos .tfvars são arquivos de definição de variáveis no Terraform. Se quiser usar arquivos .tfvars, use apenas arquivos .auto.tfvars ou .terraform.tfvars. Atente-se às prioridades dos arquivos .tfvars e dos parâmetros do ROS. A seção a seguir descreve as prioridades em ordem decrescente:

  1. Arquivos .auto.tfvars.

     Recomendamos não usar vários arquivos .auto.tfvars. Caso use, classifique-os em ordem alfabética inversa com base em seus nomes. O primeiro arquivo tem a prioridade mais alta. Por exemplo, o arquivo b.auto.tfvars tem prioridade maior que o arquivo a.auto.tfvars.

  2. Parâmetros do ROS.

  3. Arquivos terraform.tfvars.

• Pseudoparâmetro: defina os seguintes parâmetros no arquivo .tf para usar pseudoparâmetros do ROS. Para mais informações, consulte Pseudo parameters.

  Nome do parâmetro no arquivo .tf	Tipo de parâmetro no arquivo .tf	Nome do pseudoparâmetro no ROS	Descrição
  ALIYUN__StackId	string	ALIYUN::StackId	O ID da stack.
  ALIYUN__StackName	string	ALIYUN::StackName	O nome da stack.
  ALIYUN__TenantId	string	ALIYUN::TenantId	O ID da conta do alibaba cloud.
  ALIYUN__Region	string	ALIYUN::Region	A região onde a stack reside.
  ALIYUN__AccountId	string	ALIYUN::AccountId	O ID da conta do executor.
  ALIYUN__NoValue	string	ALIYUN::NoValue	O valor do parâmetro para o qual ALIYUN::NoValue está configurado é nulo.
  ALIYUN__ResourceGroupId	string	None	O grupo de recursos ao qual a stack pertence.
  ALIYUN__Tags	map(string)	None	As tags adicionadas à stack. Key especifica a chave da tag e Value especifica o valor da tag.

• Regra de extração: a tabela a seguir descreve a regra de extração.

  Parâmetro original no arquivo .tf	Parâmetro extraído na seção Parameters e descrição do parâmetro
  type	Type. As seguintes regras se aplicam: Se o valor do parâmetro type for any ou o parâmetro type for deixado vazio, o ROS define o parâmetro Type com base no valor padrão do parâmetro type: Se nenhum valor padrão estiver definido para o parâmetro type ou o valor padrão do parâmetro type for nulo, o ROS define o parâmetro Type como String. Se o valor padrão do parâmetro type for uma string, o ROS define o parâmetro Type como String. Se o valor padrão do parâmetro type for um número, o ROS define o parâmetro Type como Number. Se o valor padrão do parâmetro type for um booleano, o ROS define o parâmetro Type como Boolean. Se o valor padrão do parâmetro type não for um dos tipos anteriores, o ROS define o parâmetro Type como Json. Importante Recomendamos definir o parâmetro type caso o tipo padrão (string) não seja o tipo esperado. Se o parâmetro type for deixado vazio e o valor padrão do parâmetro type for um número, o Terraform identifica o número como uma string e o ROS define o parâmetro Type como 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. } Se o valor do parâmetro type for uma string, o ROS define o parâmetro Type como String. Se o valor do parâmetro type for um número, o ROS define o parâmetro Type como Number. Se o valor do parâmetro type for um booleano, o ROS define o parâmetro Type como Boolean. Se o valor do parâmetro type não for um dos tipos anteriores, o ROS define o parâmetro Type como Json.
  default	Default.
  sensitive	NoEcho.
  description	Se o valor do parâmetro description não for uma string JSON, o ROS gera o parâmetro Description. Se o valor do parâmetro description for uma string JSON, o valor deve seguir a mesma sintaxe da seção Parameters do modelo do ROS. As seguintes regras se aplicam: Apenas parâmetros válidos têm suporte. Se o parâmetro NoEcho estiver definido, o valor do parâmetro sensitive é ignorado. Se o parâmetro NoEcho estiver vazio, o valor do parâmetro sensitive é usado. Se o parâmetro Default estiver definido, o valor do parâmetro default é ignorado. Se o parâmetro Default estiver vazio, o valor do parâmetro default é usado. Se o parâmetro Type estiver definido, seu valor deve ser igual ao valor do parâmetro type. Para mais informações, consulte Constraints between parameter types in the Parameters section and the .tf file.

• Código de exemplo 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

Os itens de saída do modelo do Terraform. Esses itens seguem a mesma sintaxe dos itens de saída de um modelo do ROS.

Antes de configure a seção Outputs, atente-se aos seguintes pontos:

• Os itens de saída na seção Outputs devem ser definidos no arquivo .tf. No entanto, os itens de saída no arquivo .tf não precisam ser definidos na seção Outputs.

  • Se os itens de saída definidos no arquivo .tf não estiverem na seção Outputs, o ROS extrai automaticamente esses itens do arquivo .tf e gera as definições na seção Outputs.

  • Se os itens de saída definidos no arquivo .tf já estiverem na seção Outputs, o ROS não extrai os itens do arquivo .tf e usa as definições da seção Outputs.

• O parâmetro Condition não tem suporte na seção Outputs.

• Recomendamos definir o parâmetro Value como nulo para retornar os itens de saída do modelo do Terraform.

Extraia os itens de saída de um modelo do Terraform com base nos seus requisitos de negócios. Se os itens de saída definidos no arquivo .tf não estiverem na seção Outputs, o ROS extrai automaticamente esses itens do arquivo .tf e gera as definições na seção Outputs.

• Regra de extração: a tabela a seguir descreve a regra de extração.

  • Nome do item de saída: os nomes dos itens de saída permanecem inalterados.

  • Parâmetro description:

    • Se o valor do parâmetro description não for uma string JSON, o ROS gera o parâmetro Description na seção Outputs.

    • Se o valor do parâmetro description for uma string JSON, ele deve seguir a mesma sintaxe da seção Outputs do modelo do ROS. Se seguir essa sintaxe, o ROS gera os parâmetros Description e Label na seção Outputs.

• Código de exemplo de itens de saída extraídos:

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

(Opcional) Metadata

Os metadados do modelo do Terraform. Para mais informações, consulte Metadata.

Nota

Para usar a seção Metadata apenas no console do ROS, adicione um arquivo .metadata na seção Workspace.

(Opcional) Mappings

Os mapeamentos do modelo do Terraform. Para mais informações, consulte Mappings.

Nota

Se você adicionar o arquivo .mappings à seção Workspace e o conteúdo for um dicionário JSON válido, o ROS usa esse conteúdo para substituir as configurações na seção Mappings.

(Opcional) Conditions

As condições do modelo do Terraform. Para mais informações, consulte Conditions.

Nota

Se você adicionar o arquivo .conditions à seção Workspace e o conteúdo for um dicionário JSON válido, o ROS usa esse conteúdo para substituir as configurações na seção Conditions.

(Opcional) Rules

As regras do modelo do Terraform. Para mais informações, consulte Rules.

Nota

Se você adicionar o arquivo .rules à seção Workspace e o conteúdo for um dicionário JSON válido, o ROS usa esse conteúdo para substituir as configurações na seção Rules.