Resource Orchestration Service：Struktur Template Terraform

Struktur

Sebuah template Terraform terdiri dari 10 bagian. Contoh kode berikut menunjukkan struktur template:

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

(Wajib) ROSTemplateFormatVersion

Versi format template ROS Terraform. Atur nilainya menjadi 2015-09-01.

(Wajib) Transform

Versi Terraform yang kompatibel dengan ROS. Nilai valid:

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

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

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

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

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

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

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

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

• Aliyun::OpenTofu-v1.6: Versi OpenTofu 1.6

• Aliyun::OpenTofu-v1.7: Versi OpenTofu 1.7

• Aliyun::OpenTofu-v1.8: Versi OpenTofu 1.8

Sebelum mengonfigurasi bagian Transform, perhatikan hal-hal berikut:

• Ketika versi mayor atau minor baru dari Terraform dirilis, ROS menyertakan nomor versi baru sebagai nilai valid dari parameter Transform.

• Perubahan pada versi patch Terraform tidak memengaruhi nilai valid dari parameter Transform.

• Ketika melanjutkan pembuatan stack atau memperbarui stack, Anda dapat mengubah nilai parameter Transform. Nilai asli dan baru dari parameter Transform harus memenuhi kondisi dalam tabel berikut. Versi Terraform 1.x kompatibel satu sama lain dan dapat digunakan sebagai pengganti satu sama lain.

  Nilai asli	Nilai baru
  Aliyun::Terraform-v1.0	Aliyun::Terraform-v1.1 atau Aliyun::Terraform-v1.2
  Aliyun::Terraform-v1.1	Aliyun::Terraform-v1.0 atau Aliyun::Terraform-v1.2
  Aliyun::Terraform-v1.2	Aliyun::Terraform-v1.0 atau Aliyun::Terraform-v1.1

  Catatan

  Anda dapat menggunakan parameter UpdateAllowedTransforms dalam operasi GetFeatureDetails untuk menanyakan versi Transform yang dapat diperbarui di ROS.

(Wajib) Workspace

Pasangan nilai-kunci dari semua modul dalam ruang kerja Terraform. Dalam pasangan nilai-kunci, kuncinya adalah jalur file modul dan nilainya adalah konten file modul.

Sebelum mengonfigurasi bagian Workspace, perhatikan hal-hal berikut:

• Bagian Workspace dapat berisi hingga 50 file dan tidak boleh kosong.

• Jalur file

  • Jalur file dapat memiliki panjang hingga 1.024 karakter. Nama folder atau file dalam jalur dapat memiliki panjang hingga 255 karakter.

  • Jalur file harus berupa jalur relatif, dan tidak dapat dimulai dengan garis miring (/) atau diakhiri dengan .json, .tfstate, atau .hcl. Jika nama file .tf diakhiri dengan .debug.tf, ROS mengabaikan file tersebut dan tidak menggunakan Terraform untuk mengatur file tersebut.

  • Jalur file dapat berisi huruf, angka, dan karakter khusus berikut: ! " # $ % & ' ( ) * + , - . / : ; <=> ? @ [\] ^ _ ` {|} ~

  • Kedalaman maksimum jalur file adalah 5. Sebagai contoh, kedalaman main.tf adalah 1, dan kedalaman modules/vpc/main.tf adalah 3.

  • Pemisah jalur file adalah garis miring (/) dan nilai antara dua garis miring tidak boleh kosong atau diatur ke . atau ...

• Konten file

  • Fitur provisioner, backend, dan Terraform Cloud tidak didukung.

  • Fitur sumber modul didukung. Anda dapat menggunakan hanya modul yang disediakan oleh Alibaba Cloud atau modul lokal. Saat menggunakan modul lokal, hanya data di bagian Workspace yang dapat dirujuk secara relatif sebagai sumber modul. Konten file harus dimulai dengan titik dan garis miring (./) dan tidak dapat berisi tanda dolar ($) atau tanda persen (%). Pemisah jalur file adalah garis miring (/) dan nilai antara dua garis miring tidak boleh kosong atau diatur ke . atau ...

  • Fitur Provider didukung.

    Anda harus mengganti variabel dalam kode sampel berikut dengan informasi aktual yang ingin Anda gunakan, dan menghapus tanda kurung sudut (< >). Bagian berikut mencantumkan nilai valid untuk setiap variabel:

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

    • <host>: registry.terraform.io. Anda juga dapat membiarkan variabel ini kosong.

    • <namespace>: hashicorp, aliyun, dan fortinetdev. Anda juga dapat membiarkan variabel ini kosong.

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

  • Item konfigurasi spesifik dari fitur Provider dibatasi atau dilarang. Bagian berikut mencantumkan item konfigurasi.

    • Item konfigurasi yang dibatasi:

      • alicloud: shared_credentials_file

      • aws: assume_role_with_web_identity.web_identity_token_file dan custom_ca_bundle

      • azurerm: client_id_file_path, client_certificate_path, client_secret_file_path, dan oidc_token_file_path

      • fortios: cabundlefile dan fmg_cabundlefile

      • fortimanager: cabundlefile

      • helm: kubernetes.config_path

      • kubernetes: config_path

        Catatan

        Item konfigurasi tunduk pada aturan berikut:

        • Nilainya harus berupa string satu baris. Sebagai contoh, nilainya tidak bisa berupa referensi ke variabel.

        • Saat Anda memisahkan variabel dengan garis miring (/), pastikan setiap variabel hanya dapat berisi huruf, angka, tanda hubung (-), garis bawah (_), dan titik (.). Variabel tidak boleh kosong atau diatur ke . atau ...

        • Jika variabel pertama tidak sesuai dengan aturan sebelumnya setelah Anda memisahkan variabel dengan garis miring (/), pastikan variabel pertama adalah ., ${path.module}, ${path.root}, ${path.cwd}, atau ${terraform.workspace}.

    • Item konfigurasi yang dilarang:

      • aws: shared_config_files dan shared_credentials_files

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

      • kubernetes: config_paths dan exec

  • resources dan data sources dari fitur Provider didukung. Namun, terraform_remote_state data source, template.template_file data source, dan template.template_dir resource tidak didukung.

  • Properti spesifik dari resources atau data sources dibatasi. Bagian berikut mencantumkan properti tersebut.

    • alicloud_file_crc64_checksum: filename

    • helm_template: repository_key_file, repository_cert_file, dan repository_ca_file

      Catatan

      Item konfigurasi tunduk pada aturan berikut:

      • Nilainya harus berupa string satu baris. Sebagai contoh, nilainya tidak bisa berupa referensi ke variabel.

      • Saat Anda memisahkan variabel dengan garis miring (/), pastikan setiap variabel hanya dapat berisi huruf, angka, tanda hubung (-), garis bawah (_), dan titik (.). Variabel tidak boleh kosong atau diatur ke . atau ...

      • Jika variabel pertama tidak sesuai dengan aturan sebelumnya setelah Anda memisahkan variabel dengan garis miring (/), pastikan variabel pertama adalah ., ${path.module}, ${path.root}, ${path.cwd}, atau ${terraform.workspace}.

• Fungsi templatefile tidak didukung.

• Parameter path dalam fungsi file, fileexists, fileset, dan filebase64 tunduk pada aturan berikut:

  • Parameter ini wajib.

  • Nilainya harus berupa string satu baris. Sebagai contoh, nilainya tidak bisa berupa referensi ke variabel.

  • Saat Anda memisahkan variabel dengan garis miring (/), pastikan variabel pertama adalah ${path.module}, ${path.root}, ${path.cwd}, atau ${terraform.workspace}.

  • Saat Anda memisahkan variabel dengan garis miring (/), setiap variabel yang mengikuti variabel pertama hanya dapat berisi huruf, angka, tanda hubung (-), garis bawah (_), dan titik (.), dan tidak boleh kosong atau diatur ke . atau ...

(Opsional) Deskripsi

Deskripsi template Terraform.

(Opsional) Parameter

Parameter template Terraform. Parameter template Terraform mengikuti sintaks yang sama dengan parameter template ROS. Untuk informasi lebih lanjut, lihat Ikhtisar.

Sebelum mengonfigurasi bagian Parameter, perhatikan hal-hal berikut:

• Parameter dalam bagian Parameter harus didefinisikan dalam file .tf. Parameter dalam file .tf tidak perlu didefinisikan dalam bagian Parameter.

  • Jika parameter yang didefinisikan dalam file .tf tidak didefinisikan dalam bagian Parameter, ROS secara otomatis mengekstrak parameter dari file .tf dan menghasilkan definisi dalam bagian Parameter.

  • Jika parameter yang didefinisikan dalam file .tf sudah didefinisikan dalam bagian Parameter, ROS tidak mengekstrak parameter dari file .tf dan menggunakan definisi dalam bagian Parameter.

• Tipe parameter dalam bagian Parameter harus konsisten dengan tipe parameter yang relevan dalam file .tf.

  Sebagai contoh, tipe parameter dalam bagian Parameter adalah A, dan tipe parameter yang relevan dalam file .tf adalah B. Tabel berikut menjelaskan batasan antara Tipe Parameter A dan Tipe Parameter B.

  Tabel 1: Batasan antara tipe parameter dalam bagian Parameter dan file .tf

  Tipe Parameter B dalam file .tf	Tipe Parameter A dalam bagian Parameter
  any atau kosong	Nilai valid A saat tipe nilai default dalam file .tf adalah C: Nilai valid A jika C tidak didefinisikan atau C adalah null: String, Number, CommaDelimitedList, Json, Boolean, ALIYUN::OOS::Parameter::Value, dan ALIYUN::OOS::SecretParameter::Value. Nilai valid A jika C adalah string: String, ALIYUN::OOS::Parameter::Value, dan ALIYUN::OOS::SecretParameter::Value. Jika nilai default dalam file .tf dapat dikonversi menjadi angka, nilai Number juga didukung untuk A. Nilai valid A jika C adalah angka: Number, String, ALIYUN::OOS::Parameter::Value, dan ALIYUN::OOS::SecretParameter::Value. Nilai valid A jika C adalah boolean: Boolean, String, ALIYUN::OOS::Parameter::Value, dan ALIYUN::OOS::SecretParameter::Value. Nilai valid A jika C adalah daftar (string): Json, CommaDelimitedList, String, ALIYUN::OOS::Parameter::Value, dan ALIYUN::OOS::SecretParameter::Value. Nilai valid A jika C bukan salah satu tipe sebelumnya: Json, String, ALIYUN::OOS::Parameter::Value, dan ALIYUN::OOS::SecretParameter::Value.
  string	String, ALIYUN::OOS::Parameter::Value, atau ALIYUN::OOS::SecretParameter::Value.
  number	Number, String, ALIYUN::OOS::Parameter::Value, atau ALIYUN::OOS::SecretParameter::Value.
  bool	Boolean, String, ALIYUN::OOS::Parameter::Value, atau ALIYUN::OOS::SecretParameter::Value.
  list (string)	Json, CommaDelimitedList, String, ALIYUN::OOS::Parameter::Value, atau ALIYUN::OOS::SecretParameter::Value.
  tipe lainnya	Json, String, ALIYUN::OOS::Parameter::Value, atau ALIYUN::OOS::SecretParameter::Value.

Anda dapat mengekstrak parameter template Terraform berdasarkan kebutuhan bisnis Anda. Jika parameter yang didefinisikan dalam file .tf tidak didefinisikan dalam bagian Parameter, ROS secara otomatis mengekstrak parameter dari file .tf dan menghasilkan definisi dalam bagian Parameter.

• Nama parameter: Setelah parameter diekstrak, nama parameter tetap tidak berubah. Nama parameter, kecuali parameter semu bawaan, tidak boleh dimulai dengan ALIYUN__.

• File pengoperan parameter: Kami merekomendasikan Anda menggunakan parameter ROS daripada file .tfvars untuk meneruskan nilai parameter. File .tfvars adalah file definisi variabel di Terraform. Jika Anda ingin menggunakan file .tfvars, Anda hanya dapat menggunakan file .auto.tfvars atau file .terraform.tfvars. Anda harus memperhatikan prioritas file .tfvars dan parameter ROS. Bagian berikut menjelaskan prioritas dalam urutan menurun:

  1. File .auto.tfvars.

     Kami merekomendasikan agar Anda tidak menggunakan beberapa file .auto.tfvars. Jika Anda menggunakan beberapa file .auto.tfvars, urutkan file tersebut secara alfabetis terbalik berdasarkan nama file. File pertama memiliki prioritas tertinggi. Sebagai contoh, file bernama b.auto.tfvars memiliki prioritas lebih tinggi daripada file bernama a.auto.tfvars.

  2. Parameter ROS.

  3. File terraform.tfvars.

• Parameter semu: Anda dapat mendefinisikan parameter berikut dalam file .tf untuk menggunakan parameter semu ROS. Untuk informasi lebih lanjut, lihat Parameter semu.

  Nama parameter dalam file .tf	Tipe parameter dalam file .tf	Nama parameter semu di ROS	Deskripsi
  ALIYUN__StackId	string	ALIYUN::StackId	ID stack.
  ALIYUN__StackName	string	ALIYUN::StackName	Nama stack.
  ALIYUN__TenantId	string	ALIYUN::TenantId	ID akun Alibaba Cloud.
  ALIYUN__Region	string	ALIYUN::Region	Wilayah tempat stack berada.
  ALIYUN__AccountId	string	ALIYUN::AccountId	ID akun eksekutor.
  ALIYUN__NoValue	string	ALIYUN::NoValue	Nilai parameter yang dikonfigurasikan ALIYUN::NoValue adalah null.
  ALIYUN__ResourceGroupId	string	Tidak ada	Grup sumber daya tempat stack termasuk.
  ALIYUN__Tags	map(string)	Tidak ada	Tag yang ditambahkan ke stack. Key menentukan kunci tag, dan Value menentukan nilai tag.

• Aturan ekstraksi: Tabel berikut menjelaskan aturan ekstraksi.

  Parameter asli dalam file .tf	Parameter yang diekstrak dalam bagian Parameter dan deskripsi parameter
  type	Type. Aturan berikut berlaku: Jika nilai parameter type adalah any atau parameter type dibiarkan kosong, ROS mendefinisikan parameter Type berdasarkan nilai default parameter type: Jika tidak ada nilai default yang didefinisikan untuk parameter type atau nilai default parameter type adalah null, ROS mendefinisikan parameter Type sebagai String. Jika nilai default parameter type adalah string, ROS mendefinisikan parameter Type sebagai String. Jika nilai default parameter type adalah angka, ROS mendefinisikan parameter Type sebagai Number. Jika nilai default parameter type adalah boolean, ROS mendefinisikan parameter Type sebagai Boolean. Jika nilai default parameter type bukan salah satu tipe sebelumnya, ROS mendefinisikan parameter Type sebagai Json. Penting Kami merekomendasikan Anda mendefinisikan parameter type jika tipe default (string) bukan tipe yang Anda harapkan. Jika parameter type dibiarkan kosong dan nilai default parameter type adalah angka, Terraform mengidentifikasi angka tersebut sebagai string dan ROS mendefinisikan parameter Type sebagai String. variable "i" { default = 1 // Terraform mengidentifikasi nilai default 1 sebagai string "1", dan ROS mendefinisikan parameter Type sebagai String. } variable "f" { default = 1.1 // Terraform mengidentifikasi nilai default 1.1 sebagai string "1.1", dan ROS mendefinisikan parameter Type sebagai String. } variable "l" { default = [1.1] // Terraform mengidentifikasi nilai default [1.1] sebagai string ["1.1"], dan ROS mendefinisikan parameter Type sebagai Json. } Jika nilai parameter type adalah string, ROS mendefinisikan parameter Type sebagai String. Jika nilai parameter type adalah angka, ROS mendefinisikan parameter Type sebagai Number. Jika nilai parameter type adalah boolean, ROS mendefinisikan parameter Type sebagai Boolean. Jika nilai parameter type bukan salah satu tipe sebelumnya, ROS mendefinisikan parameter Type sebagai Json.
  default	Default.
  sensitive	NoEcho.
  description	Jika nilai parameter description bukan string JSON, ROS menghasilkan parameter Description. Jika nilai parameter description adalah string JSON, nilainya harus mengikuti sintaks yang sama dengan bagian Parameter template ROS. Aturan berikut berlaku: Hanya parameter valid yang didukung. Jika parameter NoEcho didefinisikan, nilai parameter sensitive diabaikan. Jika parameter NoEcho dibiarkan kosong, nilai parameter sensitive digunakan. Jika parameter Default didefinisikan, nilai parameter default diabaikan. Jika parameter Default dibiarkan kosong, nilai parameter default digunakan. Jika parameter Type didefinisikan, nilai parameter Type harus sama dengan nilai parameter type. Untuk informasi lebih lanjut, lihat Batasan antara tipe parameter dalam bagian Parameter dan file .tf.

• Contoh kode parameter yang diekstrak:

  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

(Opsional) Outputs

Item keluaran template Terraform. Item keluaran mengikuti sintaks yang sama dengan item keluaran template ROS.

Sebelum mengonfigurasi bagian Outputs, perhatikan hal-hal berikut:

• Item keluaran dalam bagian Outputs harus didefinisikan dalam file .tf. Item keluaran dalam file .tf tidak perlu didefinisikan dalam bagian Outputs.

  • Jika item keluaran yang didefinisikan dalam file .tf tidak didefinisikan dalam bagian Outputs, ROS secara otomatis mengekstrak item keluaran dari file .tf dan menghasilkan definisi dalam bagian Outputs.

  • Jika item keluaran yang didefinisikan dalam file .tf sudah didefinisikan dalam bagian Outputs, ROS tidak mengekstrak item keluaran dari file .tf, dan menggunakan definisi dalam bagian Outputs.

• Parameter Condition tidak didukung dalam bagian Outputs.

• Kami merekomendasikan Anda mengatur parameter Value menjadi null untuk mengembalikan item keluaran template Terraform.

Anda dapat mengekstrak item keluaran template Terraform berdasarkan kebutuhan bisnis Anda. Jika item keluaran yang didefinisikan dalam file .tf tidak didefinisikan dalam bagian Outputs, ROS secara otomatis mengekstrak item keluaran dari file .tf dan menghasilkan definisi dalam bagian Outputs.

• Aturan ekstraksi: Tabel berikut menjelaskan aturan ekstraksi.

  • Nama item keluaran: Nama item keluaran tetap tidak berubah.

  • parameter description:

    • Jika nilai parameter description bukan string JSON, ROS menghasilkan parameter Description dalam bagian Outputs.

    • Jika nilai parameter description adalah string JSON, nilainya harus mengikuti sintaks yang sama dengan bagian Outputs template ROS. Jika nilainya mengikuti sintaks yang sama, ROS menghasilkan parameter Description dan Label dalam bagian Outputs.

• Contoh kode item keluaran yang diekstrak:

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

(Opsional) Metadata

Metadata template Terraform. Untuk informasi lebih lanjut, lihat Metadata.

(Opsional) Mappings

Pemetaan template Terraform. Untuk informasi lebih lanjut, lihat Mappings.

(Opsional) Conditions

Kondisi template Terraform. Untuk informasi lebih lanjut, lihat Conditions.

(Opsional) Rules

Aturan template Terraform. Untuk informasi lebih lanjut, lihat Rules.