本實驗室由我們與合作夥伴 Hashicorp 共同開發。如果您在帳戶資料中選擇接收產品更新、公告和優惠資訊，我們可能會將您的個人資訊提供給本實驗室的贊助者 Hashicorp。

GSP752

總覽

Terraform 必須保存代管基礎架構和設定的狀態資訊，以利確定實際資源與設定的對應關係、追蹤中繼資料，並在處理大型基礎架構時提升效能。

根據預設，狀態資訊會儲存在名為 terraform.tfstate 的本機檔案中，但也可以改成遠端儲存，這在團隊協作時更為方便。

Terraform 會依據本機狀態制定計畫並修改基礎架構。在執行任何作業前，Terraform 都會先重新整理，讓狀態反映實際基礎架構。

Terraform 狀態的主要用途，是連結遠端系統中的物件與設定中宣告的資源執行個體。當 Terraform 因設定變更而建立遠端物件時，會記錄該物件的識別資訊，並將其與特定資源執行個體連結；日後若設定再度變更，系統就能據此更新或刪除該物件。

目標

在本實驗室，您將學會執行下列工作：

• 建立本機後端
• 建立 Cloud Storage 後端
• 重新整理 Terraform 狀態
• 匯入 Terraform 設定
• 運用 Terraform 管理匯入的設定

設定和需求

瞭解以下事項後，再點選「Start Lab」按鈕

請詳閱以下操作說明。實驗室活動會計時，且中途無法暫停。點選「Start Lab」後就會開始計時，顯示可使用 Google Cloud 資源的時間。

您將在真正的雲端環境完成實作實驗室活動，而不是模擬或示範環境。為此，我們會提供新的暫時憑證，供您在實驗室活動期間登入及存取 Google Cloud。

為了順利完成這個實驗室，請先確認：

• 可以使用標準的網際網路瀏覽器 (Chrome 瀏覽器為佳)。

注意事項：請使用無痕模式 (建議選項) 或私密瀏覽視窗執行此實驗室，這可以防止個人帳戶和學員帳戶之間的衝突，避免個人帳戶產生額外費用。

• 是時候完成實驗室活動了！別忘了，活動一旦開始將無法暫停。

注意事項：務必使用實驗室專用的學員帳戶。如果使用其他 Google Cloud 帳戶，可能會產生額外費用。

如何開始研究室及登入 Google Cloud 控制台

1. 點選「Start Lab」按鈕。如果實驗室會產生費用，畫面上會出現選擇付款方式的對話方塊。左側的「Lab Details」窗格會顯示下列項目：

   • 「Open Google Cloud console」按鈕
   • 剩餘時間
   • 必須在這個研究室中使用的臨時憑證
   • 完成這個實驗室所需的其他資訊 (如有)

2. 點選「Open Google Cloud console」；如果使用 Chrome 瀏覽器，也能按一下滑鼠右鍵，選取「在無痕視窗中開啟連結」。

   接著，實驗室會啟動相關資源，並開啟另一個分頁，顯示「登入」頁面。

   提示：您可以在不同的視窗中並排開啟分頁。

   注意：如果頁面中顯示「選擇帳戶」對話方塊，請點選「使用其他帳戶」。

3. 如有必要，請將下方的 Username 貼到「登入」對話方塊。

   {{{user_0.username | "Username"}}}

   您也可以在「Lab Details」窗格找到 Username。

4. 點選「下一步」。

5. 複製下方的 Password，並貼到「歡迎使用」對話方塊。

   {{{user_0.password | "Password"}}}

   您也可以在「Lab Details」窗格找到 Password。

6. 點選「下一步」。

   重要事項：請務必使用實驗室提供的憑證，而非自己的 Google Cloud 帳戶憑證。 注意：如果使用自己的 Google Cloud 帳戶來進行這個實驗室，可能會產生額外費用。

7. 按過後續的所有頁面：

   • 接受條款及細則。
   • 由於這是臨時帳戶，請勿新增救援選項或雙重驗證機制。
   • 請勿申請免費試用。

Google Cloud 控制台稍後會在這個分頁開啟。

注意：如要使用 Google Cloud 產品和服務，請點選「導覽選單」，或在「搜尋」欄位輸入服務或產品名稱。

啟動 Cloud Shell

Cloud Shell 是搭載多項開發工具的虛擬機器，提供永久的 5 GB 主目錄，而且在 Google Cloud 中運作。Cloud Shell 提供指令列存取權，方便您使用 Google Cloud 資源。

1. 點按 Google Cloud 控制台頂端的「啟用 Cloud Shell」圖示 。

2. 系統顯示視窗時，請按照下列步驟操作：

   • 繼續操作 Cloud Shell 視窗。
   • 授權 Cloud Shell 使用您的憑證發出 Google Cloud API 呼叫。

連線建立完成即代表已通過驗證，而且專案已設為您的 Project_ID：。輸出內容中有一行文字，宣告本工作階段的 Project_ID：

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

gcloud 是 Google Cloud 的指令列工具，已預先安裝於 Cloud Shell，並支援 Tab 鍵自動完成功能。

3. (選用) 您可以執行下列指令來列出使用中的帳戶：

gcloud auth list

4. 點按「授權」。

輸出內容：

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. (選用) 您可以使用下列指令來列出專案 ID：

gcloud config list project

輸出內容：

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} 注意：如需 gcloud 的完整說明，請前往 Google Cloud 參閱 gcloud CLI 總覽指南。

Terraform 狀態的用途

「狀態」是 Terraform 運作的必備要素。有人會好奇，Terraform 是否能不使用狀態，改在每次執行時直接檢查雲端資源就好？事實上，即便在某些情境下能勉強不靠狀態運作，也只是把原本由狀態處理的複雜難題，交給另一套同樣繁瑣的機制而已。本節將說明 Terraform 狀態不可或缺的原因。

對應實際情況

Terraform 需要依靠某種形式的資料庫，將 Terraform 設定與實際資源相互對應。例如，當您的設定包含 resource "google_compute_instance" "foo"，Terraform 會利用此對應關係，確認該資源代表 i-abcd1234 執行個體。

Terraform 預設每個遠端物件只會綁定一個資源執行個體。這通常不成問題，因為物件是由 Terraform 建立，並在狀態中記錄識別資訊。若您改為匯入外部建立的物件，就必須確保每個物件只對應到單一資源執行個體。

如果某個遠端物件重複綁定多個資源執行個體，對應關係就會變得模糊，可能導致 Terraform 對這些物件執行預期外的操作。

中繼資料

除了追蹤資源和遠端物件的對應關係，Terraform 也必須追蹤資源依附關係等中繼資料。

Terraform 通常會依設定來判斷資源的處理順序。然而，當您從設定中移除某個資源時，Terraform 便難以判斷正確的刪除順序：系統雖能辨識原本的對應關係，並規劃刪除行動，但因為設定檔已不含該資源，僅憑設定無法確定刪除順序。

為確保正確作業，Terraform 會在狀態中保留最新的依附關係記錄。這樣一來，即使您刪除了設定中的項目，Terraform 仍能依狀態判斷正確的刪除順序。

如果 Terraform 知道各類資源的處理順序，理論上可避免此問題。例如，刪除資源時需先移除伺服器，再刪除其所屬的子網路。不過，這種做法過於複雜，很快就會變得難以管理：除了要清楚每個雲端中各種資源的刪除順序之外，Terraform 還必須掌握不同 provider 的順序關係。

基於類似理由，Terraform 也會儲存其他中繼資料。比如，若有多個具別名的 provider，Terraform 會保留一個指標，指向該資源上次使用的 provider 設定。

效能

除了基本的對應關係，Terraform 也會在狀態中快取所有資源的屬性值。這並非必要功能，存入資料純粹是為了提升效能。

執行 terraform plan 時，Terraform 必須掌握資源現況，才能有效判斷需要改動哪裡，才能達成預期設定。

對於小型基礎架構，Terraform 可以向 provider 查詢，取得所有資源的最新屬性。Terraform 的預設行為是，每次執行 plan 和 apply，都會全面更新狀態中的資源資訊。

然而，對大型基礎架構來說，逐一查詢資源實在太慢。許多雲端服務供應商並未提供能一次查詢多項資源的 API，每項資源的封包往返時間約需數百毫秒。此外，供應商幾乎都有 API 頻率限制，導致 Terraform 在單位時間內只能查詢有限數量的資源。因此，大型基礎架構的使用者常會搭配 -refresh=false 和 -target 旗標來規避限制。在這種情況下，系統會直接將快取狀態視為正確資訊。

同步處理

根據預設，Terraform 會將狀態檔案儲存在當前執行 Terraform 的工作目錄。這在入門階段或許可行，但團隊協作時，所有成員必須共用相同的狀態，才能確保對相同的遠端物件執行作業。

建議採用遠端狀態來解決問題。憑藉功能完善的狀態後端，Terraform 可以利用遠端鎖定機制，防止多名使用者同時執行 Terraform，確保每次執行均以最新狀態為基準。

狀態鎖定

若後端支援，Terraform 會在所有可能寫入狀態的作業中鎖定狀態，避免他人同時操作而導致狀態損壞。

鎖定程序會在這些作業中自動執行，過程中不會出現提示。如果鎖定失敗，Terraform 將停止執行。雖然多數指令可利用 -lock 旗標停用此功能，但不建議這麼做。

如果鎖定所需時間比預期長，Terraform 會顯示狀態訊息；若未顯示訊息，代表鎖定程序仍在進行中。

並非所有後端都支援鎖定。如想瞭解特定後端是否支援，請參閱後端類型清單。

工作區

每個 Terraform 設定都有關聯的後端，後端負責定義作業執行方式，以及 Terraform 狀態等永久資料的儲存位置。

後端儲存的永久資料隸屬於「工作區」。最初，後端只有一個名為「default」的工作區，因此每個設定預設只與一個 Terraform 狀態相關聯。

部分後端支援「多個」命名工作區，使單一設定能對應多個狀態。雖然設定仍只使用同一個後端，但您不必設定新後端或變更驗證憑證，就能部署多個執行個體。

工作 1：設定後端

Terraform 的「後端」指定了狀態載入方式，以及 apply 等作業的執行邏輯。透過這層抽象機制，系統可將狀態檔案儲存在本機以外的位置，並支援遠端執行等功能。

Terraform 預設會使用「本機」後端，這也是您平時熟悉的運作方式。在先前的實驗室中，都是透過這個後端來執行作業。

以下是使用後端的優點：

• 適合團隊協作：後端可將狀態儲存在遠端，並利用鎖定機制保護狀態，避免損壞。Terraform Cloud 等部分後端，甚至會自動保存所有狀態修訂版本。
• 避免將機密資訊寫入磁碟：系統會視需要從後端擷取狀態，並只將其暫存在記憶體中。
• 支援遠端作業：針對大型基礎架構或特定變更，執行 terraform apply 可能耗時較久。有些後端支援遠端作業，使作業可在遠端環境執行。即便您關閉電腦，作業仍會持續完成。搭配遠端狀態儲存與鎖定機制 (如上文所述)，也有助於團隊協作。

後端非強制使用：即使不學習或使用後端，也能順利操作 Terraform。然而，當團隊達到一定規模時，後端確實能解決隨之而來的痛點。如果您是獨立作業，通常不使用後端也沒問題。

即使您只打算使用「本機」後端，瞭解相關知識仍有助益，因為您可以視需要調整本機後端的運作方式。

在 Cloud Shell IDE 啟用 Gemini Code Assist

您可以在 Cloud Shell 等整合式開發環境 (IDE) 中使用 Gemini Code Assist，取得程式碼相關指引或解決程式碼問題。Gemini Code Assist 必須先啟用，才能開始使用。

1. 在 Cloud Shell 執行下列指令，啟用 Gemini for Google Cloud API：

gcloud services enable cloudaicompanion.googleapis.com

2. 點按 Cloud Shell 工具列中的「開啟編輯器」。

注意：如要開啟 Cloud Shell 編輯器，請點選 Cloud Shell 工具列中的「開啟編輯器」。如要在 Cloud Shell 與程式碼編輯器之間切換，請視需要點選「開啟編輯器」或「開啟終端機」。

3. 點選畫面底部狀態列中的「Cloud Code - No Project」。

4. 依指示授權外掛程式。如果系統未自動選取專案，請點按「選取 Google Cloud 專案」，然後選擇 。

5. 確認狀態列的 Cloud Code 狀態訊息中已顯示 Google Cloud 專案 ()。

新增本機後端

本節將說明如何設定本機後端。

第一次設定後端時 (也就是從未定義後端，到明確指定一個後端)，Terraform 會提供將目前狀態遷移至新後端的選項，讓您在採用後端的同時保留既有狀態。

為了確保萬無一失，建議您一律先手動備份狀態。只要將 terraform.tfstate 檔案複製到其他位置即可。雖然初始化過程也會自動備份，但額外備份總是更保險！

首次設定後端的流程與日後更改設定相同，都是先建立新設定，然後執行 terraform init。Terraform 會引導您完成後續步驟。

1. 在 Cloud Shell 終端機中建立 main.tf 設定檔：

touch main.tf

2. 點按 Cloud Shell 工具列上的「開啟編輯器」。

3. 將下列 Cloud Storage bucket 資源程式碼複製到 main.tf 設定檔。

provider "google" { project = "# REPLACE WITH YOUR PROJECT ID" region = "{{{project_0.default_region | REGION}}}" } resource "google_storage_bucket" "test-bucket-for-state" { name = "# REPLACE WITH YOUR PROJECT ID" location = "US" uniform_bucket_level_access = true }

4. 依序點選「檔案」>「儲存」，但不要關閉檔案。

如要進一步瞭解 Cloud Storage 資源，請參閱 Terraform 說明文件。

5. 在 IDE 中開啟 main.tf 檔案，並啟用 Gemini Code Assist 後，注意編輯器右上角會出現 圖示。

6. 點選工具列上的「Gemini Code Assist: Smart Actions」圖示 。

您可以使用 Gemini Code Assist 的 AI 功能，直接在程式碼編輯器中變更程式碼。在這個例子中，您決定讓 Gemini Code Assist 協助編輯 main.tf 設定檔的內容。

7. 將下列提示詞貼到工具列開啟的 Gemini Code Assist 內嵌文字欄位，請 Gemini Code Assist 協助編輯 main.tf 設定檔。

Update the main.tf configuration file with the following changes: * In the Google provider block, set the project to {{{project_0.project_id | PROJECT_ID}}}. * In the "test-bucket-for-state" resource block, update the name of the bucket to {{{project_0.project_id | BUCKET_NAME}}}.

8. 按下 Enter 鍵，提示 Gemini Code Assist 據此修改程式碼。

9. 在「Gemini Diff」檢視畫面出現提示時，點選「接受」。

main.tf 設定檔的內容應與下列範例類似。

provider "google" { project = "{{{project_0.project_id | PROJECT_ID}}}" region = "{{{project_0.default_region | REGION}}}" } resource "google_storage_bucket" "test-bucket-for-state" { name = "{{{project_0.project_id | BUCKET_NAME}}}" location = "US" uniform_bucket_level_access = true }

10. 在 main.tf 檔案中新增本機後端：

terraform { backend "local" { path = "terraform/state/terraform.tfstate" } }

這會參照 terraform/state 目錄中的 terraform.tfstate 檔案。如要指定其他路徑，可以修改 path 變數。

本機後端會將狀態儲存在本機檔案系統中、運用系統 API 鎖定狀態，並在本機執行作業。

對於已設定的後端，Terraform 必須將其初始化後才能使用。為此，您需要執行 terraform init。您的團隊成員在處理任何 Terraform 設定時，也都應該優先執行 terraform init 指令。這項指令可以安全重複執行，它會完成 Terraform 環境所需的一切設定，包括後端初始化。

具體來說，以下情況必須呼叫 init 指令：

• 在新環境設定後端
• 變更後端設定 (包括更換後端類型)
• 完全移除後端設定

您無需特別記住這些情況，因為 Terraform 會自動判斷何時需要初始化，適時顯示錯誤訊息。Terraform 之所以不直接初始化，是因為過程中可能需要使用者補充資訊，或涉及狀態遷移等操作。

11. 在 Cloud Shell 工具列中，按一下「開啟終端機」，然後執行下列指令來初始化 Terraform：

terraform init

12. 執行下列指令來套用變更，並在系統提示時輸入 yes 確認：

terraform apply

現在 Cloud Shell 編輯器的 terraform/state 目錄下，應會出現名為 terraform.tfstate 的狀態檔案。

13. 執行下列指令來檢查狀態檔案：

terraform show

畫面上應會顯示 google_storage_bucket.test-bucket-for-state 資源。

新增 Cloud Storage 後端

Cloud Storage 後端會將狀態以物件形式存於指定的 Cloud Storage bucket 中，並透過設定前置字串來指定儲存路徑。這個後端也支援狀態鎖定機制，每當執行可能寫入狀態的作業，都會自動鎖定狀態，避免他人同時操作而導致狀態損壞。

凡是涉及寫入狀態的作業，都會自動執行狀態鎖定，過程中不會出現提示。如果鎖定失敗，Terraform 將停止執行。雖然多數指令可利用 -lock 旗標停用此功能，但不建議這麼做。

1. 返回編輯器中的 main.tf 檔案。接著，將目前的本機後端替換成 gcs 後端。

2. 為變更現有的本機後端設定，請將下列設定複製到檔案中，取代原本的 local 後端：

terraform { backend "gcs" { bucket = "{{{project_0.project_id | BUCKET_NAME}}}" prefix = "terraform/state" } } 注意：請務必更新 bucket 的變數定義。如果設定未曾更改，名稱應與 google_storage_bucket 資源中定義的 name 相同。這個 bucket 將專門用來託管狀態檔案。

3. 執行以下指令，即可再次初始化後端，自動完成狀態遷移：

terraform init -migrate-state

在系統提示時輸入 yes 確認。

4. 在 Cloud 控制台，依序點選「導覽選單」圖示 >「Cloud Storage」>「Bucket」。

5. 按一下 bucket，找出 terraform/state/default.tfstate 檔案。現在狀態檔案已成功儲存至 Cloud Storage bucket！

注意：不想再使用後端時，只要移除檔案中的設定即可。就像處理其他變更一樣，Terraform 會自動偵測到這項異動，並提示再次執行初始化。

再次初始化時，Terraform 會詢問是否要將狀態遷移回本機。完成後，Terraform 將恢復預設運作模式。

重新整理狀態

terraform refresh 指令的作用是將 Terraform 透過狀態檔案記錄的資訊，與實際基礎架構做比對，檢查實際環境是否與上次記錄的狀態有所不同，並更新狀態檔案。

這項操作不會更動基礎架構，但會修正狀態檔案。如果狀態有變化，可能會影響下次執行 plan 或 apply 時的結果。

1. 返回 Cloud 控制台中的 Cloud Storage bucket，勾選 bucket 名稱旁的核取方塊。

2. 按一下「標籤」分頁標籤。

3. 按一下「新增標籤」。將「鍵 2」和「值 2」分別設為 key 和 value。

4. 點選「儲存」。

5. 返回 Cloud Shell，並使用下列指令更新狀態檔案：

terraform refresh

6. 執行下列指令來檢查更新：

terraform show

在設定的 labels 屬性中，應會顯示 "key" = "value" 鍵/值組合。

點選「Check my progress」，確認目標已達成。 設定後端

清理工作區

請先刪除佈建的基礎架構，再繼續下一個工作。

1. 首先，將後端還原為 local，以便刪除 Cloud Storage bucket。將下列設定複製到檔案中，取代原本的 gcs 設定：

terraform { backend "local" { path = "terraform/state/terraform.tfstate" } }

2. 執行下列指令，再次初始化 local 後端：

terraform init -migrate-state

在系統提示時輸入 yes 確認。

3. main.tf 檔案開啟時，注意編輯器右上角會出現 圖示。

接著，使用 Gemini Code Assist 修改 Terraform 設定，在用於刪除 Cloud Storage bucket 資源的程式碼中加入引數。

4. 點選工具列上的「Gemini Code Assist: Smart Actions」 圖示。

5. 將下列提示詞貼到工具列開啟的 Gemini Code Assist 內嵌文字欄位，請 Gemini Code Assist 協助修改 main.tf 設定檔

Update the google_storage_bucket resource named "test-bucket-for-state" in the main.tf file. Add the force_destroy = true argument to its configuration.

刪除 bucket 時，這個布林值選項可用於刪除其中所有物件。若嘗試刪除含有物件的 bucket，Terraform 將無法執行。

6. 按下 Enter 鍵，提示 Gemini Code Assist 據此修改程式碼。

7. 在「Gemini Diff」檢視畫面出現提示時，點選「接受」。

main.tf 設定檔的內容應與下列範例類似。

resource "google_storage_bucket" "test-bucket-for-state" { name = "{{{project_0.project_id | BUCKET_NAME}}}" location = "US" uniform_bucket_level_access = true force_destroy = true }

8. 執行下列指令來套用變更：

terraform apply

在系統提示時輸入 yes 確認。

9. 現在您可以順利刪除基礎架構。請執行下列指令：

terraform destroy

在系統提示時輸入 yes 確認。

工作 2：匯入 Terraform 設定

在本節中，您會將現有的 Docker 容器和映像檔匯入空的 Terraform 工作區，並瞭解將既有基礎架構匯入 Terraform 時，應採取的策略與注意事項。

Terraform 的預設工作流程，是完全透過 Terraform 來建立與管理基礎架構。

• 撰寫 Terraform 設定，定義想建立的基礎架構

• 檢查 Terraform 計畫，確保執行後產生的基礎架構與狀態皆符合預期

• 套用設定，建立 Terraform 狀態和基礎架構

運用 Terraform 建立基礎架構後，您可以更新設定，並透過 plan 和 apply 實作變更。不再需要這些資源時，最終也能使用 Terraform 將其刪除。這套工作流程的前提，是預設會由 Terraform 建立全新的基礎架構。

然而，您可能也會需要管理非由 Terraform 建立的基礎架構。這時就能利用 terraform import 指令來解決問題，將支援的資源載入 Terraform 工作區的狀態中。

不過，import 指令並不會自動產生管理基礎架構的設定，因此需要經過多個步驟，才能將既有基礎架構匯入 Terraform。

如要將既有基礎架構移至 Terraform 管理，主要有五個步驟：

• 確認要匯入的基礎架構
• 將該基礎架構匯入 Terraform 狀態
• 撰寫與該基礎架構相符的 Terraform 設定
• 檢查 Terraform 計畫，確認設定與預期的狀態和基礎架構相符
• 套用設定以更新 Terraform 狀態

在本節中，您將先使用 Docker CLI 建立 Docker 容器，接著將容器匯入新的 Terraform 工作區，並使用 Terraform 更新容器設定，等到操作完成後，再將容器刪除。

警告：匯入基礎架構會影響 Terraform 狀態，若處理不當，可能導致既有的 Terraform 專案失效。因此，在對實際專案執行 import 指令前，請務必備份並妥善保存 terraform.tfstate 檔案和 .terraform 目錄。

建立 Docker 容器

1. 執行下列指令，運用 Docker Hub 上最新的 NGINX 映像檔建立名為 hashicorp-learn 的容器，然後透過 Cloud Shell 虛擬機器的通訊埠 80 (HTTP) 預覽該容器：

docker run --name hashicorp-learn --detach --publish 8080:80 nginx:latest

2. 執行下列指令，確認容器正在運作：

docker ps

3. 在 Cloud Shell 窗格，依序點選「網頁預覽」和「透過以下通訊埠預覽：8080」。

Cloud Shell 會透過 Proxy 服務，在新的瀏覽器視窗中開啟預覽網址，並顯示 NGINX 預設索引頁面。備妥 Docker 映像檔與容器後，您就可以將這些資源匯入工作區，開始用 Terraform 管理。

將容器匯入 Terraform

1. 執行下列指令，複製範例存放區：

git clone https://github.com/hashicorp/learn-terraform-import.git

2. 執行下列指令，切換至該目錄：

cd learn-terraform-import

3. 更新 terraform.tf 檔案中的 provider 版本：

sed -i 's/version = "~> 3.0.2"/version = ">= 3.5"/' terraform.tf

這個目錄包含兩個 Terraform 設定檔，也就是您將在本指南後續步驟中使用的設定：

• main.tf 檔案會設定 Docker provider。
• docker.tf 檔案包含管理前述步驟中所建 Docker 容器的必要設定。

4. 執行下列指令，初始化 Terraform 工作區：

terraform init --upgrade 注意：如果出現類似「Error: Failed to query available provider packages」的錯誤訊息，請執行下列指令：terraform init -upgrade

5. 在 Cloud Shell 編輯器中，前往 learn-terraform-import/main.tf。

6. 找出 provider: docker 資源，然後註解排除或刪除 host 引數：

provider "docker" { # host = "npipe:////.//pipe//docker_engine" } 注意：我們已知 Docker 初始化錯誤會引發問題，這是目前的因應措施。

7. 接著前往 learn-terraform-import/docker.tf。

8. 到剛才註解排除的程式碼下方，在 docker.tf 檔案中定義空的 docker_container 資源，代表具有 Terraform 資源 ID docker_container.web 的 Docker 容器：

resource "docker_container" "web" {}

9. 找到要匯入容器的名稱。在這個案例中，就是您在上一步建立的容器：

docker ps

10. 執行下列 terraform import 指令，將現有的 Docker 容器連接至剛剛建立的 docker_container.web 資源。執行匯入時，必須提供這個 Terraform 資源 ID 和完整的 Docker 容器 ID。執行 docker inspect -f {{.ID}} hashicorp-learn 指令，即可傳回完整的 SHA256 容器 ID：

terraform import docker_container.web $(docker inspect -f {{.ID}} hashicorp-learn) 注意：terraform import 接受的 ID 因資源類型而異。只要是支援匯入的資源，相關的 provider 文件中都會詳細說明。就本範例而言，請參閱 Docker provider 說明文件。

11. 執行下列指令，確認容器已匯入 Terraform 狀態：

terraform show

這份狀態資料包含 Terraform 對剛匯入的 Docker 容器掌握的所有資訊。不過，terraform import 指令並不會自動建立資源設定。

建立設定

您需要先建立 Terraform 設定，才能使用 Terraform 管理容器。

1. 執行下列程式碼：

terraform plan 注意：由於缺少必要的 image 和 name 引數，Terraform 會顯示錯誤訊息。若資源缺少這些必要引數，Terraform 將無法產生相關計畫。

如要讓 docker.tf 設定符合匯入狀態，有兩種做法：直接將資源目前的完整狀態原封不動地寫入設定，或是逐一挑選必要的屬性。這兩種做法各有適合使用的情境。

• 直接使用目前狀態通常比較快速，但由於狀態中包含所有屬性 (無論是否必要)，可能導致設定過於冗長。

• 逐一選取必要屬性則較易於後續管理，但您必須先瞭解需要設定哪些屬性。

在本實驗室中，您將採用資源目前的狀態來設定。

2. 將 Terraform 狀態複製到 docker.tf 檔案：

terraform show -no-color > docker.tf 注意：使用 > 符號會將 docker.tf 的內容全部替換為 terraform show 指令的輸出內容。雖然在本範例中可行，但若要在已管理其他資源的設定中匯入資源，就需要編輯 terraform show 的輸出內容，移除不想完全取代的資源設定，並將新資源併入現有設定。

3. 檢查 docker.tf 檔案，確認內容已替換成剛剛執行的 terraform show 指令輸出內容。

4. 執行下列程式碼：

terraform plan

Terraform 會針對已淘汰的引數 (「links」) 和多個唯讀引數 (ip_address、network_data、gateway、ip_prefix_length、id) 顯示警告和錯誤訊息。

這些唯讀引數是 Terraform 在狀態中儲存的 Docker 容器資訊，但因為是由 Docker 內部管理，所以您無法透過設定指定。至於 links 引數，雖然目前仍能在設定中指定，但本身已遭淘汰，未來的 Docker provider 版本可能不再支援，因此 Terraform 仍會顯示警告。

由於這裡示範的做法會載入 Terraform 狀態中的所有屬性，因此設定會包含一些數值與預設值相同的選用屬性。至於哪些屬性為選用、預設值分別為何，則因 provider 而異，詳情請參閱 provider 說明文件。

5. 現在可以視需要移除這些選用屬性了。請將這些屬性全部移除，只保留必要的 image、name 和 ports。完成後，設定應如下所示：

輸出內容：

resource "docker_container" "web" { image = "sha256:87a94228f133e2da99cb16d653cd1373c5b4e8689956386c1c12b60a20421a02" name = "hashicorp-learn" ports { external = 8080 internal = 80 ip = "0.0.0.0" protocol = "tcp" } }

匯入實際的基礎架構時，建議先參閱 provider 說明文件，瞭解各引數的用途。如此一來，若在執行 plan 時出現錯誤或警告，也能判斷該如何處理。舉例來說，您可以在 Docker provider 說明文件中找到關於 links 引數的詳細資訊。

6. 執行下列指令，確認錯誤已排除：

terraform plan

此時應該可以順利執行 plan。請注意，plan 會顯示 Terraform 將要更新容器，加入 attach、logs、must_run 和 start 屬性。

雖然 Terraform 在建立 Docker 容器時會用到這些屬性，但 Docker 本身並不會儲存這些資訊，所以 terraform import 無法將這些屬性值載入狀態。後續執行 plan 與 apply 時，Docker provider 會自動幫這些屬性帶入預設值並存入狀態，但這不會影響正在運作的容器。

7. 執行下列指令，套用變更，讓更新的 Terraform 設定與狀態，能與對應的 Docker 容器保持同步。在系統提示時輸入 yes 確認。

terraform apply

設定檔、Terraform 狀態和容器均已完成同步後，您就能像平常一樣，直接使用 Terraform 來管理這個容器。

建立映像檔資源

某些時候，不一定要使用 terraform import 指令，也能將資源納入 Terraform 的管理範圍。像 Docker 映像檔這類只由單一專屬 ID 或標籤定義的資源，通常就適用這種方式。

在 docker.tf 檔案中，docker_container.web 資源標註了建立容器時所用映像檔的 SHA256 雜湊 ID。由於 Docker 內部是以這種方式儲存映像檔 ID，因此 terraform import 會直接將該 ID 載入狀態中。然而，映像檔 ID 並不像標記或名稱那樣易於辨識，也可能不符合您的實際需求。例如，您可能更偏好使用最新版的「nginx」映像檔。

1. 如要擷取映像檔的標記名稱，請執行下列指令，並將 <IMAGE-ID> 替換為 docker.tf 中的映像檔 ID：

docker image inspect <IMAGE-ID> -f {{.RepoTags}}

2. 在 docker.tf 檔案中新增以下設定，表示此映像檔屬於資源：

resource "docker_image" "nginx" { name = "nginx:latest" } 注意：暫時不要替換 docker_container.web 資源中的映像檔值，否則 Terraform 會刪除再重建容器。由於 Terraform 尚未將 docker_image.nginx 資源載入狀態，因此無法與硬式編碼的映像檔 ID 做比對，這會讓 Terraform 判定必須更換容器。為避免這種情況，請依照實驗室示範的做法，先建立映像檔再更新容器，使用該映像檔。

3. 執行下列指令，將映像檔資源加入狀態。在系統提示時輸入 yes 確認。

terraform apply

Terraform 建立好映像檔資源後，您就能在容器設定中參照該資源。於是，您決定請 Gemini Code Assist 幫忙。

4. docker.tf 檔案開啟時，注意編輯器右上角會出現 圖示。

5. 點選工具列上的「Gemini Code Assist: Smart Actions」圖示 。

6. 將下列提示詞貼到工具列開啟的 Gemini Code Assist 內嵌文字欄位，修改 docker.tf 檔案中 docker_container.web 的映像檔值，改成參照新的映像檔資源。

Update the image argument in the docker_container resource named web within the docker.tf file. Set its value to docker_image.nginx.image_id.

7. 按下 Enter 鍵，提示 Gemini Code Assist 據此修改程式碼。

8. 在「Gemini Diff」檢視畫面出現提示時，點選「接受」。

docker.tf 設定檔的內容應與下列範例類似。

resource "docker_container" "web" { image = docker_image.nginx.image_id name = "hashicorp-learn" ports { external = 8080 internal = 80 ip = "0.0.0.0" protocol = "tcp" } }

9. 執行下列指令，查看是否有變更。在系統提示時輸入 yes 確認。

terraform apply

由於 docker_image.nginx.latest 的值與先前替換的硬式編碼映像檔 ID 相符，所以此時執行 terraform apply 不會顯示任何變更。

注意：從最初建立 Docker 容器，到執行這項指令的期間，如果「nginx:latest」標記對應的映像檔 ID 曾經變動，系統會刪除舊容器，並使用新的映像檔重新建立。

運用 Terraform 管理容器

既然 Docker 容器已由 Terraform 管理，您就可以透過 Terraform 變更設定。

1. 在 docker.tf 檔案中，將容器的對外通訊埠從 8080 改成 8081：

resource "docker_container" "web" { name = "hashicorp-learn" image = docker_image.nginx.image_id ports { external = 8081 internal = 80 ip = "0.0.0.0" protocol = "tcp" } }

2. 執行下列指令，套用變更：

terraform apply

在系統提示時輸入 yes 確認。

Terraform 會刪除容器，並使用新的通訊埠設定，重新建立容器。

3. 執行下列指令，確認已換成使用新設定的容器：

docker ps

您會發現容器 ID 已變更。這是因為變更通訊埠設定時，必須先刪除舊容器，再重建一個全新容器。

刪除基礎架構

您已將 Docker 容器和用來建立容器的映像檔匯入 Terraform。

1. 執行下列指令，刪除容器和映像檔：

terraform destroy

在系統提示時輸入 yes 確認。

2. 執行下列指令，確認容器已刪除：

docker ps --filter "name=hashicorp-learn" 注意：由於您已將映像檔同時加入 Terraform 設定與容器中，系統會一併從 Docker 和容器中移除該映像檔。如有其他容器正在使用同一映像檔，刪除作業就會失敗。提醒您，一旦將資源匯入，Terraform 就會接管資源的完整生命週期，其中也包含刪除操作。

限制和其他注意事項

將資源匯入 Terraform 時，務必考量一些重要事項。

執行匯入時，系統只能得知 Terraform provider 回報的基礎架構當前狀態，無法掌握以下資訊：

• 基礎架構是否正常運作
• 基礎架構的設計意圖
• 不在 Terraform 控制下的基礎架構異動，例如 Docker 容器檔案系統的狀態異動

匯入過程需要手動操作，因此容易出錯。若操作者不清楚資源當初建立時的背景與原因，風險會更高。

由於匯入操作會改動 Terraform 狀態檔案，建議在匯入新的基礎架構前建立備份。

Terraform 在執行匯入時，無法自動偵測或建立基礎架構之間的關聯。

對於無需手動設定的預設屬性，Terraform 不會主動偵測。

部分 provider 和資源不支援匯入 Terraform。

將基礎架構匯入 Terraform，並不代表能直接由 Terraform 執行刪除和重建。比如，匯入的基礎架構可能會依賴非代管的其他基礎架構或設定。

遵循基礎架構即程式碼 (IaC) 最佳做法 (例如「不可變基礎架構」) 可以避免許多這類問題，但手動建立的基礎架構通常無法遵循這些做法。

Terraformer 等工具可自動化匯入基礎架構的某些手動步驟，但這些工具不屬於 Terraform，HashiCorp 也未提供背書或支援。

恭喜！

在本實驗室中，您已學會如何在 Gemini Code Assist 的協助下，利用 Terraform 管理後端和狀態。您建立了本地及 Cloud Storage 後端來管理狀態檔，並完成狀態更新與設定匯入。最後，更透過更新設定與手動調整，成功讓 Terraform 全面接管 Docker 容器。

後續步驟/瞭解詳情

建議參考以下資源，獲得更多 Terraform 實作練習機會：

• Google Cloud Marketplace 中的 Hashicorp！
• Hashicorp Learn
• Terraform 社群
• Terraform Google 範例

Google Cloud 教育訓練與認證

協助您瞭解如何充分運用 Google Cloud 的技術。我們的課程會介紹專業技能和最佳做法，讓您可以快速掌握要領並持續進修。我們提供從基本到進階等級的訓練課程，並有隨選、線上和虛擬課程等選項，方便您抽空參加。認證可協助您驗證及證明自己在 Google Cloud 技術方面的技能和專業知識。

使用手冊上次更新日期：2025 年 12 月 2 日

實驗室上次測試日期：2025 年 12 月 2 日

Copyright 2026 Google LLC 保留所有權利。Google 和 Google 標誌是 Google LLC 的商標，其他公司和產品名稱則有可能是其關聯公司的商標。