全部產品
Search
文件中心

Terraform:Variable 介紹

更新時間:Jul 31, 2025

概述

前文中的樣本一直在寫入程式碼資源參數值,但如果你想參數化配置或者標準化代碼,並在 Terraform 工作流程的 apply 階段自訂資源屬性怎麼辦?這正是本文要講的變數的用武之地。

變數可以讓你參數化在資源之間共用的值,除此之外,使用變數還具有以下好處:

  1. 增加通用性

    輸入變數作為參數提供給 Terraform 使用,將原始碼和屬性賦值分離,可以實現對同一份 Terraform 配置的輕鬆定製和共用,而無需更改原始碼。

  2. 提高靈活性

    定義變數後,在運行時(apply)有多種方法可以為屬性自訂設定其值,包括環境變數、CLI 選項和索引值對檔案。在如下的樣本中,名稱、描述和網段都是硬式編碼。你可以將這些屬性中的任何一個聲明為變數,並在運行時指定具體的值。

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

變數的文法

接下來讓我們探討如何聲明輸入變數。

變數必須在 variable 塊中聲明。建議將所有的變數聲明儲存在一個名為 variables.tf 的檔案中。

關鍵字 variable 旁邊的標籤為變數名稱。變數名稱有兩個設定規則:

  1. 變數名在模組內必須唯一

    在當前模組中聲明的變數,名稱必須保持唯一性,當然子模組中聲明的變數和主模組中聲明的變數不會衝突。

  2. 變數名不能是關鍵字

    變數名不能是 Terraform 預留的關鍵字,比如所有的元參數 count,for_each 等

變數沒有必選的參數,因此變數塊可以為空白,Terraform 可以根據變數值自動推斷類型和預設值。

type

type 參數指定了變數接受的值的類型。Terraform 支援以下基本變數類型:

  • bool,用於二進位值,如 true 或 false(不帶引號)

  • number,用於數值變數

  • string,用於字元序列

default

default 是變數的另一個元參數,用於給屬性分配預設值。

要訪問模組內聲明的變數值,可以使用運算式 var.。在如下的樣本中,變數 vpc_cidr_block 在資源塊中格式化為 var.vpc_cidr_block,並被分配給 cidr_block 參數,建立資源時使用引號中的預設值。

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

變數塊中的變數名必須與資源塊中的引用相匹配。預設值可以通過分配值在環境變數或 .tfvars 檔案或 -var 選項中被覆蓋,如:

# 通過 CLI -var 選項覆蓋變數預設值
$ terraform plan -var vpc_cidr_block="172.16.0.0/16"

description

description 用於記錄變數的用途。當變數沒有定義預設值時,描述將在 plan 或者 apply 階段顯示:

截屏2024-07-13 21.05.24.png

description 字串通常包含在文檔中,應當解釋變數的用途和預期值。因此應從使用者使用視角而非維護者的角度去編寫。維護者可以使用注釋,而非直接寫到 description 中。

sensitive

sensitive 是一個變數參數,顧名思義,用於保護敏感資訊不會顯示在命令輸出或記錄檔中。敏感值的可接受值為true。當設定為true時,變數的值在 terraform plan 或terraform apply 的輸出中標記為敏感。

當處理如資料庫憑證或 AccessKey 或者登入密碼等敏感資訊時,此參數非常有用,將變數標記為敏感將消除意外暴露機密資訊的風險。

在此樣本中,變數 vpc_cidr_block 被標記為敏感。資源 my-vpc 使用了變數 vpc_cidr_block,運行 terraform plan 或 apply 時,值沒有被顯示:

$ 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

驗證塊包含一個條件參數,用於指定驗證規則。你可以通過在變數塊中包含驗證子塊來驗證賦給變數的值。

在如下樣本中,length 和 substr 用作條件參數,驗證 vpc_name 的值是否長度超過 4 並且是否以 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."
  }
}

當執行 terraform plan 並且輸入 vpc_name 值為 my-vpc 時,將會觸發規則校正拋出具體的錯誤資訊:

截屏2024-07-14 11.14.42.png

變數的設定方式

在運行時有多種設定變數值的方法:

# .tfvars 檔案(推薦)
$ terraform apply -var-file my-vars.tfvars

# CLI 選項
$ terraform apply -var vpc_cidr_block=“172.16.0.0/16”

# 環境變數
$ export TF_VAR_vpc_dicr_block=“172.16.0.0/16”
$ terraform apply

# 預設的變數檔案 terraform.tfvars
$ terraform apply

首先,你可以使用 .tfvars 檔案快速切換和版本變數集;你也可以使用 CLI 選項,在運行簡單設定檔的快速驗證時非常有用;環境變數在指令碼和流水線中非常有用。如果通過 description 的方法沒有設定所需變數,可以使用 CLI 提示。

當需要輸入許多變數定義,尤其是涉及到複雜類型的變數時,在 CLI 選項中設定變數值將會比較困難。相反,可以在副檔名為 .tfvars 或 .tfvars.json 的檔案中以 K-V 的方式指定變數值,然後在運行 terraform plan 或者 apply 命令是通過 -var-file 選項指定參數集:

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

副檔名為 .tfvars 或 .tfvars.json 的檔案中的變數定義遵循與 HCL 相同的文法,但僅包含對變數名的賦值。值得注意的是,只要變數檔案準確地命名為terraform.tfvars、terraform.tfvars.json、.auto.tfvars或.auto.tfvars.json,Terraform 在執行 plan 或者 apply 命令時會自動載入這些檔案,無需使用 -var-file 選項。.tfvars 檔案中的定義會覆蓋變數的預設值和環境變數中的定義。如果要在命令列上替換 .tfvars 檔案中設定的變數的值,可以使用 -var 選項,具體格式為 -var="<變數名>=<變數值>",比如想要在執行 terraform plan 的時候,將 vpc_name 指定為 "my-first-vpc",可以使用如下的方式:

$ terraform plan -var="vpc_name=my-fisrt-vpc"

此時 terraform plan 的輸出結果中,vpc_name 的值將顯示為 my-fisrt-vpc,而非 .tfvars 中定義的 my-vpc。此方法常用於自動化流程,其中 -var 從另一個環境變數擷取,並替換掉變數檔案中事先定義好的值。

-var 選項的優先順序最高,超過所有其他變數賦值方法。如果同時存在多種為變數賦值的方法,使用 -var 選項定義的值最終將賦給變數。

如果某個變數沒有使用以上所描述的方法設定變數值,那麼 Terraform 會在運行 plan 或者 apply 的時候提示你。例如,在本例中,變數 vpc_name 未被賦值,如果在執行 terraform 命令的時候也沒有使用 -var 或者 -var-file 選項,則 CLI 將會提示你要輸入值:

截屏2024-07-14 10.57.18.png

變數的最佳實務

當聲明變數的時候,我們提供以下幾條建議:

  1. 只參數化每個執行個體或環境中會變化的值

    在決定是否暴露一個變數時,請確保你有具體的變更用例。如果一個變數只有很小的幾率需要使用,請不要暴露它。對帶有預設值的變數變更或新增是向後相容的,但是移除某個變數則屬於非相容性變更,需要額外注意。

  2. 儘可能使用 .tfvars 變數檔案

    對於根模組,推薦使用 .tfvars 變數檔案來為變數設定具體的值。儘可能避免在變數檔案和命令列選項之間交替使用,命令列選項是臨時的,容易被遺忘,並且無法被提交到原始碼中進資料列版本設定,而預設的變數檔案更具有可預測性。

  3. 給變數起與其使用目的相關的名稱

    表示數值的變數,例如磁碟大小或者記憶體大小或者付費時間長度,儘可能在變數命名中使用單位。阿里雲的 OpenAPI 沒有標準單位,因此遵循這種命名規範可以為 Terraform 設定檔的維護者明確預期的輸入單位。表示邏輯的變數,為了簡化條件邏輯,應給布爾變數取帶有肯定含義的名字,例如 enable_ipv6。

  4. 變數必須要有描述

    描述會自動包含在文檔中,並為新的開發人員添加額外的上下文,增強 Terraform 設定檔的可讀性和可維護性。