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

# 使用 AWS CDK 開始使用 AWS DevOps 代理程式
<a name="getting-started-with-aws-devops-agent-getting-started-with-aws-devops-agent-using-aws-cdk"></a>

## 概觀
<a name="overview"></a>

本指南說明如何使用 AWS 雲端開發套件 (AWS CDK) 來建立和部署 AWS DevOps 代理程式資源。 AWS CDK 應用程式會透過 AWS CloudFormation 自動建立代理程式空間、 AWS Identity and Access Management (IAM) 角色、運算子應用程式和 AWS 帳戶關聯。

 AWS CDK 方法透過將所有必要資源定義為基礎設施作為程式碼，自動執行 [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)。

## 先決條件
<a name="prerequisites"></a>

開始前，請確定您有下列項目：
+ AWS 命令列界面 (AWS CLI) 已安裝並使用適當的登入資料設定
+ Node.js 第 18 版或更新版本
+ AWS 全域安裝的 CDK 命令列界面 (CLI)。若要安裝 AWS CDK CLI，請執行下列命令：

```
npm install -g aws-cdk
```
+ 一個 AWS 帳戶用於監控 （主要） 帳戶
+ （選用） 如果您想要設定跨 AWS 帳戶監控的第二個帳戶

## 本指南涵蓋的內容
<a name="what-this-guide-covers"></a>

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

## 已建立資源
<a name="resources-created"></a>

### 第 1 部分：DevOpsAgentStack （監控帳戶）
<a name="part-1-devopsagentstack-monitoring-account"></a>
+ **IAM 角色** (`DevOpsAgentRole-AgentSpace`) — 由 DevOps Agent 服務擔任以監控帳戶。包括 `AIDevOpsAgentAccessPolicy`受管政策和允許建立 Resource Explorer 服務連結角色的內嵌政策。
+ **IAM 角色** (`DevOpsAgentRole-WebappAdmin`) — 具有客服人員操作`AIDevOpsOperatorAppAccessPolicy`受管政策的操作員應用程式角色。
+ **客服人員空間** (`MyCDKAgentSpace`) — 使用 `AWS::DevOpsAgent::AgentSpace` CloudFormation 資源建立的中央客服人員空間。包括運算子應用程式組態。
+ **關聯** (AWS 監視器） — 使用 `AWS::DevOpsAgent::Association` CloudFormation 資源將監控帳戶連結至代理程式空間。
+ **關聯** (AWS 來源） — （選用） 將服務帳戶連結到代理程式空間以進行跨帳戶監控。

### 第 2 部分：ServiceStack （服務帳戶，選用）
<a name="part-2-servicestack-service-account-optional"></a>
+ **IAM 角色** (`DevOpsAgentRole-SecondaryAccount`) — 具有固定名稱的跨帳戶角色。受監控帳戶中的代理程式空間信任。包括 `AIDevOpsAgentAccessPolicy`受管政策和允許建立 Resource Explorer 服務連結角色的內嵌政策。
+ **Lambda 函數** (`echo-service`) — 回應輸入事件的簡單範例服務。

## 設定
<a name="setup"></a>

### 步驟 1：複製範例儲存庫
<a name="step-1-clone-the-sample-repository"></a>

執行下列命令來複製儲存庫並變更至專案目錄：

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

### 步驟 2：安裝相依性
<a name="step-2-install-dependencies"></a>

執行下列命令來安裝專案相依性：

```
npm install
```

## 第 1 部分：部署代理程式空間
<a name="part-1-deploy-the-agent-space"></a>

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

### 步驟 1：設定監控帳戶 ID
<a name="step-1-configure-the-monitoring-account-id"></a>

開啟`lib/constants.ts`並設定您的監控帳戶 ID：

下列範例顯示要更新的常數：

```
export const MONITORING_ACCOUNT_ID = "<YOUR_MONITORING_ACCOUNT_ID>";
```

### 步驟 2：引導 AWS CDK 環境
<a name="step-2-bootstrap-the-aws-cdk-environment"></a>

如果您尚未在監控帳戶中引導 AWS CDK，請執行下列命令：

```
cdk bootstrap aws://<MONITORING_ACCOUNT_ID>/<REGION> --profile monitoring
```

### 步驟 3：建置和部署
<a name="step-3-build-and-deploy"></a>

執行下列命令來建置 TypeScript 程式碼並部署堆疊：

```
npm run build
cdk deploy DevOpsAgentStack --profile monitoring
```

### 步驟 4：記錄堆疊輸出
<a name="step-4-record-the-stack-outputs"></a>

部署完成後， AWS CDK 會列印堆疊輸出。記錄這些值以供日後使用。

下列範例顯示預期的輸出：

```
Outputs:
DevOpsAgentStack.AgentSpaceArn = arn:aws:aidevops:<REGION>:123456789012:agentspace/abc123
DevOpsAgentStack.AgentSpaceRoleArn = arn:aws:iam::123456789012:role/DevOpsAgentRole-AgentSpace
DevOpsAgentStack.OperatorRoleArn = arn:aws:iam::123456789012:role/DevOpsAgentRole-WebappAdmin
DevOpsAgentStack.AssociationId = assoc-xyz
```

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

### 步驟 5：驗證部署
<a name="step-5-verify-the-deployment"></a>

若要確認已成功建立代理程式空間，請執行下列 CLI AWS 命令：

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

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

## 第 2 部分 （選用）：新增跨帳戶監控
<a name="part-2-optional-add-cross-account-monitoring"></a>

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

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

1. 使用信任代理程式空間的 IAM 角色，將 ServiceStack 部署至服務帳戶。

**重要**  
** 您必須完成第 1 部分，才能繼續。ServiceStack 需要 DevOpsAgentStack 部署輸出`AgentSpaceArn`中的 。

### 步驟 1：設定服務帳戶 ID
<a name="step-1-configure-the-service-account-id"></a>

開啟`lib/constants.ts`並設定您的服務帳戶 ID：

下列範例顯示要更新的常數：

```
export const SERVICE_ACCOUNT_ID = "<YOUR_SERVICE_ACCOUNT_ID>";
```

DevOpsAgentStack 使用此帳戶 ID 建立來源 AWS 關聯。如果您在設定此值之前已部署 DevOpsAgentStack，請重新部署 以建立關聯：

執行下列命令以重新部署：

```
npm run build
cdk deploy DevOpsAgentStack --profile monitoring
```

### 步驟 2：設定客服人員空間 ARN
<a name="step-2-set-the-agent-space-arn"></a>

從 DevOpsAgentStack 輸出複製 `AgentSpaceArn`值 （第 1 部分，步驟 4)，並在 中設定： `lib/constants.ts`

下列範例顯示要更新的常數：

```
export const AGENT_SPACE_ARN = "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/<SPACE_ID>";
```

ServiceStack 使用此值來限制次要帳戶角色的信任政策範圍。只有在設定此值時，才會合成 ServiceStack。

### 步驟 3：引導服務帳戶
<a name="step-3-bootstrap-the-service-account"></a>

如果您尚未在服務帳戶中啟動 AWS CDK，請執行下列命令：

```
cdk bootstrap aws://<SERVICE_ACCOUNT_ID>/<REGION> --profile service
```

### 步驟 4：部署 ServiceStack
<a name="step-4-deploy-the-servicestack"></a>

執行下列命令，使用服務帳戶的登入資料來建置和部署 ServiceStack：

```
npm run build
cdk deploy ServiceStack --profile service
```

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

### 步驟 5：驗證部署
<a name="step-5-verify-the-deployment"></a>

若要確認 Lambda 函數已成功部署，請執行下列命令來測試 echo 服務：

```
aws lambda invoke \
  --function-name echo-service \
  --payload '{"test": "hello world"}' \
  --profile service \
  response.json
cat response.json
```

## 疑難排解
<a name="troubleshooting"></a>

本節說明常見問題以及如何解決這些問題。

**找不到 CloudFormation 資源類型**
+ 確認您是在 中部署[支援的區域](about-aws-devops-agent-supported-regions.md)。
+ 確認您的 AWS CLI 已設定適當的許可。

**IAM 角色建立失敗**
+ 確認您的部署角色具有建立 IAM 角色的許可。
+ 檢查信任政策條件是否符合您的帳戶 ID。

**跨帳戶部署失敗，並顯示「無法在目標帳戶中擔任角色」**
+ 每個堆疊都必須使用目標帳戶的登入資料進行部署。使用 `--profile`旗標指定正確的 CLI AWS 設定檔。
+ 確認已在目標帳戶中引導 AWS CDK。

**IAM 傳播延遲**
+ IAM 角色變更可能需要幾分鐘的時間才能傳播。如果客服人員空間建立在角色建立後立即失敗，請等待幾分鐘，然後重新部署。

## 清除
<a name="cleanup"></a>

若要移除所有資源，請以相反順序銷毀堆疊。

執行下列命令來銷毀堆疊：

```
# If you deployed the ServiceStack, destroy it first
cdk destroy ServiceStack --profile service
# Then destroy the DevOpsAgentStack
cdk destroy DevOpsAgentStack --profile monitoring
```

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

## 安全考量
<a name="security-considerations"></a>
+  AWS CDK 應用程式會使用只允許`aidevops.amazonaws.com`服務主體擔任的信任政策來建立 IAM 角色。
+ 信任政策包括限制存取特定 AWS 帳戶和客服人員空間 ARN 的條件。
+ 所有政策都遵循最低權限原則。根據組織的安全需求檢閱和自訂 IAM 政策。
+ 跨帳戶角色 (`DevOpsAgentRole-SecondaryAccount`) 使用固定名稱，範圍為特定的客服人員空間 ARN。

## 後續步驟
<a name="next-steps"></a>

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

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

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

## 其他資源
<a name="additional-resources"></a>
+ [AWS DevOps 代理程式使用者指南](https://docs.aws.amazon.com/devopsagent/latest/userguide/)
+ GitHub 網站上的[範例 CDK 儲存庫](https://github.com/aws-samples/sample-aws-devops-agent-cdk) 
+ [CLI 入門指南](https://docs.aws.amazon.com/devopsagent/latest/userguide/getting-started-with-aws-devops-agent-cli-onboarding-guide.html)