Terraform 資源搜尋與匯入教學：自動生成代碼，完成 IaC 遷移

HashiCorp Terraform 技術專欄技術專欄 2026 年 4 月 16 日

雲端架構隨著企業規模擴張，常面臨預算浪費、設定偏移 (Configuration Drift)、缺乏治理與 Shadow IT 等問題。

雖然 Terraform 已成為基礎架構佈署的標準，但如何將散落在各處、未受控的舊有資源納入管理，一直是維運團隊的挑戰。為了解決碎片化流程，Terraform 1.14 版本推出了搜尋 (Search) 與批量匯入 (Bulk-import) 功能。

這項新工作流不只協助企業盤點雲端環境中未受託管的資源，更直接將其導入自動化的安全流程中。以下將透過實際案例，說明 Terraform 如何簡化資源匯入的繁瑣過程。

為什麼需要 Terraform 資源搜尋功能？

目前的雲端環境極其複雜，根據統計，高達 97% 的企業在管理基礎架構時面臨挑戰，且需解決預算超支的問題。其中，「混合雲與多雲環境」的營運複雜度，被公認為是目前最大的技術阻礙。

具體來說，維運團隊常遇到以下問題：

解決手動操作 (ClickOps) 的管理漏洞

直接在雲端控制台手動點選（ClickOps）產生的資源，因為繞過了 IaC 流程，缺乏版本控制與自動化，成為資安治理與成本控制的盲點。

解決雲端資源浪費與閒置風險

缺乏統一盤點工具會導致測試環境、閒置虛擬機或過期儲存空間被遺忘。這些「孤兒資源」大幅增加非必要支出，更因為設定過期或錯誤，成為駭客入侵的資安破口。

解決設定偏移隱患

當雲端資源的實際狀態與預期代碼不符，即產生「設定偏移」。若資源未透過 IaC 管理，偏移將變得不可控，並引發以下風險：

資安威脅：未被追蹤的變更可能成為攻擊者的入侵破口。
營運中斷：意外的設定變動會導致部署失敗或服務停機。
合規風險：稽核員無法確認實際環境是否符合公司政策或安全標準。

解決政策執行與自動化治理的缺失

缺乏 IaC 的環境無法建立防護欄（Guardrails）或自動化合規檢查，因此容易繞過安全控制，增加營運風險並喪失環境可視性，進而造成違反法規或不符產業標準的情況。

Terraform Search 如何解決管理難題？

Terraform Search 支援 HCP Terraform 介面、版本控制系統 (VCS) 或 CLI 工作區，有效解決上述痛點。操作邏輯簡單：

定義查詢：在設定檔中使用 list 區塊定義查詢條件，主動搜尋雲端環境中的現有資源。
自動生成代碼：透過 terraform query 指令，自動產出匯入所需的 resource 與 import 區塊。
一鍵納管：將產出的代碼複製到 main.tf 並執行 terraform apply，即可完成資源匯入。

這套工作流取代了過去耗時且容易出錯的手動匯入（terraform import）流程，實現更安全、可重複利用的自動化管理。

案例：透過 Terraform Search 匯入 AWS EC2 資源

本範例將示範如何搜尋並匯入已存在於 AWS 控制台、但尚未納入 Terraform 狀態檔（State）管理的 EC2 實例。目標是消除管理斷層，將資源統一納入 Terraform 管理。

若使用 HCP Terraform（版本 1.14 以上），可以在左側選單看到新增的「Search & Import」選項。本案例將以 CLI 操作為主，示範匯入流程所需的 HCL 代碼。

HCP Terraform 工作區中的「搜尋與匯入 (Search & Import)」功能介面

透過 search.tfquery.hcl 檔案內的 list 區塊來定義查詢條件。此區塊包含兩個核心參數：指定執行查詢的 Provider，以及用來建構查詢條件的 config 區塊。

search.tfquery.hcl

list "aws_instance" "unmanaged" {
  provider = aws
 
  config {
    region = "us-east-2"
 
    filter {
      name   = "tag:ManagedBy"
      values = ["unmanaged"]
    }
 
    filter {
      name   = "instance-state-name"
      values = ["running"]
    }
  }
}

此範例透過 Terraform 搜尋 AWS us-east-2 區域中，所有標籤為 ManagedBy: unmanaged 的執行中 EC2 實例。

提示：查詢條件可根據需求自定義。更多進階參數請參考官方的「批量匯入資源 (Import resources in bulk)」文件。

定義好查詢條件後，即可執行以下指令：

$ terraform query
Running query in HCP Terraform. Output will stream here. Pressing Ctrl-C
will stop streaming the logs, but will not stop the query running remotely.
 
Preparing the remote query run...
 
To view this query run in a browser, visit:
https://app.terraform.io/app/acfaria-hashicorp/ec2-search/search/qry-ubTgayE2hnLsF3LL
 
Waiting for the query run to start...
 
Terraform 1.14
on linux_amd64
Initializing plugins and modules...
list.aws_instance.unmanaged   account_id=008971679752,id=i-011f5cd5c03cc2560,region=us-east-2   unmanaged-instance-6
list.aws_instance.unmanaged   account_id=008971679752,id=i-0ca0957c269603542,region=us-east-2   unmanaged-instance-2
list.aws_instance.unmanaged   account_id=008971679752,id=i-0553ba06da0a4ae8f,region=us-east-2   unmanaged-instance-4
list.aws_instance.unmanaged   account_id=008971679752,id=i-0f10ea0f0d579ed3d,region=us-east-2   unmanaged-instance-3
list.aws_instance.unmanaged   account_id=008971679752,id=i-0ebdff0b154a659df,region=us-east-2   unmanaged-instance-1
list.aws_instance.unmanaged   account_id=008971679752,id=i-02c648ca8076d113f,region=us-east-2   unmanaged-instance-5

Terraform 搜尋結果會同步顯示在 CLI 介面與 HCP Terraform 控制台：

HCP Terraform 控制台呈現的搜尋查詢與結果畫面

HCP Terraform 控制台會同步顯示查詢設定，可以檢視各項未受控資源的細節，勾選欲匯入狀態檔（State）項目、點擊「Generate Starter Configuration」來生成初始代碼。

已勾選欲匯入的未受控資源

HCP Terraform 控制台自動產出匯入所需的 import 與 resource 區塊（如下圖）。請確認生成的 HCL 代碼無誤後，即可將未受控資源匯入 Terraform 狀態檔（State）。

HCP Terraform 控制台生成的初始代碼（Starter Configuration）

將產出的初始代碼複製到工作區的 main.tf 並視需求調整（如：移除衝突參數、修改標籤值），即可執行 terraform apply 將未受控資源匯入狀態檔（State）。

提示： 針對架構較複雜（complex schemas）的資源，Terraform 生成的預設代碼可能不完全正確，匯入前須手動微調。詳細資訊請參考官方文件的「限制說明（Limitations）」章節。

$ terraform apply
Running apply in HCP Terraform. Output will stream here. Pressing Ctrl-C
will cancel the remote apply if it's still pending. If the apply started it
will stop streaming the logs, but will not stop the apply running remotely.
 
Preparing the remote apply...
 
To view this run in a browser, visit:
https://app.terraform.io/app/acfaria-hashicorp/ec2-search/runs/run-ULkrfr9NQNNEjgAw
 
Waiting for the plan to start...
 
Terraform 1.14
on linux_amd64
Initializing plugins and modules...
aws_instance.unmanaged_4: Refreshing state... [id=i-0ebdff0b154a659df]
aws_instance.unmanaged_5: Refreshing state... [id=i-02c648ca8076d113f]
aws_instance.unmanaged_2: Refreshing state... [id=i-0553ba06da0a4ae8f]
aws_instance.unmanaged_3: Refreshing state... [id=i-0f10ea0f0d579ed3d]
aws_instance.unmanaged_1: Refreshing state... [id=i-0ca0957c269603542]
aws_instance.unmanaged_0: Refreshing state... [id=i-011f5cd5c03cc2560]
 
Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  ~ update in-place
 
Terraform will perform the following actions:
 
  # aws_instance.unmanaged_0 will be updated in-place
  # (will be imported first)
 …
 
Plan: 6 to import, 0 to add, 6 to change, 0 to destroy.

資源會立即匯入 CLI 與 HCP Terraform 狀態中。

aws_instance.unmanaged_5: Modifying... [id=i-02c648ca8076d113f]
aws_instance.unmanaged_1: Modifying... [id=i-0ca0957c269603542]
aws_instance.unmanaged_0: Modifying... [id=i-011f5cd5c03cc2560]
aws_instance.unmanaged_4: Modifying... [id=i-0ebdff0b154a659df]
aws_instance.unmanaged_3: Modifying... [id=i-0f10ea0f0d579ed3d]
aws_instance.unmanaged_2: Modifying... [id=i-0553ba06da0a4ae8f]
aws_instance.unmanaged_0: Modifications complete after 1s [id=i-011f5cd5c03cc2560]
aws_instance.unmanaged_1: Modifications complete after 1s [id=i-0ca0957c269603542]
aws_instance.unmanaged_2: Modifications complete after 1s [id=i-0553ba06da0a4ae8f]
aws_instance.unmanaged_5: Modifications complete after 1s [id=i-02c648ca8076d113f]
aws_instance.unmanaged_3: Modifications complete after 1s [id=i-0f10ea0f0d579ed3d]
aws_instance.unmanaged_4: Modifications complete after 1s [id=i-0ebdff0b154a659df]
 
 
Apply complete! Resources: 6 imported, 0 added, 6 changed, 0 destroyed.

並同步顯示於 HCP Terraform 控制台。

你可以在 AWS 控制台確認變更是否生效（例如 ManagedBy 標籤已更新為 terraform，且實例名稱變更為 managed-instance-#）。

AWS 控制台呈現匯入資源後的變更結果

使用 Terraform MCP Server 生成搜尋設定

談到 Terraform Search，另一個值得關注的應用是利用 Terraform MCP Server。它能協助開發者根據組織需求，撰寫更精確且相關的 Terraform 設定。

隨著最新版本發布，使用者只需在支援 MCP 的生成式 AI 工具中輸入指令，即可自動生成搜尋設定，例如：「請幫我搜尋標籤為 unmanaged 的未受控 aws_instance 資源，並使用組織 HCP Terraform 私有註冊表（Private Registry）中的 X 模組來進行匯入管理。」

這不僅把散落在外的資源抓回來，還能確保匯入的資源直接套用公司核可的架構範本，維持架構的一致性。

溫馨提醒：清理環境
使用測試資源進行實作，結束後記得執行 terraform destroy 徹底清理環境，以免產生不必要的帳單費用。