本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用 AWS CDK 开始使用 AWS DevOps 代理


## 概述


本指南向您展示如何使用 C AWS loud Development Kit (AWS CDK) 创建和部署 AWS DevOps 代理资源。 AWS CDK 应用程序通过自动创建代理空间、 AWS 身份和访问管理 (IAM) 角色、操作员应用程序和账户关联。 AWS AWS CloudFormation

 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)。

## 先决条件


开始之前，请确保您拥有：
+ AWS 已安装命令行接口 (AWS CLI)，并使用相应的凭据进行配置
+ Node.js 版本 18 或更高版本
+ AWS 全局安装了 CDK 命令行界面 (CLI)。要安装 AWS CDK CLI，请运行以下命令：

```
npm install -g aws-cdk
```
+ 一个 AWS 用于监控（主要）账户的账户
+ （可选）如果您想设置跨 AWS 账户监控，则需要第二个账户

## 本指南涵盖的内容


本指南分为两部分：
+ **第 1 部分** — 在您的监控账户中部署带有操作员应用程序和 AWS 关联的代理空间。完成本部分后，代理可以监控该账户中的问题。
+ **第 2 部分（可选）**— 为服务账户添加源 AWS 关联，并将跨账户 IAM 角色部署到该账户。此配置使代理空间能够跨账户监控资源。

## 创建的资源


### 第 1 部分： DevOpsAgentStack （监控账户）

+ **IAM 角色** (`DevOpsAgentRole-AgentSpace`)-由 DevOps 代理服务担任以监控账户。包括`AIDevOpsAgentAccessPolicy`托管策略和允许创建资源管理器服务相关角色的内联策略。
+ **IAM 角色** (`DevOpsAgentRole-WebappAdmin`)-操作员应用程序角色，具有代理操作的`AIDevOpsOperatorAppAccessPolicy`托管策略。
+ **代理空间** (`MyCDKAgentSpace`)-使用`AWS::DevOpsAgent::AgentSpace` CloudFormation 资源创建的中央代理空间。包括操作员应用程序配置。
+ **关联**（AWS 监视器）-使用`AWS::DevOpsAgent::Association` CloudFormation 资源将监控账户链接到代理空间。
+ **关联**（AWS 来源）-（可选）将服务帐户链接到代理空间以进行跨账户监控。

### 第 2 部分： ServiceStack （服务帐号，可选）

+ **IAM 角色** (`DevOpsAgentRole-SecondaryAccount`) — 具有固定名称的跨账户角色。受监控账户中代理空间的信任。包括`AIDevOpsAgentAccessPolicy`托管策略和允许创建资源管理器服务相关角色的内联策略。
+ **Lambda 函数** (`echo-service`) — 一个回显输入事件的简单示例服务。

## 设置


### 步骤 1：克隆示例存储库


运行以下命令来克隆存储库并切换到项目目录：

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

### 第 2 步：安装依赖关系


运行以下命令来安装项目依赖项：

```
npm install
```

## 第 1 部分：部署代理空间


在本节中，您将在您的监控账户中创建代理空间、IAM 角色、操作员应用程序和 AWS 关联。

### 步骤 1：配置监控账户 ID


打开`lib/constants.ts`并设置您的监控账户 ID：

以下示例显示了要更新的常量：

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

### 第 2 步：引导 AWS CDK 环境


如果您尚未在监控账户中引导 AWS CDK，请运行以下命令：

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

### 步骤 3：构建和部署


运行以下命令来构建 TypeScript 代码并部署堆栈：

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

### 第 4 步：记录堆栈输出


部署完成后， 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：验证部署


要验证代理空间是否已成功创建，请运行以下 AWS CLI 命令：

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

此时，您的代理空间已在启用操作员应用程序并关联您的监控账户的情况下进行部署。代理可以监控此账户中的问题。

## 第 2 部分（可选）：添加跨账户监控


在本节中，您将扩展设置，以便您的代理空间可以监控第二个 AWS 帐户（服务帐户）中的资源。这涉及两个操作：

1. 在中添加指向服务帐号的源 AWS 关联。 DevOpsAgentStack 

1. 使用信任代理空间的 IAM 角色将部署 ServiceStack 到服务账户。

**重要**  
**必须先完成第 1 部分，然后才能继续。 ServiceStack 需要 DevOpsAgentStack 部署输出`AgentSpaceArn`中的。

### 步骤 1：配置服务帐号 ID


打开`lib/constants.ts`并设置您的服务帐号 ID：

以下示例显示了要更新的常量：

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

使用此账户 ID DevOpsAgentStack 创建源 AWS 关联。如果您 DevOpsAgentStack 在设置此值之前部署了，请重新部署以创建关联：

运行以下命令进行重新部署：

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

### 步骤 2：设置代理空间 ARN


复制 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 步：引导服务账号


如果您尚未在服务帐号中引导 AWS CDK，请运行以下命令：

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

### 步骤 4：部署 ServiceStack


运行以下命令，使用服务帐号 ServiceStack 的凭据构建和部署：

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

这将在服务帐号中创建以下资源：
+ 信任监控账户中代理空间的 IAM 角色 (`DevOpsAgentRole-SecondaryAccount`)
+ 将 echo Lambda 函数 (`echo-service`) 作为示例服务

### 步骤 5：验证部署


要确认 Lambda 函数已成功部署，请运行以下命令来测试 echo 服务：

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

## 问题排查


本节介绍常见问题以及如何解决这些问题。

**CloudFormation 未找到资源类型**
+ 确认您正在中进行部署[支持的区域：](about-aws-devops-agent-supported-regions.md)。
+ 确认您的 AWS CLI 配置了相应的权限。

**IAM 角色创建失败**
+ 验证您的部署角色是否有权创建 IAM 角色。
+ 检查信任政策条件是否与您的账户 ID 相符。

**跨账户部署失败，并显示 “无法在目标账户中扮演角色”**
+ 每个堆栈都必须使用目标账户的凭据进行部署。使用该`--profile`标志指定正确的 AWS CLI 配置文件。
+ 验证 AWS CDK 是否已在目标账户中被引导。

**IAM 传播延迟**
+ IAM 角色更改可能需要几分钟才能传播。如果创建角色后立即创建代理空间失败，请等待几分钟并重新部署。

## 清理


要移除所有资源，请按相反的顺序销毁堆栈。

运行以下命令来销毁堆栈：

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

**警告：**此操作将永久删除您的代理空间和所有相关数据。此操作无法撤消。在继续操作之前，请确保已备份所有重要信息。

## 安全注意事项

+  AWS CDK 应用程序使用信任策略创建 IAM 角色，该策略仅允许`aidevops.amazonaws.com`服务委托人代入这些角色。
+ 信任策略包括限制访问您的特定 AWS 账户和代理空间 ARN 的条件。
+ 所有策略都遵循最低权限原则。根据贵组织的安全要求查看和自定义 IAM 策略。
+ 跨账户角色 (`DevOpsAgentRole-SecondaryAccount`) 使用固定名称，其作用域仅限于特定的代理空间 ARN。

## 后续步骤


使用 AWS CDK 部署 AWS DevOps 代理后：

1. 在《 DevOps 代理[用户指南》中了解AWS DevOps 代理](https://docs.aws.amazon.com/devopsagent/latest/userguide/)的全部功能。

1. 考虑将 AWS CDK 部署集成到您的 CI/CD 管道中，以实现自动化基础架构管理。

## 其他资源

+ [AWS DevOps 代理用户指南](https://docs.aws.amazon.com/devopsagent/latest/userguide/)
+ 网站上的 [CDK 存储库示例](https://github.com/aws-samples/sample-aws-devops-agent-cdk) GitHub 
+ [CLI 入门指南](https://docs.aws.amazon.com/devopsagent/latest/userguide/getting-started-with-aws-devops-agent-cli-onboarding-guide.html)