Terraform 是把基礎設施寫成設定檔的工具:你宣告「要什麼」,它比對現況、算出差異、再執行。本次用 Terraform 1.17.2 在 2 核心 VPS 實測,30 行設定跑完 init、plan、apply 到 destroy,全程 4 秒內結束,同一份檔案用 OpenTofu 1.13.9 也能直接跑通。
手動點 Console 的五個慢性病
| 症狀 | 你以為的情況 | 實際上 |
|---|---|---|
| 「這台機器誰開的」 | 查 cloud console 的 activity log | 三個月前的 log 早被覆蓋,開機器的人已離職 |
| 「測試環境跟正式差在哪」 | 應該一樣吧 | 上個月有人在正式環境手動改了安全群組,沒人記得 |
| 「重建一次要多久」 | 半小時吧 | 兩天,而且每次都不一樣,因為順序靠記憶 |
| 「可以只改一個參數嗎」 | 改完重開就好 | 有些資源改了要重建,服務中斷時間沒人算過 |
| 「稽核要變更紀錄」 | 應該有 log | log 只記「誰按了按鈕」,沒記「為什麼」與「改了什麼」 |
這五件事的共同點:基礎設施的真實狀態存在人的記憶裡,而不是檔案裡。 IaC 的價值不是「自動化很快」,而是把狀態從記憶搬到版本控制。
一表看懂:五種 IaC 工具的差別
| 工具 | 設定語言 | 狀態管理 | 授權 | 適合誰 |
|---|---|---|---|---|
| Terraform 1.17.2 | HCL(宣告式) | 自己維護 state 檔 | BUSL 1.1(四年後轉 MPL 2.0) | 多雲、生態最大,採用最久 |
| OpenTofu 1.13.9 | HCL(與 Terraform 相容) | 同 Terraform + 內建加密 | MPL 2.0(開源) | 不想被 BUSL 綁住、要 state 加密 |
| Pulumi | TypeScript/Python/Go | 雲端或自架狀態後端 | Apache 2.0(社群版) | 想用真程式語言寫,不要 HCL |
| Ansible | YAML playbook | 無狀態(每次重跑) | GPL 3.0 | 設定機器內部,不是開雲端資源 |
| CloudFormation | YAML/JSON | AWS 代管 | 專有 | 純 AWS、不想自己管 state |
最常被搞混的是 Ansible 與 Terraform。Ansible 管「機器裡面」(裝套件、改設定檔),Terraform 管「機器本身」(開 VM、建網路、給 IAM),兩者互補而不是替代。
五個核心概念,先建立心智模型
| 概念 | 白話解釋 | 對應到本次實測 |
|---|---|---|
| Provider | 外掛,負責跟某個平台講話 | hashicorp/local、hashicorp/random |
| Resource | 一個要被建立的東西 | local_file.env_config(寫出 .env 檔) |
| State | Terraform 記下的「上次做完的結果」 | terraform.tfstate |
| Plan | 把「設定」與「state+現況」相比,算出要動什麼 | terraform plan |
| Module | 打包好的設定,可重複引用 | 本次未用,團隊規模變大才需要 |
整個流程可以濃縮成一句話:讀設定 → 讀 state → 對照真實世界 → 算出最小差異 → 執行。理解這條線,後面所有錯誤訊息都看得懂。
你寫的 .tf ──┐
├──► plan(差異)──► apply ──► 真實資源
state 檔 ────┤ │
真實世界 ────┘◄────── refresh ──────────────┘
實測環境
| 項目 | 規格 |
|---|---|
| Terraform | v1.17.2(2026-11-11 發布)+ linux_amd64 |
| 對照工具 | OpenTofu v1.13.9(2026-11-05 發布) |
| 機器 | 2 vCPU / 7 GB RAM / 無 GPU 的 VPS |
| Provider | hashicorp/local v2.9.1、hashicorp/random v3.9.1 |
| 示範對象 | 本機檔案與隨機 ID(不需雲端帳號,任何人都能複製貼上跑完) |
刻意不用 AWS:一來不需要帳號與費用,二來所有讀者都能在自己的電腦上驗證本文的每個數字。真正的雲端 provider 差別只在「API 呼叫變慢」,流程完全一樣。
安裝:三個指令
# 1) 下載(版本號換成你要的)
curl -sLO https://releases.hashicorp.com/terraform/1.17.2/terraform_1.17.2_linux_amd64.zip
# 2) 解壓並放到 PATH
unzip -o terraform_1.17.2_linux_amd64.zip -d /usr/local/bin
# 3) 確認版本
terraform version
# Terraform v1.17.2
# on linux_amd64
macOS 用 brew install terraform;Windows 建議用 WSL,不要在 PowerShell 裡混用路徑,否則 path.module 的行為會讓你抓狂。
專案結構
tfdemo/
├── main.tf # 你寫的設定
├── .terraform.lock.hcl # provider 版本鎖定(要進版控)
├── .terraform/ # provider 二進位(不要進版控)
├── terraform.tfstate # 狀態檔(不要進版控)
└── out/ # 本次產生的檔案
.gitignore 至少要有這兩行:
.terraform/
*.tfstate*
30 行設定長什麼樣
terraform {
required_version = ">= 1.6.0"
required_providers {
local = { source = "hashicorp/local", version = "~> 2.5" }
random = { source = "hashicorp/random", version = "~> 3.6" }
}
}
variable "project" {
type = string
description = "專案代號,會出現在檔名與標籤裡"
default = "demo"
}
variable "environments" {
type = list(string)
description = "要產生的環境清單"
default = ["dev", "staging"]
}
resource "random_id" "suffix" {
byte_length = 3
}
locals {
bucket_name = "${var.project}-assets-${random_id.suffix.hex}"
common_tags = {
project = var.project
managed_by = "terraform"
}
}
resource "local_file" "env_config" {
for_each = toset(var.environments)
filename = "${path.module}/out/${each.key}.env"
content = <<-EOT
APP_ENV=${each.key}
BUCKET=${local.bucket_name}
MANAGED_BY=${local.common_tags.managed_by}
EOT
}
output "bucket_name" {
value = local.bucket_name
description = "本次執行產生的假物件儲存桶名稱"
}
output "files_written" {
value = { for k, f in local_file.env_config : k => f.filename }
}
四段值得停下來看的地方:
required_providers鎖版本。 寫~> 2.5代表允許 2.5 到 3.0 之間,避免 provider 大改版把 plan 弄壞。for_each而不是count。 用count的話,清單中間刪一個環境會導致後面全部索引位移、資源重建;for_each用 key 認身分,刪哪個就只動哪個。locals把重複的字串收斂。 三處都寫"managed_by" = "terraform"遲早會有一處漏改。output給人與 CI 看。 後續 pipeline 要拿 bucket 名稱,就從terraform output -raw bucket_name取,不要爬 log。
第一次 init:0.79 秒
terraform init
實際輸出(節錄):
Initializing provider plugins...
- Installing hashicorp/local v2.9.1...
- Installed hashicorp/local v2.9.1 (signed by HashiCorp)
- Installing hashicorp/random v3.9.1...
- Installed hashicorp/random v3.9.1 (signed by HashiCorp)
Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.
Terraform has been successfully initialized!
init 做三件事:下載 provider、寫 lock 檔、初始化 backend。它同時是最常被誤解的指令——改了 backend 或 provider 來源之後,必須重跑 init,否則 Terraform 會用舊的 plugin 目錄繼續跑,錯誤訊息還不會直接告訴你。
validate 與 plan:先看要動什麼,再動手
terraform validate
# Success! The configuration is valid.
terraform plan -out=tfplan
plan 的尾段是重點:
Plan: 3 to add, 0 to change, 0 to destroy.
Changes to Outputs:
+ bucket_name = (known after apply)
+ files_written = {
+ dev = "./out/dev.env"
+ staging = "./out/staging.env"
}
Saved the plan to: tfplan
3 to add 對應:一個 random_id、兩個 local_file(dev 與 staging)。(known after apply) 代表這個值要等真的執行才知道——random_id 是執行時才產生的,所以依賴它的檔名也是。
-out=tfplan 是上 production 的關鍵習慣。 存下 plan 檔再 terraform apply tfplan,執行的是「你剛剛看過的那一份計畫」,中間別人改了雲端也不會偷渡進去。
apply:0.42 秒,狀態檔開始有意義
terraform apply tfplan
random_id.suffix: Creating...
random_id.suffix: Creation complete after 0s [id=i5La]
local_file.env_config["dev"]: Creating...
local_file.env_config["dev"]: Creation complete after 0s [id=95926ff8bd...]
local_file.env_config["staging"]: Creating...
local_file.env_config["staging"]: Creation complete after 0s [id=e335a0a064...]
Apply complete! Resources: 3 added, 0 changed, 0 destroyed.
Outputs:
bucket_name = "demo-assets-8b92da"
files_written = {
"dev" = "./out/dev.env"
"staging" = "./out/staging.env"
}
實際產出的檔案內容:
APP_ENV=dev
BUCKET=demo-assets-8b92da
MANAGED_BY=terraform
到這裡為止,terraform.tfstate 已經記下三個資源的 ID 與屬性。state 檔不是快取,是事實來源——把它當暫存檔刪掉,等於把 Terraform 的眼睛挖掉(見下方第八個坑)。
查狀態的兩個常用指令:
terraform state list
# local_file.env_config["dev"]
# local_file.env_config["staging"]
# random_id.suffix
terraform output -raw bucket_name
# demo-assets-8b92da
改設定會發生什麼:三個真實情境
情境一:什麼都不改,重跑 plan
No changes. Your infrastructure matches the configuration.
(耗時 0.34 秒)
這就是 IaC 最重要的性質——冪等(idempotent)。重跑一百次結果一樣,所以它適合放進 CI,每次 PR 都跑一次 plan 當作「這次改動會影響什麼」的檢查。
情境二:多加一個環境
terraform plan -var='environments=["dev","staging","prod"]'
# local_file.env_config["prod"] will be created
Plan: 1 to add, 0 to change, 0 to destroy.
只加一個,不動其他兩個——這是 for_each 的價值。如果當初寫的是 count,這個操作會變成「staging 被 prod 覆蓋」的重建。
情境三:有人手動改了檔案(狀態漂移)
故意把 out/dev.env 內容改成 APP_ENV=hacked,再跑 plan:
# local_file.env_config["dev"] will be created
+ resource "local_file" "env_config" {
+ content = <<-EOT
APP_ENV=dev
...
注意它說的是 created,不是 updated。這是 local_file 這個 provider 的特性:它的資源 ID 是內容的 SHA1,檔案被外部改掉之後,Terraform 眼中「原本那個資源」已經不存在了,所以計畫是重建。terraform apply 之後檔案確實回到正確內容。
真實雲端資源(VM、S3 bucket)的 ID 是平台給的、不會因為屬性改變而變,所以漂移通常會顯示 ~ update in-place 或 -/+ must be replaced。看到 -/+ 就要警覺:那是刪掉重建,對資料庫或儲存桶意味著資料消失。
精準重建:-replace
想強制重建單一資源(例如機器卡在某個壞狀態),不要用 taint 了,用 -replace:
terraform plan -replace=random_id.suffix
# local_file.env_config["dev"] must be replaced
~ content = <<-EOT ...
# local_file.env_config["staging"] must be replaced
連帶影響很清楚:random_id 換了,依賴它產生 bucket_name 的兩個檔案也必須重建。這種「連鎖影響可視化」正是 plan 的價值——它會先告訴你代價,再讓你決定。
destroy:0.48 秒,收乾淨
terraform destroy
local_file.env_config["dev"]: Destruction complete after 0s
local_file.env_config["staging"]: Destruction complete after 0s
random_id.suffix: Destroying... [id=i5La]
random_id.suffix: Destruction complete after 0s
Destroy complete! Resources: 3 destroyed.
執行後 terraform state list 回空、out/ 目錄裡的檔案也一併刪除。生產環境請把 destroy 當成有保險鎖的指令:多數團隊會用 prevent_destroy = true 鎖住資料庫這類資源。
resource "aws_db_instance" "main" {
# ...
lifecycle {
prevent_destroy = true
}
}
本次實測數據(單位:秒)
| 動作 | Terraform 1.17.2 | 備註 |
|---|---|---|
init(全新,需下載 2 個 provider) | 0.79 | 冷啟動,含 registry 查詢與下載 |
validate | < 0.1 | 只做語法與型別檢查 |
plan(首次) | 0.36 | 3 個資源 |
plan(無變更) | 0.34 | 冪等驗證 |
apply(3 個資源) | 0.42 | local provider,無網路 API |
destroy(3 個資源) | 0.48 | 同上 |
init(OpenTofu 1.13.9,同一份 HCL) | 3.78 | provider 來自 registry.opentofu.org |
這張表不能當成效能排名。 全部是 local provider 操作,沒有雲端 API 延遲;真實環境建一台 EC2 要 30 秒到 2 分鐘,瓶頸在雲端而不是 Terraform。OpenTofu 的 3.78 秒是單次冷啟動量測(不同 registry、不同 CDN 快取狀態),樣本只有一次,不具比較意義。
團隊協作:state 一定要搬出本機
一個人玩,state 放本機沒問題。兩個人以上就會出事:A 的 state 沒有 B 剛建的資源,A 一 apply 就把它刪了。
遠端 backend 的最小設定(S3):
terraform {
backend "s3" {
bucket = "my-tfstate-bucket"
key = "prod/network/terraform.tfstate"
region = "ap-northeast-1"
encrypt = true
use_lockfile = true
}
}
三個關鍵:
use_lockfile = true才是現在的鎖定方式。 官方文件已明確標示 DynamoDB 鎖定(dynamodb_table)為 deprecated、未來小版本會移除。舊教學十篇有九篇還在教 DynamoDB,照抄會踩到未來升級。- 開 bucket versioning。 官方文件的警告就這一句:防止誤刪與人為錯誤時還能救回 state。
- state 內含敏感值。 資料庫密碼、私鑰都可能以明文存在 state 裡,所以 bucket 要開加密、權限要收斂。
workspace 的狀態路徑是 <prefix>/<workspace>/<key>,預設前綴是 env:,所以 development workspace 會存在 env:/development/prod/network/terraform.tfstate。知道這條規則,臨時要救資料時才找得到檔案。
Terraform 與 OpenTofu:2023 年那道分岔
2023 年 8 月 HashiCorp 把 Terraform 從 MPL 2.0 改成 BUSL 1.1,社群因此在 Linux Foundation 下 fork 出 OpenTofu。兩年後的今天,這件事的實際影響是:
| 項目 | Terraform | OpenTofu |
|---|---|---|
| 目前版本 | 1.17.2(2026-11-11) | 1.13.9(2026-11-05) |
| 授權 | BUSL 1.1,Change Date 為發布後 4 年,之後轉 MPL 2.0 | MPL 2.0 |
| 商用限制 | 不得把本體以託管或嵌入方式提供,與 IBM 的付費版競爭(Additional Use Grant 允許一般生產使用) | 無此限制 |
| Registry | registry.terraform.io(8.58 億次下載的 AWS provider 在此) | registry.opentofu.org(也鏡像 Terraform registry 的 provider) |
| 相容性 | 基準 | 同一份 HCL 可直接跑;本次實測 tofu init 與 tofu plan 全數通過 |
實測時 OpenTofu 的 tofu version --json 顯示 provider 來源是 registry.opentofu.org/hashicorp/local 2.9.1——同一個版本號,換了 registry。這代表多數社群的 provider 兩邊都能用,差異主要出現在 HashiCorp 自家新功能(例如 1.17 GA 的 Terraform Policy)不會進 OpenTofu。
選哪個?三個判斷點:
- 公司有法務審核開源授權 → 選 OpenTofu,MPL 2.0 沒有模糊空間。
- 需要 HashiCorp 官方支援、Terraform Cloud/Enterprise 生態 → 留 Terraform。BUSL 的 Additional Use Grant 對「自己內部使用」是允許的,多數企業其實沒踩線。
- 需要 state 加密 → OpenTofu 內建,Terraform 要靠 S3 SSE 或外部方案。
1.17 版多了什麼
| 功能 | 意義 |
|---|---|
| provider requirements 可用變數與 locals | 多環境/多 region 的 provider 版本可以參數化,不用複製貼上 |
-minimal-refresh | 只 refresh「有變更計畫」的資源,大型專案 plan 明顯變快(本次規模小,差異量測不出來) |
| Terraform Policy GA | plan/apply/query 加 -policies 就能跑政策檢查,不再需要實驗旗標 |
第三項對團隊最有感:以前「不准開 0.0.0.0/0 的安全群組」要靠自寫腳本掃 plan JSON,現在是原生命令。
八個踩過才知道的坑
| 坑 | 症狀 | 解法 |
|---|---|---|
把 terraform.tfstate 加進 .gitignore 之後也忘了備份 | 換電腦後 Terraform 認為資源都不存在,一 apply 全部重建 | 本機開發也要開遠端 backend,或至少定期備份 state |
| 手動改雲端主控台 | plan 突然冒出一堆「要改回去」的變更 | 這是正常行為,別用 -refresh=false 蓋掉;要嘛改設定,要嘛匯入 |
刪掉 .terraform.lock.hcl | CI 與本機裝到不同版本的 provider,plan 結果不一致 | lock 檔一定要進版控 |
count 用在會增刪的清單 | 刪中間一個,後面全部重建 | 改用 for_each + map/set |
sensitive = true 只遮輸出 | 值仍以明文存在 state | 敏感資料用外部 secret manager,或 OpenTofu 的 state 加密 |
在 CI 用 apply -auto-approve 直接跑 | 沒人看過 plan 就改動生產環境 | CI 流程固定為 plan -out → 人工核准 → apply tfplan |
迴圈裡呼叫 terraform apply 多次 | state 鎖衝突、跑一半失敗難善後 | 一次 plan 涵蓋所有變更 |
terraform destroy 在錯的 workspace | 拆掉不該拆的環境 | 執行前先 terraform workspace show,資料庫類加 prevent_destroy |
誰適合,誰不需要
適合現在開始用:
- 已經有 3 台以上雲端機器,或準備開第二個環境(staging/prod)
- 團隊兩人以上,開始出現「這是誰開的」這種問題
- 需要合規稽核(誰在什麼時候改了什麼)
- 正在把地端服務搬上雲,想先寫成可重複的規格
可以再等等:
- 只有一台 VPS、一個 docker compose 檔——
docker compose本身就是宣告式,再加一層 Terraform 只是多一個 state 要顧 - 完全沒有雲端資源,只是管 Kubernetes 內部物件——Helm 與 Kustomize 更直接
- 團隊沒有版本控制習慣——先建立 PR 流程,否則 IaC 只會把混亂寫成程式碼
已知限制與沒做的事
- 沒有實測真實雲端 provider。 本次刻意用 local/random provider,所以文中沒有「建一台 EC2 要幾秒」的數字。EC2、RDS 的實際耗時受 region 與 API 限流影響,需要實測才能寫。
- 沒有跑 Terraform Cloud。 遠端執行、policy as code 的雲端版流程未驗證,文中講的是 OSS 版 CLI。
-minimal-refresh的加速幅度未量化。 本次只有 3 個資源,差異落在誤差內;資源上百個的專案才有明顯差距。- OpenTofu 只驗證 init 與 plan,沒有 apply。 相容性結論限於「同一份 HCL 可初始化與產生計畫」。
- 版本與星數以查證當下為準。 Terraform 1.17.2(2026-11-11)、OpenTofu 1.13.9(2026-11-05);OpenTofu 約 30,900 星、Terraform 約 50,200 星,數字會變動。
站內延伸閱讀
- Docker Compose healthcheck 實戰:等到健康才啟動——IaC 開完機器之後,容器怎麼等到真的可用,這篇補上。
- AWS Emulator 實測:官方本機 AWS 模擬器怎麼用——想在沒有雲端帳號的情況下測 Terraform,這是另一條路。
- 老系統不用打掉重練:10 集 K8s 漸進現代化影片導讀——Terraform 管基礎設施、K8s 管工作負載,兩者的分工邊界這篇講得清楚。
- Nginx 反向代理完整指南——機器開好之後最常接的第一個服務。
本文不含聯盟連結;版本號與授權條文以官方 release 頁與 LICENSE 檔為準,實測數據為 2026-11-18 在單機量測的單次結果。
