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

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

- Source: https://oharu121.com/zh-tw/blog/terraform-import-blocks-console-built-aws-prod-delete-guard/
- Published: 2026-11-08T11:51:21+09:00
- Tags: Terraform, AWS, GitHub Actions

---
## 引言

我參與開發的一個 AWS 資料層分成測試帳戶和 production 環境，其中測試帳戶是用 Terraform 建立的。建立時使用的模組，是我以唯讀方式擷取 production 的設定之後寫成的。詳細的做法寫在[我之前寫的 Terraform 重建文章](/zh-tw/blog/terraform-rebuild-console-aws-account-prod-spec-parity-oidc/)裡。那篇文章也提到，之後要讓 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` 區塊**：呼叫資料層模組，並傳入這個帳戶專用的值。

```text title="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 時，這項修改會被改回程式碼的設定；如果改回去需要刪除資源，刪除檢查就會中止這次執行。

*Figure — ApplyPaths: 每個 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` 一次處理：

```hcl title="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 了：

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

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

```bash
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.
```

*Figure — ReadOnlyPlan: 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 就只能先建立一個新的資源，再刪除舊的：

```text
# 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 role | 4 | 新的 role 會先建立，其他資源之後才改為指向它，所以在切換生效之前，呼叫可能會因為 `AccessDenied` 而失敗 |
| Lambda role 的 inline policy | 1 | 跟著它的 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 的名稱組出來：

```hcl title="modules/data-layer/bedrock_kb.tf" del={2} ins={3}
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 則傳入主控台裡原本的名稱：

```hcl title="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 = {}
}
```

```hcl title="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}")
  # …
}
```

*Figure — NameAdoption: 用模組自己的名稱會強制替換。透過 existing_names 傳入主控台裡原本的名稱，import 就能把資源原地納入管理。*

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

```bash
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`，所以測試帳戶原本的流程不受影響：

```yaml title=".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
```

*Image: GitHub 的 Run workflow 對話框，分支選了 main，target 輸入選了 prod*

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

`prod` environment 只能從 `main` 部署。這個限制是用 deployment branch policy 設定的，做法和[我之前寫的 Terraform 重建文章](/zh-tw/blog/terraform-rebuild-console-aws-account-prod-spec-parity-oidc/)替 `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 裡的檢查是這樣寫的：

```yaml title=".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。

> **試試這招**
>
> **用手寫的 plan 測試 jq 篩選運算式**
>
> 我用一份包含 `update`、`["delete","create"]` 和 `["delete"]` 的 plan 測試，結果輸出了 `delete/create a.rep` 和 `delete a.del`，update 則沒有輸出任何東西。

我把負責建立 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 上失敗了**：

```text
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 的資源則還沒有開始套用。

*Figure — PartialApply: 第一次執行卡在了兩個 security policy，在這之前的部分都已套用。改成忽略主控台填的描述之後，第二次執行完成了剩下的部分。*

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

```hcl title="modules/data-layer/opensearch.tf" ins={7-9}
resource "aws_opensearchserverless_security_policy" "encryption" {
  name   = local.collection_name
  type   = "encryption"
  policy = jsonencode({ /* 規則與金鑰設定，此處省略 */ })

  # 主控台填了描述；把它清空的更新會被 UpdateSecurityPolicy API 拒絕。
  lifecycle {
    ignore_changes = [description]
  }
}
```

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

```text
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 不去更新它們。

## 參考連結

- [Terraform：import 區塊，包含 for_each](https://developer.hashicorp.com/terraform/language/import)
- [Terraform：覆寫檔案，以及其中的 backend 區塊如何優先](https://developer.hashicorp.com/terraform/language/files/override)
- [Terraform：lifecycle meta-argument 與 ignore_changes](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle)
- [Terraform JSON 輸出格式，包含替換時的 actions 值](https://developer.hashicorp.com/terraform/internals/json-format)
- [Terraform：重構模組時使用的 moved 區塊](https://developer.hashicorp.com/terraform/language/modules/develop/refactoring)
- [GitHub Docs：部署與 environment，包含 deployment branch policy](https://docs.github.com/en/actions/reference/workflows-and-actions/deployments-and-environments)
- [OpenSearch Serverless API：UpdateSecurityPolicy](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_UpdateSecurityPolicy.html)
