Variabel - Terraform - Alibaba Cloud Documentation Center

Ikhtisar

Contoh sebelumnya menggunakan nilai yang dikodekan secara langsung (hard-coded) untuk argumen resource. Untuk memparameterisasi konfigurasi Anda, menstandarkan kode, atau menyesuaikan properti resource selama langkah apply, gunakan variabel input.

Variabel input memungkinkan Anda memparameterisasi nilai untuk resource dan memberikan manfaat berikut:

Meningkatkan kemampuan penggunaan ulang

Variabel input berfungsi sebagai parameter untuk konfigurasi Terraform Anda. Dengan memisahkan penugasan atribut dari kode sumber, Anda dapat dengan mudah menyesuaikan dan berbagi konfigurasi yang sama tanpa mengubahnya.
Meningkatkan fleksibilitas

Setelah mendefinisikan sebuah variabel, Anda dapat mengatur nilainya saat runtime (apply) melalui beberapa cara, termasuk variabel lingkungan, opsi CLI, dan file pasangan kunci-nilai. Pada contoh berikut, nama, deskripsi, dan blok CIDR dikodekan secara langsung. Anda dapat mendeklarasikan salah satu argumen ini sebagai variabel dan menentukan nilainya saat runtime.

resource "alicloud_vpc" "my_vpc" {
  vpc_name    = "main-vpc"
  cidr_block  = "10.0.0.0/16"
  description = "my first vpc network"
}

Sintaksis variabel

Anda mendeklarasikan variabel input menggunakan blok variable.

Deklarasikan variabel input dalam blok variable. Kami menyarankan menempatkan semua deklarasi variabel untuk suatu modul dalam satu file bernama variables.tf.

Label yang mengikuti kata kunci variable adalah nama variabel tersebut. Nama variabel harus memenuhi dua aturan berikut:

Bersifat unik dalam satu modul.

Nama variabel harus unik di antara semua variabel dalam modul yang sama. Variabel dalam modul anak dapat memiliki nama yang sama dengan variabel dalam modul induk karena keduanya berada dalam cakupan yang terpisah.
Bukan merupakan kata kunci yang dicadangkan.

Nama variabel tidak boleh merupakan salah satu kata kunci yang dicadangkan oleh Terraform, seperti meta-argumen count dan for_each.

Blok variable dapat kosong karena tidak ada argumen yang wajib diisi. Jika Anda tidak memberikan nilai default, Terraform dapat menginferensi tipe variabel tersebut dari nilai yang Anda berikan saat runtime.

type

Argumen type menentukan tipe nilai apa saja yang diterima untuk variabel tersebut. Terraform mendukung tipe primitif berikut:

bool: Nilai boolean, yaitu true atau false (tanpa tanda kutip).
number: Nilai numerik.
string: Rangkaian karakter teks.

default

Argumen default memberikan nilai default untuk variabel, sehingga variabel tersebut menjadi opsional.

Untuk mengakses nilai variabel yang dideklarasikan dalam suatu modul, gunakan ekspresi var.. Pada contoh berikut, variabel vpc_cidr_block dirujuk sebagai var.vpc_cidr_block dalam blok resource dan ditugaskan ke argumen cidr_block. Resource tersebut dibuat menggunakan nilai default variabel, yang diapit tanda kutip.

resource "alicloud_vpc" "my_vpc" {
  vpc_name    = "main-vpc"
  cidr_block  = var.vpc_cidr_block
  description = ""
}
variable "vpc_cidr_block" {
  default = "10.0.0.0/16"
}

Nama variabel dalam blok variable harus sesuai dengan referensinya dalam blok resource. Anda dapat mengganti nilai default dengan mengatur nilai melalui variabel lingkungan, file .tfvars, atau opsi CLI -var. Contohnya:

# Ganti nilai default menggunakan opsi CLI -var
$ terraform plan -var 'vpc_cidr_block=172.16.0.0/16'

description

Argumen description mendokumentasikan tujuan variabel tersebut. Jika suatu variabel tidak memiliki nilai default, Terraform akan menampilkan deskripsi tersebut saat meminta nilai selama operasi plan atau apply:

$ terraform plan
var.vpc_cidr_block
  A CIDR block for the VPC.
  Enter a value:

String description sering dimasukkan dalam dokumentasi dan harus menjelaskan tujuan serta nilai yang diharapkan untuk variabel tersebut. Tulis dari perspektif pengguna, bukan pemelihara modul. Gunakan komentar kode untuk catatan yang ditujukan kepada pemelihara modul.

sensitive

Mengatur argumen sensitive ke true mencegah Terraform menampilkan nilai variabel tersebut dalam output perintah atau file log. Hal ini menandai nilai sebagai sensitif dalam output terraform plan dan terraform apply.

Argumen ini berguna saat menangani informasi sensitif seperti kredensial database, AccessKey, atau kata sandi login. Menandai variabel sebagai sensitif mengurangi risiko terjadinya kebocoran informasi rahasia secara tidak sengaja.

Pada contoh ini, variabel vpc_cidr_block ditandai sebagai sensitif. Resource my-vpc menggunakan variabel ini. Saat Anda menjalankan terraform plan atau apply, nilainya tidak ditampilkan:

$ terraform plan
Terraform will perform the following actions:
  # alicloud_vpc.my-vpc will be created
  + resource "alicloud_vpc" "my-vpc" {
      + cidr_block            = (sensitive value)
      + create_time           = (known after apply)
      + id                    = (known after apply)
      + status                = (known after apply)
      + user_cidrs            = (known after apply)
      + vpc_name              = "main-vpc"
      ...
    }
Plan: 1 to add, 0 to change, 0 to destroy.

validation

Anda dapat memvalidasi nilai yang ditugaskan ke suatu variabel dengan menyertakan satu atau beberapa sub-blok validation dalam blok variable. Blok validation mencakup argumen condition yang menentukan aturan validasi.

Pada contoh berikut, fungsi length dan substr digunakan sebagai condition untuk memverifikasi bahwa nilai vpc_name lebih dari 4 karakter dan diawali dengan tf-:

variable "vpc_name" {
  validation {
    condition     = length(var.vpc_name) > 4 && substr(var.vpc_name, 0, 3) == "tf-"
    error_message = "The VPC name must start with 'tf-' and be longer than 4 characters."
  }
}

Saat Anda menjalankan terraform plan dan memasukkan my-vpc sebagai nilai untuk vpc_name, aturan validasi dipicu dan mengembalikan pesan kesalahan yang telah ditentukan:

Error: Invalid value for variable
  on main.tf line 66:
  66: variable "vpc_name" {
    var.vpc_name is "my-vpc"
The VPC name must start with 'tf-' and be longer than 4 characters.
This was checked by the validation rule at main.tf:67,3-13.

Mengatur variabel

Anda dapat mengatur nilai variabel saat runtime melalui beberapa cara:

# File .tfvars (disarankan)
$ terraform apply -var-file my-vars.tfvars
# Opsi CLI
$ terraform apply -var vpc_cidr_block="172.16.0.0/16"
# Variabel lingkungan
$ export TF_VAR_vpc_cidr_block="172.16.0.0/16"
$ terraform apply
# File variabel default terraform.tfvars
$ terraform apply

Anda dapat menggunakan file .tfvars untuk beralih dengan cepat antar set variabel dan mengontrol versinya. Opsi CLI berguna untuk validasi cepat pada konfigurasi sederhana. Variabel lingkungan berguna dalam skrip dan pipeline. Jika variabel wajib tidak diatur dengan metode apa pun, CLI akan meminta Anda memasukkan nilainya.

Saat Anda perlu mendefinisikan banyak variabel, terutama yang memiliki tipe kompleks, mengaturnya melalui opsi CLI bisa menjadi sulit. Sebagai gantinya, Anda dapat menentukan nilai variabel sebagai pasangan kunci-nilai dalam file dengan ekstensi .tfvars atau .tfvars.json. Kemudian, Anda dapat meneruskan file tersebut dengan opsi -var-file saat menjalankan terraform plan atau terraform apply:

$ terraform plan -var-file my-vars.tfvars

Definisi variabel dalam file dengan ekstensi .tfvars atau .tfvars.json mengikuti sintaksis HCL yang sama, tetapi hanya berisi penugasan ke nama variabel. Secara khusus, Terraform secara otomatis memuat file variabel yang bernama terraform.tfvars, terraform.tfvars.json, .auto.tfvars, atau .auto.tfvars.json saat Anda menjalankan perintah plan atau apply, sehingga tidak perlu menggunakan opsi -var-file. Definisi dalam file .tfvars menggantikan nilai default variabel dan definisi dari variabel lingkungan. Untuk mengganti nilai variabel dari file .tfvars melalui baris perintah, Anda dapat menggunakan opsi -var dalam format -var="<variable_name>=<variable_value>". Misalnya, untuk menentukan vpc_name sebagai "my-first-vpc" saat menjalankan terraform plan, gunakan metode berikut:

$ terraform plan -var 'vpc_name=my-first-vpc'

Output terraform plan kemudian akan menampilkan nilai vpc_name sebagai my-first-vpc, bukan my-vpc seperti yang didefinisikan dalam file .tfvars. Metode ini berguna dalam pipeline otomatis, memungkinkan Anda meneruskan nilai secara dinamis ke flag -var dan menggantikan nilai yang telah ditentukan sebelumnya.

Opsi CLI -var memiliki prioritas tertinggi dan menggantikan nilai yang diatur dengan metode lain.

Jika variabel wajib (yang tidak memiliki nilai default) tidak diberi nilai melalui metode apa pun yang dijelaskan, Terraform akan meminta Anda memasukkan nilai saat menjalankan plan atau apply. Misalnya, jika variabel wajib seperti vpc_name tidak memiliki nilai yang ditugaskan, CLI akan meminta input:

$ terraform plan
var.vpc_name
  Enter a value:

Praktik terbaik

Kami merekomendasikan praktik terbaik berikut saat mendeklarasikan variabel:

Parameterisasi hanya yang perlu diubah

Ekspos variabel hanya jika Anda memiliki kasus penggunaan spesifik yang mengharuskan nilainya berubah antar instans atau lingkungan. Hindari parameterisasi berlebihan. Menambah atau mengubah variabel dengan nilai default bersifat backward-compatible, tetapi menghapus variabel merupakan perubahan yang merusak (breaking change) dan memerlukan perhatian ekstra.
Lebih memilih file .tfvars untuk modul root

Untuk modul root, kami menyarankan menggunakan file .tfvars untuk mengatur nilai variabel. Hindari berganti-ganti antara file variabel dan opsi baris perintah. Opsi CLI bersifat sementara, mudah dilupakan, dan tidak dapat dikomit ke kode sumber untuk kontrol versi. Menggunakan file variabel default lebih dapat diprediksi.
Beri nama variabel sesuai tujuannya

Untuk variabel numerik, seperti ukuran disk atau memori, atau periode pembayaran, sertakan satuan dalam nama variabel bila memungkinkan. Alibaba Cloud OpenAPI tidak memiliki satuan standar, sehingga konvensi penamaan ini memperjelas satuan input yang diharapkan bagi mereka yang memelihara konfigurasi Terraform. Untuk variabel logis, gunakan nama yang diformulasikan secara positif, seperti enable_ipv6, untuk menyederhanakan logika kondisional.
Berikan deskripsi untuk setiap variabel

Deskripsi secara otomatis dimasukkan dalam dokumentasi dan memberikan konteks tambahan bagi pengembang baru, sehingga meningkatkan keterbacaan dan kemudahan pemeliharaan file konfigurasi Terraform Anda.