本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 Terraform 開始使用 AWS DevOps 代理程式


## 概觀


本指南說明如何使用 Terraform 來建立和部署 AWS DevOps 代理程式資源。Terraform 組態會自動建立代理程式空間、IAM 角色、運算子應用程式和 AWS 帳戶關聯。

Terraform 方法透過將所有必要資源定義為基礎設施作為程式碼，自動執行 [CLI 入門指南](https://docs.aws.amazon.com/devopsagent/latest/userguide/getting-started-with-aws-devops-agent-cli-onboarding-guide.html)中所述的手動步驟。

AWS DevOps 代理程式可在下列 6 AWS 區域使用：美國東部 （維吉尼亞北部）、美國西部 （奧勒岡）、亞太區域 （雪梨）、亞太區域 （東京）、歐洲 （法蘭克福） 和歐洲 （愛爾蘭）。如需支援區域的詳細資訊，請參閱 [支援的區域](about-aws-devops-agent-supported-regions.md)。

## 先決條件


開始前，請確定您具有下列項目：
+ Terraform >= 已安裝 1.0
+ AWS 使用適當的登入資料安裝和設定 CLI
+ 一個 AWS 帳戶用於監控 （主要） 帳戶
+ （選用） 如果您想要設定跨 AWS 帳戶監控的第二個帳戶

## 本指南涵蓋的內容


本指南分為兩個部分：
+ **第 1** 部分 — 使用 運算子應用程式和監控帳戶中的 AWS 關聯部署代理程式空間。完成此部分後，客服人員可以監控該帳戶中的問題。
+ **第 2 部分 （選用）** — 新增服務帳戶的來源 AWS 關聯，並將跨帳戶 IAM 角色加上 echo Lambda 部署至該帳戶。這可讓客服人員空間跨帳戶監控資源。

## 已建立資源


### 第 1 部分：監控帳戶

+ **IAM 角色** (`DevOpsAgentRole-AgentSpace-*`) — 由 DevOps Agent 服務擔任以監控帳戶。包括 `AIDevOpsAgentAccessPolicy`受管政策和允許建立 Resource Explorer 服務連結角色的內嵌政策。
+ **IAM 角色** (`DevOpsAgentRole-WebappAdmin-*`) — 具有客服人員操作`AIDevOpsOperatorAppAccessPolicy`受管政策的操作員應用程式角色。
+ **客服人員空間** （可設定的名稱） — 使用 `awscc_devopsagent_agent_space` 資源建立的中央客服人員空間。包括運算子應用程式組態。
+ **關聯** (AWS 監視器） — 使用 `awscc_devopsagent_association` 資源將監控帳戶連結至客服人員空間。
+ **關聯** (AWS 來源） — （選用） 將服務帳戶連結到代理程式空間以進行跨帳戶監控。

### 第 2 部分：服務帳戶 （選用）

+ **IAM 角色** (`DevOpsAgentRole-SecondaryAccount-TF`) — 具有固定名稱的跨帳戶角色。受監控帳戶中的代理程式空間信任。包括 `AIDevOpsAgentAccessPolicy`受管政策和允許建立 Resource Explorer 服務連結角色的內嵌政策。
+ **Lambda 函數** (`echo-service-tf`) — 回應輸入事件的簡單範例服務。

## 設定


### 步驟 1：複製範例儲存庫


```
git clone https://github.com/aws-samples/sample-aws-devops-agent-terraform.git
cd sample-aws-devops-agent-terraform
```

### 步驟 2：設定變數


複製範例變數檔案，並針對您的環境進行自訂：

```
cp terraform.tfvars.example terraform.tfvars
```

`terraform.tfvars` 使用您的客服人員空間名稱和描述進行編輯：

```
agent_space_name        = "MyCompanyAgentSpace"
agent_space_description = "DevOps Agent Space for monitoring production workloads"
```

## 第 1 部分：部署代理程式空間


在本節中，您會在監控帳戶中建立代理程式空間、IAM 角色、運算子應用程式和 AWS 關聯。

### 步驟 1：使用自動化部署 （建議）


使用提供的部署指令碼進行簡化設定：

```
./deploy.sh
```

此指令碼會自動：
+ 檢查先決條件 (Terraform、 AWS CLI、登入資料）
+ 視需要`terraform.tfvars`從範例建立
+ 初始化、驗證、規劃和套用 Terraform

或者，如果您偏好手動控制：

```
terraform init
terraform plan
terraform apply
```

出現提示`yes`時輸入 以確認部署。

### 步驟 2：記錄輸出


部署完成後，Terraform 會列印輸出。記錄這些值以供日後使用：

```
Outputs:
agent_space_id              = "abc123"
agent_space_arn             = "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/abc123"
agent_space_name            = "MyCompanyAgentSpace"
devops_agentspace_role_arn  = "arn:aws:iam::<MONITORING_ACCOUNT_ID>:role/DevOpsAgentRole-AgentSpace-a1b2c3d4"
devops_operator_role_arn    = "arn:aws:iam::<MONITORING_ACCOUNT_ID>:role/DevOpsAgentRole-WebappAdmin-a1b2c3d4"
primary_account_id          = "<MONITORING_ACCOUNT_ID>"
primary_account_association_id = "assoc-xyz"
```

如果您打算完成第 2 部分，請儲存該`agent_space_arn`值。您將需要它來設定服務帳戶資源。

### 步驟 3：驗證部署


執行部署後驗證指令碼：

```
./post-deploy.sh
```

或使用 AWS CLI 來驗證已成功建立代理程式空間：

```
aws devops-agent get-agent-space \
  --agent-space-id <AGENT_SPACE_ID> \
  --region <REGION>
```

此時，您的代理程式空間會在啟用 運算子應用程式且您的監控帳戶相關聯的情況下部署。代理程式可以監控此帳戶中的問題。

## 第 2 部分 （選用）：新增跨帳戶監控


在本節中，您會擴展設定，讓客服人員空間可以監控第二個 AWS 帳戶 （服務帳戶） 中的資源。這涉及兩個動作：

1. 新增指向服務帳戶的來源 AWS 關聯。

1. 將跨帳戶 IAM 角色和 echo Lambda 函數部署至服務帳戶。

**重要**  
** 您必須完成第 1 部分，才能繼續。服務帳戶資源需要`agent_space_arn`來自第 1 部分部署輸出的 。

### 步驟 1：設定服務帳戶 ID


在 中`terraform.tfvars`，設定您的服務帳戶 ID：

```
service_account_id = "<YOUR_SERVICE_ACCOUNT_ID>"
```

### 步驟 2：設定客服人員空間 ARN


從第 1 部分輸出複製 `agent_space_arn`值 （步驟 2)，並在 中設定`terraform.tfvars`：

```
agent_space_arn = "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/<SPACE_ID>"
```

服務帳戶資源使用此值來限制次要帳戶角色的信任政策範圍。只有在設定此值時，才會建立這些資源。

### 步驟 3：設定 `aws.service` 供應商


在 中`main.tf`，使用服務帳戶的登入資料設定`aws.service`提供者別名。您可以使用具名設定檔或擔任角色：

使用設定檔：

```
provider "aws" {
  alias   = "service"
  region  = var.aws_region
  profile = "your-service-account-profile"
}
```

或使用擔任角色：

```
provider "aws" {
  alias  = "service"
  region = var.aws_region
  assume_role {
    role_arn = "arn:aws:iam::<SERVICE_ACCOUNT_ID>:role/OrganizationAccountAccessRole"
  }
}
```

### 步驟 4：部署


套用更新的組態：

```
terraform apply
```

這會在服務帳戶中建立下列資源：
+ 信任監控帳戶中客服人員空間的 IAM 角色 (`DevOpsAgentRole-SecondaryAccount-TF`)
+ 以 echo Lambda 函數 (`echo-service-tf`) 做為範例服務

它也會在監控帳戶中建立來源 AWS 關聯，以連結服務帳戶。

### 步驟 5：驗證部署


測試 echo 服務以確認 Lambda 函數已成功部署：

```
aws lambda invoke \
  --function-name echo-service-tf \
  --payload '{"test": "hello world"}' \
  --profile <your-service-account-profile> \
  --region <REGION> \
  response.json
cat response.json
```

## 疑難排解


**IAM 傳播延遲**
+ 組態包含 IAM 角色建立與客服人員空間建立`time_sleep`之間的 30 秒。DevOps Agent 服務會在建立 Agent Space 期間驗證運算子角色的信任政策，如果 IAM 尚未完全傳播，則可能會失敗。如果您仍然看到信任政策錯誤，請等待一分鐘，然後`terraform apply`再次執行 - IAM 角色將已存在，而套用將在停止的位置取得。

**許可錯誤**
+ 確認您的 AWS 登入資料具有建立角色和政策所需的 IAM 許可。
+ 檢查信任政策條件是否符合您的帳戶 ID。

**跨帳戶部署失敗**
+ 必須使用服務帳戶的登入資料來設定`aws.service`提供者。使用具名設定檔或擔任角色區塊。
+ 確認該`agent_space_arn`值符合來自第 1 部分輸出的 ARN。

**找不到 Terraform 資源類型**
+ 確認您有`awscc`提供者版本 `~> 1.0`或更新版本。`awscc_devopsagent_agent_space` 和資源`awscc_devopsagent_association`需要 AWS 雲端控制供應商。

## 清除


若要移除所有資源，如果您已部署第 2 部分，請以相反順序銷毀：

```
./cleanup.sh
```

或手動：

```
terraform destroy
```

**警告：**這會永久刪除您的客服人員空間和所有相關聯的資料。在繼續之前，請確定您已備份任何重要資訊。

## 安全考量

+ Terraform 組態會建立具有信任政策的 IAM 角色，只允許`aidevops.amazonaws.com`服務主體擔任這些角色。
+ 信任政策包括限制存取特定 AWS 帳戶和客服人員空間 ARN 的條件。
+ 所有政策都遵循最低權限原則。根據組織的安全需求檢閱和自訂 IAM 政策。
+ 跨帳戶角色 (`DevOpsAgentRole-SecondaryAccount-TF`) 使用固定名稱，範圍為特定的客服人員空間 ARN。

## 後續步驟


使用 Terraform 部署您的 AWS DevOps 代理程式之後：

1. 請參閱 DevOps Agent [AWS 使用者指南，了解 DevOps Agent](https://docs.aws.amazon.com/devopsagent/latest/userguide/) 功能的完整範圍。

1. 考慮將 Terraform 部署整合到您的 CI/CD 管道，以進行自動化基礎設施管理。

## 其他資源

+ [AWS DevOps 代理程式使用者指南](https://docs.aws.amazon.com/devopsagent/latest/userguide/)
+ [範例 Terraform 儲存庫](https://github.com/aws-samples/sample-aws-devops-agent-terraform)
+ [CLI 入門指南](https://docs.aws.amazon.com/devopsagent/latest/userguide/getting-started-with-aws-devops-agent-cli-onboarding-guide.html)