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

开始使用 AWS DevOps 使用 Terraform 的代理

概述

本指南向您展示如何使用 Terraform 创建和部署 AWS DevOps 代理资源。Terraform 配置可自动创建代理空间、IAM 角色、操作员应用程序和 AWS 账户关联。

Terraform 方法通过将所有必需的资源定义为基础架构即代码，从而自动执行 CLI 入门指南中描述的手动步骤。

AWS DevOps 代理可在以下 6 个 AWS 区域使用：美国东部（弗吉尼亚北部）、美国西部（俄勒冈）、亚太地区（悉尼）、亚太地区（东京）、欧洲（法兰克福）和欧洲（爱尔兰）。有关受支持区域的更多信息，请参阅支持的区域：。

先决条件

在开始之前，请确保您具有以下各项：

本指南涵盖的内容

本指南分为三个部分：

创建的资源

第 1 部分：监控账户

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

设置

步骤 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 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

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

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

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

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

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

步骤 1：配置服务帐号 ID

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

service_account_id = "<YOUR_SERVICE_ACCOUNT_ID>"

步骤 2：设置代理空间 ARN

复制第 1 部分输出（步骤 2）中的agent_space_arn值并将其设置为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

这将在服务帐号中创建以下资源：

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

步骤 5：验证部署

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

第 3 部分（可选）：注册第三方集成

在本节中，您将向代理空间注册外部服务（Dynatrace、 ServiceNow、Splunk、New Relic GitLab、、 PagerDuty）。这些集成使 AWS DevOps 代理能够在调查期间访问遥测、事件数据和源代码控制信息。

与 AWS CDK 示例（需要单独的 IntegrationsStack 阶段和手动接线座席空间 ID）不同，这些资源直接引用代理空间，并且可以与第 1 部分terraform apply相同的方式部署。

支持的集成

步骤 1：配置集成凭证

向中添加一个integrations方块terraform.tfvars，仅填充您想要的服务。以下示例显示了 Dynatrace 集成：

integrations = {
  dynatrace = {
    account_urn   = "<DYNATRACE_ACCOUNT_URN>"
    client_id     = "<DYNATRACE_CLIENT_ID>"
    client_name   = "<DYNATRACE_CLIENT_NAME>"
    client_secret = "<DYNATRACE_CLIENT_SECRET>"
    env_id        = "<DYNATRACE_ENVIRONMENT_ID>"
    resources     = ["<DYNATRACE_RESOURCE_1>"]
  }
}

有关每个集成的完整形式，请参阅示例存储库terraform.tfvars.example中的。

ServiceNow 要求：始终instance_id明确设置为简短的实例名称（例如，"ven04972"— 而不是完整名称instance_url）。如果省略，instance_id则关联将回退到instance_url， DevOps 代理 API 会使用拒绝该关联。400 GeneralServiceException: instanceId '<url>' does not match the registered ServiceNow instance

安全性：integrations变量已被标记sensitive，因此其值已从计划和应用输出中删除。请勿向提交真实凭证terraform.tfvars。对于生产环境，从 Secrets Manager 或 AWS Systems Manager 参数存储库中获取 AWS 密钥（例如，使用data源代码），而不是纯文本。

步骤 2：部署

应用配置：

terraform apply

这将为每个启用的集成创建服务注册和关联。

步骤 3：查看输出

部署完成后，集成输出将每个启用的服务映射到其注册的 ID：

integration_service_ids = {
  "dynatrace" = "service-abc123"
}
integration_association_ids = {
  "dynatrace" = "assoc-xyz789"
}

有关为每项服务配置凭证的更多信息，请参阅：

使用现有 IAM 角色（可选）

默认情况下，Terraform 配置会为代理空间和操作员应用程序创建新的 IAM 角色。如果您已经拥有具有所需策略的 IAM 角色，则可以跳过角色创建，改为提供现有角色 ARN。

要求

现有角色必须满足以下要求：

代理空间角色

操作员应用程序角色

配置

在中terraform.tfvars，设置一个或两个角色 ARN：

existing_agentspace_role_arn = "arn:aws:iam::ACCOUNT_ID:role/YourAgentSpaceRole"
existing_operator_role_arn   = "arn:aws:iam::ACCOUNT_ID:role/YourOperatorRole"

设置这些值后，将跳过中的iam.tf相应角色资源。这种方法完全向后兼容 — 具有空值（默认）的现有配置保留了当前的角色创建行为。

问题排查

IAM 传播延迟

ServiceNow instanceId does not match错误

Dynatrace 协会 status: invalid

权限错误

Cross-account 部署失败

未找到 Terraform 资源类型

资源清理

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

./cleanup.sh

或者手动：

terraform destroy

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

安全注意事项

后续步骤

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

其他资源