我用 Terraform 接管了在 AWS 主控台手動建立的 AWS production 環境 — 保留各項 AWS 資源的名稱,並在 CI 擋下 Terraform 可能意外導致的刪除

用 Terraform import 區塊把在 AWS 主控台手動建立的資料層交給 Terraform 管理,並保留各項 AWS 資源原本的名稱。production 環境由我手動套用,套用前會先檢查 plan,只要有 AWS 資源會被刪除就會中止。

白底上由四個紫色平行四邊形組成 T 字的 Terraform 標誌,旁邊是近黑色的 Terraform 字樣
本頁目錄

引言

我參與開發的一個 AWS 資料層分成測試帳戶和 production 環境,其中測試帳戶是用 Terraform 建立的。建立時使用的模組,是我以唯讀方式擷取 production 的設定之後寫成的。詳細的做法寫在我之前寫的 Terraform 重建文章裡。那篇文章也提到,之後要讓 production 也使用同一個模組時,「只需要新增一個 tfvars 檔案」。

但 production 本身仍然是在主控台手動建立、手動修改的。我希望 production 也由同一個模組定義,並且由我手動啟動套用。但是當我第一次對 production 執行唯讀的 terraform plan 時,plan 竟然列出有 7 個資源要被刪除,這是因為主控台給這些資源取的名稱和模組產生的名稱不同。

現在,在 production 套用 Terraform 時會匯入既有的資源,並保留各項 AWS 資源原本的名稱。兩個帳戶都改由 Terraform 管理,合併到 main 時會部署到測試環境;只有透過手動啟動的 workflow 才會部署到 production,而且這個 workflow 會拒絕任何會刪除 AWS 資源的 plan。

一個模組、兩個 root、兩種套用方式

兩個帳戶使用同一個資料層模組,但各自有自己的 root 目錄和 state。state 是 Terraform 記錄自己管理了哪些資源的檔案;每個 root 各有一份,所以兩個帳戶的資源不會混在一起。root 是執行 terraform plan 的目錄,裡面放了三樣東西:

  1. backend:指定 state 存放的位置,例如 S3 bucket。
  2. provider:設定 Terraform 要操作的 AWS 帳戶,每個 root 只指向其中一個帳戶。
  3. module 區塊:呼叫資料層模組,並傳入這個帳戶專用的值。
terraform/
modules/
bootstrap/ state bucket 與 GitHub Actions 的 role,兩個帳戶共用
data-layer/ S3、Glue、OpenSearch Serverless、Bedrock knowledge base、Lambda、AgentCore
bootstrap/
test/
prod/
envs/
test/ main.tf
prod/ main.tf, imports.tf

production 的 root 和測試帳戶的 root 只有兩個地方不同:

  1. imports.tf:把模組裡的資源對應到 production 已經存在的資源。
  2. main.tf:把這些資源在主控台原本的名稱傳給模組。

每個 pull request 都會為兩個帳戶各執行一次 plan。pull request 合併到 main 時會套用到測試帳戶;production 則只有在我手動啟動 workflow 時才會套用。如果 plan 裡有任何資源會被刪除,production 的這次執行就會在套用任何東西之前失敗。

因此,如果在主控台修改了 production,下一個 pull request 的 production plan 就會把這項修改列成和程式碼之間的差異。下一次套用到 production 時,這項修改會被改回程式碼的設定;如果改回去需要刪除資源,刪除檢查就會中止這次執行。

pull request 會對兩個帳戶執行 plan,合併後套用到測試帳戶;production 只有在手動啟動、而且通過刪除檢查時才會套用三條泳道。任何分支的 pull request 都會對測試和 production 帳戶執行 terraform plan,並把結果貼成留言,不會套用任何變更。合併到 main 後,job 在只從 main 部署的 test environment 中執行,自動套用到測試帳戶。production 環境只有在手動啟動 workflow、並把 target 設為 prod 時才會套用。job 在同樣只從 main 部署的 prod environment 中把 plan 存成 tfplan,只要有任何資源會被刪除,刪除檢查就讓執行失敗,否則把存下的 plan 套用到 production 帳戶。Pull request任何分支對測試和 production 帳戶執行 terraform plan只貼成 PR 留言,不套用合併到 main自動environment:test只從 main 部署terraform apply測試帳戶手動執行target: prodenvironment:prod只從 main 部署plan -out=tfplan刪除檢查apply tfplanproduction 帳戶有刪除就失敗
每個 pull request 都會對兩個帳戶執行 plan。合併之後會套用到測試帳戶。production 只有在我從 main 手動啟動 workflow 時才會套用,而且存下的 plan 必須先通過刪除檢查。

用唯讀的 plan 預演接管 production 上的資源

只要結合 import 區塊和本機 backend,terraform plan 就能顯示套用後 production 上的資源會發生什麼變化,而且在這個階段還不會改變 production 上的任何資源。import 區塊會寫明一個既有的資源,以及這個資源在模組中要對應到的位址。plan 會讀取實際運行中的資源,和 Terraform 的設定比對,並在真正匯入之前列出差異。

我呼叫 AWS 的 List、Get 和 Describe 類 API,收集了各資源的 ID,並替每個資源寫了一個 import 區塊。結構重複的資源則用 for_each 一次處理:

terraform/envs/prod/imports.tf
import {
to = module.data_layer.aws_bedrockagent_knowledge_base.this["handbook"]
id = "KBID000001"
}
import {
to = module.data_layer.aws_bedrockagent_data_source.this["handbook"]
id = "DSID000001,KBID000001"
}
import {
for_each = local.buckets
to = module.data_layer.aws_s3_bucket.this[each.key]
id = each.value
}

production 的 main.tf 把 state 設定存放在一個 S3 bucket 裡,但這個 bucket 當時還不存在,所以 terraform plan 根本無法執行;而且預演本來就不該把 state 寫進 production。

如果添加名稱以 _override.tf 結尾的檔案,Terraform 會優先拿它的內容覆蓋其他檔案裡的同一段設定,而且覆寫檔案裡的 backend 區塊會優先於原本的 backend 區塊。所以只要放一個暫時的覆寫檔案,就能讓 state 改存到本機磁碟,完全不用動到 main.tf,自然也就不需要 S3 bucket 了:

terraform/envs/prod/zz_local_override.tf
terraform {
backend "local" {
path = "/tmp/prod-rehearsal.tfstate"
}
}

使用 production 的憑證執行時,plan 會讀取每一個資源,但不會改動帳戶裡的任何東西:

終端機視窗
輸入
aws-vault exec prod -- terraform -chdir=terraform/envs/prod plan -lock=false
輸出
Plan: 44 to import, 17 to add, 23 to change, 7 to destroy.
我用 import 區塊、本機 state 的覆寫檔案和 production 的憑證執行 plan,plan 只讀取 production 環境三個輸入交給 terraform plan:為每個既有資源寫了 import 區塊的 imports.tf、讓 state 放在本機磁碟的 zz_local_override.tf,以及只用來讀取的 production 環境憑證。plan 透過 List、Get 和 Describe 呼叫讀取 production 帳戶,不寫入任何東西。輸出是實際套用時會做的變更:44 個 import、新增 17 個、變更 23 個、刪除 7 個。imports.tf每個既有資源一個 import 區塊zz_local_override.tfstate 放在本機磁碟production 的憑證只用來讀取terraform plan-lock=falseproduction 帳戶List / Get / Describe不寫入任何東西實際套用時會做的變更Plan: 44 to import, 17 to add,23 to change, 7 to destroy.
import 區塊指定既有的資源,覆寫檔案把 state 留在本機,plan 只讀取 production。plan 的結果列出了真正套用時會做的變更。

等 production 的 state bucket 建好之後,我刪除了覆寫檔案,這樣同一個指令就會改用 S3 backend 存放 state 了。

為什麼 plan 要替換 7 個資源?

7 個要替換的資源裡,有 6 個是因為名稱不同。我在 AWS 主控台建立這些資源時,主控台自動產生了名稱,而模組則依自己的規則組出的是另一個名稱。另外有一條 inline policy,因為它所屬的 role 要被替換,所以也跟著被替換。

Terraform 無法直接把 knowledge base 的資料來源或 IAM role 改名。只要名稱不同,Terraform 就只能先建立一個新的資源,再刪除舊的:

# module.data_layer.aws_bedrockagent_data_source.this["catalog"] must be replaced
~ name = "knowledge-base-quick-start-xxxxx-data-source" -> "app-catalog-s3" # forces replacement
# module.data_layer.aws_iam_role.kb["catalog"] must be replaced
~ name = "AmazonBedrockExecutionRoleForKnowledgeBase_xxxxx" -> "app-kb-catalog" # forces replacement
資源替換數量替換的代價
knowledge base 的資料來源2資料來源 ID 會改變,所有文件都要重新同步到 knowledge base
knowledge base、Lambda 和 gateway 的 IAM role4新的 role 會先建立,其他資源之後才改為指向它,所以在切換生效之前,呼叫可能會因為 AccessDenied 而失敗
Lambda role 的 inline policy1跟著它的 role 一起重建

其中一個 knowledge base 帶有模組沒有宣告的 aws-apn-id 標籤,所以 plan 裡也列出了移除這個標籤的變更。plan 還把 AgentCore 的 service-linked role 列為要新建立的資源,但 production 裡已經有一個了,所以套用原本會在建立它時失敗。

依照 knowledge base 名稱命名的資料來源

模組原本會用 knowledge base 的名稱,組出每個資料來源的名稱。後來我在主控台替一個 knowledge base 改了名,並把模組裡的名稱也改成新名稱。knowledge base 本身可以直接改名,所以 plan 只把它列為原地更新。但資料來源的名稱是從 knowledge base 的名稱組出來的,也跟著變了;資料來源無法直接改名,所以 plan 把它列為要替換的資源。

我讓每個資料來源改用自己的固定名稱,不再從 knowledge base 的名稱組出來:

modules/data-layer/bedrock_kb.tf
resource "aws_bedrockagent_data_source" "this" {
name = "${replace(each.value.name, "_", "-")}-s3"
name = each.value.data_source_name
# …
}

改完之後,測試帳戶的 plan 就從 1 to add, 1 to change, 1 to destroy 變成了 0 to add, 1 to change, 0 to destroy。

用 existing_names 保留主控台的名稱

我加了一個選填的變數,用來存放主控台取的名稱;當這個變數沒有值時,模組就照自己的規則產生名稱。測試帳戶不傳入任何值,所以沿用原本的名稱;production 則傳入主控台裡原本的名稱:

modules/data-layer/variables.tf
variable "existing_names" {
type = object({
data_sources = optional(map(string), {})
kb_roles = optional(map(string), {})
reviewer_role = optional(string)
gateway_role = optional(string)
})
default = {}
}
modules/data-layer/bedrock_kb.tf
resource "aws_iam_role" "kb" {
name = lookup(var.existing_names.kb_roles, each.key, "${local.prefix}-kb-${each.key}")
# …
}
用 existing_names 保留主控台給的名稱,role 會被 import 而不是被替換production 環境中有一個 IAM role,主控台把它命名為 AmazonBedrockExecutionRoleForKnowledgeBase_xxxxx。左側是模組的命名規則,產生的名稱 app-kb-catalog 和實際名稱不同,所以 plan 會強制替換:建立新的 role,刪除舊的。右側由 existing_names 原封不動地傳入主控台的名稱,所以 import 會把這個 role 納入管理,plan 只會原地更新它。在主控台手動建立的 production IAM roleAmazonBedrockExecutionRoleForKnowledgeBase_xxxxx和實際存在的 role 名稱比較模組的命名規則app-kb-catalog名稱不同:強制替換建立新的 role,刪除舊的existing_namesAmazonBedrockExecutionRoleForKnowledgeBase_xxxxx名稱相同:直接 import納入管理,原地更新
用模組自己的名稱會強制替換。透過 existing_names 傳入主控台裡原本的名稱,import 就能把資源原地納入管理。

剩下的兩個問題,也就是 aws-apn-id 標籤會被移除、service-linked role 會被重複建立,各只需要一行就能解決。在 knowledge base 上加上 ignore_changes = [tags["aws-apn-id"]],Terraform 就不會去動那個標籤;替 service-linked role 寫一個 import 區塊,它就從新建改成匯入既有的 role。

終端機視窗
輸入
aws-vault exec prod -- terraform -chdir=terraform/envs/prod plan -lock=false
輸出
Plan: 45 to import, 9 to add, 28 to change, 0 to destroy.

這 9 個新增都不會改動任何既有的東西,內容分成四類:

  1. 納入管理的 role 上的三條 inline policy
  2. 同樣在這些 role 上的兩個 policy attachment
  3. 一條新的 OpenSearch data access policy
  4. 確認 index 存在的 terraform_data,以及接在它後面的 time_sleep

測試帳戶的 plan 仍然輸出 No changes. Your infrastructure matches the configuration.。

為什麼我保留了資源的舊名稱?

當初做決定時,考量的是切換期間權限會中斷一段時間。改用模組的名稱,代表 Terraform 要先建立每個新的 role,把 knowledge base、Lambda 或 gateway 指向它,再刪除舊的 role。在這段期間,任何呼叫都可能失敗。

不過,保留名稱也有代價。每個納入管理的 role 都同時帶著主控台附加的 managed policy 和模組的 inline policy,同樣的權限有了兩份。我把這一點加進了快照差異比對指令碼的預期差異清單(EXPECTED_DIFFS),並註明了原因。

手動套用 Terraform 到 production,並先進行刪除檢查

production 只有在我用 target: prod 手動觸發 workflow_dispatch 時才會套用,而且 job 套用的就是它檢查過的那份 plan。workflow_dispatch 是 GitHub Actions 用來手動啟動 workflow 的觸發條件。target 設成選擇式輸入、預設為 test,所以測試帳戶原本的流程不受影響:

.github/workflows/terraform.yml
on:
workflow_dispatch:
inputs:
target:
description: apply する環境
type: choice
options: [test, prod]
default: test
jobs:
apply-prod:
if: github.event_name == 'workflow_dispatch' && inputs.target == 'prod'
environment: prod
env:
TF_DIR: terraform/envs/prod

GitHub 的 Run workflow 對話框,分支選了 main,target 輸入選了 prod

在 main 上手動執行 workflow,並把 target 選成 prod。

prod environment 只能從 main 部署。這個限制是用 deployment branch policy 設定的,做法和我之前寫的 Terraform 重建文章替 test 設定的一樣。這個 environment 沒有設定必要的審查者,所以套用前不需要任何人核准。AWS 的 apply role 只信任來自 prod environment 的 OIDC token(token 的 subject 必須指向這個 environment)。

刪除檢查會把存下的 plan 讀成 JSON,只要有任何資源的 actions 包含 delete,就會失敗。Terraform 的 JSON 格式會把替換寫成 ["delete", "create"] 或 ["create", "delete"]。官方說明文件寫明,採用這種形式,就是為了讓呼叫端只要搜尋 delete,就能抓到三種會刪除資源的情況:

  • ["delete"]:只刪除資源。
  • ["delete", "create"]:替換資源,先刪除舊的再建立新的,這是 Terraform 的預設做法。
  • ["create", "delete"]:替換資源,先建立新的再刪除舊的,用於設定了 create_before_destroy 的資源。

workflow 裡的檢查是這樣寫的:

.github/workflows/terraform.yml
- name: terraform plan
run: terraform -chdir="$TF_DIR" plan -input=false -no-color -lock-timeout=10m -out=tfplan
- name: Refuse deletes and replacements
run: |
terraform -chdir="$TF_DIR" show -json tfplan > plan.json
jq -r '.resource_changes[] | select(.change.actions | index("delete")) | "\(.change.actions | join("/")) \(.address)"' plan.json > destructive.txt
if [ -s destructive.txt ]; then
echo "::error::refusing to apply a plan that deletes or replaces resources"
cat destructive.txt
exit 1
fi
- name: terraform apply
run: terraform -chdir="$TF_DIR" apply -input=false -no-color -lock-timeout=10m tfplan

套用 tfplan 而不是重新執行 plan,代表變更的只會是通過檢查的那份 plan 裡列出的資源。如果在 plan 和套用之間 state 有了變動,Terraform 會拒絕套用這份已經過時的 plan。

我把負責建立 state bucket 和兩個 GitHub role 的 bootstrap root,改寫成共用模組 modules/bootstrap。把測試帳戶的資源搬進這個模組,用了 13 個 moved 區塊。moved 區塊會告訴 Terraform,資源只是換了位址,並不是換成了另一個資源。測試帳戶的 bootstrap 因此規劃出 0 to add, 0 to change, 0 to destroy,production 的 bootstrap 則新建立了 13 個資源。

第一次套用 production 時卡在了兩個 OpenSearch security policy

第一次執行匯入了全部 45 個資源並套用了大部分的更新,但是在 OpenSearch Serverless 的兩個 security policy 上失敗了:

Error: updating OpenSearch Serverless Security Policy
with module.data_layer.aws_opensearchserverless_security_policy.encryption,
on ../../modules/data-layer/opensearch.tf line 10, in resource "aws_opensearchserverless_security_policy" "encryption":
10: resource "aws_opensearchserverless_security_policy" "encryption" {
ID: <collection-name>
Cause: operation error OpenSearchServerless: UpdateSecurityPolicy, ,
ValidationException: No changes detected in policy or policy description"

這是因為主控台替這兩個 policy 都填了描述(description 欄位),模組卻沒有宣告任何描述。於是 Terraform 送出了一個更新把描述清空,policy 本身則沒有改變。OpenSearch Serverless 的 UpdateSecurityPolicy API 認為這個請求沒有任何變更,因此拒絕了它。更新不算刪除,所以刪除檢查放行了這份 plan。

沒有任何東西被刪除,已經成功的部分也都保留了下來。Terraform 是以資源為單位套用的。role、security group 規則、Glue 資料表和 Lambda 的更新都已經完成,依賴 OpenSearch Serverless collection 的資源則還沒有開始套用。

第一次套用到 production 環境時卡在了 security policy,之前的部分都已套用;第二次完成了剩下的部分兩次套用的時間軸,橫跨四個階段:import;role、security group 規則、S3、Glue 和 Lambda;OpenSearch 的 security policy;collection、knowledge base 和 index。第 1 次 import 了 45 個資源並更新了第二個階段,接著在 security policy 上因為描述而出現 ValidationException 錯誤,最後一個階段沒有開始。為描述加上 ignore_changes 後,第 2 次執行時前兩個階段已在 state 中、沒有變更,security policy 不再更新,最後一個階段以新增 5、變更 3、刪除 0 完成。importrole、SG 規則、S3、Glue、Lambdasecurity policycollection、KB、index第 1 次import 了 45 個已更新ValidationException描述尚未開始第 2 次已在 state 中沒有變更忽略描述不更新新增 5、變更 3刪除 0ignore_changes = [description]
第一次執行卡在了兩個 security policy,在這之前的部分都已套用。改成忽略主控台填的描述之後,第二次執行完成了剩下的部分。

我不再讓 Terraform 管理這些描述,範圍包括這兩個 policy,以及主控台同樣填了描述的 collection:

modules/data-layer/opensearch.tf
resource "aws_opensearchserverless_security_policy" "encryption" {
name = local.collection_name
type = "encryption"
policy = jsonencode({ /* 規則與金鑰設定,此處省略 */ })
# 主控台填了描述;把它清空的更新會被 UpdateSecurityPolicy API 拒絕。
lifecycle {
ignore_changes = [description]
}
}

pull request 的 production plan 列出了剩下的變更,第二次執行把它們套用完成:

Apply complete! Resources: 5 added, 3 changed, 0 destroyed.

第二次套用完成後,再執行 plan 就輸出了 No changes. Your infrastructure matches the configuration.。

總結

production 和測試帳戶現在使用同一個資料層模組,production 只有在我手動啟動 workflow 時才會套用。在對 production 做任何變更之前,唯讀的 plan(import 區塊、本機 state 的覆寫檔案、唯讀的憑證)就先顯示了接管會造成的 7 個替換。

主控台建立資源時,會用自己的方式替資源命名,所以我讓模組把這些名稱當作輸入,而不是把資源改名。原本從另一個資源的名稱組出來的名稱,我改成給它一個自己的固定值。這樣一來,替某個資源改名,就不會導致另一個資源被替換。

production 沒有設定審查者,而是靠刪除檢查把關。只要存下的 plan 裡有任何資源會被刪除,就不會套用。

不過刪除檢查只看刪除,抓不到像這次 security policy 那樣到套用時才失敗的更新。所以主控台填過、API 又不允許清空的欄位(例如描述),我都放進了 ignore_changes,讓 Terraform 不去更新它們。

參考連結

分享這篇文章