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

# 使用 Terraform 开始使用 AWS DevOps Agent
<a name="getting-started-with-aws-devops-agent-getting-started-with-aws-devops-agent-using-terraform"></a>

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

本指南向您展示如何使用 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)。

## 先决条件
<a name="prerequisites"></a>

在开始之前，请确保您具有以下各项：
+ Terraform >= 1.0 已安装
+ AWS 已安装 CLI 并使用相应的凭据进行配置
+ 一个 AWS 用于监控（主要）账户的账户
+ （可选）如果您想设置跨 AWS 账户监控，则需要第二个账户

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

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

## 创建的资源
<a name="resources-created"></a>

### 第 1 部分：监控账户
<a name="part-1-monitoring-account"></a>
+ **IAM 角色** (`DevOpsAgentRole-AgentSpace-*`)-由 DevOps 代理服务担任以监控账户。包括`AIDevOpsAgentAccessPolicy`托管策略和允许创建资源管理器服务相关角色的内联策略。
+ **IAM 角色** (`DevOpsAgentRole-WebappAdmin-*`)-操作员应用程序角色，具有代理操作的`AIDevOpsOperatorAppAccessPolicy`托管策略。
+ **代理空间**（可配置名称）-使用`awscc_devopsagent_agent_space`资源创建的中央代理空间。包括操作员应用程序配置。
+ **关联**（AWS 监视器）-使用`awscc_devopsagent_association`资源将监控账户链接到代理空间。
+ **关联**（AWS 来源）-（可选）将服务帐户链接到代理空间以进行跨账户监控。

### 第 2 部分：服务帐号（可选）
<a name="part-2-service-account-optional"></a>
+ **IAM 角色** (`DevOpsAgentRole-SecondaryAccount-TF`)-具有固定名称的跨账户角色。受监控账户中代理空间的信任。包括`AIDevOpsAgentAccessPolicy`托管策略和允许创建资源管理器服务相关角色的内联策略。
+ **Lambda 函数** (`echo-service-tf`) — 一个回显输入事件的简单示例服务。

## 设置
<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-terraform.git
cd sample-aws-devops-agent-terraform
```

### 步骤 2：配置变量
<a name="step-2-configure-variables"></a>

复制示例变量文件并根据您的环境对其进行自定义：

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

`terraform.tfvars`使用您的代理空间名称和描述进行编辑：

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

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

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

### 步骤 1：自动化部署（推荐）
<a name="step-1-deploy-with-automation-recommended"></a>

使用提供的部署脚本来简化设置：

```
./deploy.sh
```

此脚本自动：
+ 检查先决条件（Terraform、CL AWS I、证书）
+ 如果需要`terraform.tfvars`，可以从示例中创建
+ 初始化、验证、计划和应用 Terraform

或者，如果您更喜欢手动控制：

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

`yes`当系统提示您确认部署时键入。

### 第 2 步：记录输出
<a name="step-2-record-the-outputs"></a>

部署完成后，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：验证部署
<a name="step-3-verify-the-deployment"></a>

运行部署后验证脚本：

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

或者使用 C AWS LI 验证代理空间是否已成功创建：

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

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

## 第 2 部分（可选）：添加跨账户监控
<a name="part-2-optional-add-cross-account-monitoring"></a>

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

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

1. 将跨账户 IAM 角色和 echo Lambda 函数部署到服务账户。

**重要**  
**在继续操作之前，必须完成第 1 部分。服务账户资源需要第 `agent_space_arn` 1 部分部署输出中的。

### 步骤 1：配置服务帐号 ID
<a name="step-1-configure-the-service-account-id"></a>

在中`terraform.tfvars`，设置您的服务帐号 ID：

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

### 步骤 2：设置代理空间 ARN
<a name="step-2-set-the-agent-space-arn"></a>

复制第 1 部分输出（步骤 2）中的`agent_space_arn`值并将其设置为`terraform.tfvars`：

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

服务帐号资源使用此值来确定次要账户角色的信任策略范围。这些资源只有在设置此值时才会创建。

### 第 3 步：配置 “aws.service” 提供商
<a name="step-3-configure-the-awsservice-provider"></a>

在中`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：部署
<a name="step-4-deploy"></a>

应用更新的配置：

```
terraform apply
```

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

它还会在监控账户中创建 AWS 关联服务帐号的源关联。

### 步骤 5：验证部署
<a name="step-5-verify-the-deployment"></a>

测试回显服务以确认 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
```

## 问题排查
<a name="troubleshooting"></a>

**IAM 传播延迟**
+ 该配置包括在 IAM 角色创建和代理空间创建`time_sleep`之间有 30 秒的间隔。 DevOps 代理服务会在创建代理空间期间验证操作员角色的信任策略，如果 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 云控制提供商。

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

如果您部署了第 2 部分，则要移除所有资源，请按相反的顺序销毁：

```
./cleanup.sh
```

或者手动：

```
terraform destroy
```

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

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

## 后续步骤
<a name="next-steps"></a>

使用 Terraform 部署 AWS DevOps 代理之后：

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

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

## 其他资源
<a name="additional-resources"></a>
+ [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)