本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 开始使用 AWS DevOps 代理使用 AWS CloudFormation
## 概述
本指南向您介绍如何使用 AWS CloudFormation 模板创建和部署 AWS DevOps 代理资源。这些模板以基础设施即代码的形式自动创建代理空间、 AWS 身份和访问管理 (IAM) 角色、运营商应用程序和 AWS 账户关联。
该 CloudFormation 方法[通过在声明式 YAML 模板中定义所有必需的资源，自动执行 ](https://docs.aws.amazon.com/devopsagent/latest/userguide/getting-started-with-aws-devops-agent-cli-onboarding-guide.html) CLI 入门指南中描述的手动步骤。
AWS DevOps 代理在多个 AWS 地区可用。完整列表请参阅 [支持的区域：](about-aws-devops-agent-supported-regions.md)。
## 先决条件
开始之前，请确保您拥有：
+ AWS 命令行界面 (AWS CLI) 已安装并使用相应的凭据进行配置
+ 创建 IAM 角色和 CloudFormation 堆栈的权限
+ 监控（主要） AWS 账户的一个账户
+ （可选）如果您想设置跨 AWS 账户监控，请使用第二个账户
## 本指南涵盖的内容
本指南分为以下部分：
+ **第 1 部分 ** — 使用操作员应用程序和监控账户中的 AWS 关联来部署代理空间。完成本部分后，代理可以监控该账户中的问题。
+ **第 2 部分（可选）**— 将跨账户 IAM 角色部署到辅助账户并添加源 AWS 关联。此配置使代理空间能够监控账户间的资源。
+ **第 3 部分（可选）**— 向代理空间添加技能、自定义代理和预定触发器，这样代理就可以拥有自定义知识并按计划运行自定义代理。
## 第 1 部分：部署代理空间
在本节中，您将创建一个 CloudFormation 模板，在您的监控账户中预置代理空间、IAM 角色、运营商应用程序和 AWS 关联。
### 第 1 步：创建 CloudFormation 模板
将以下模板另存为`devops-agent-stack.yaml`：
```
AWSTemplateFormatVersion: '2010-09-09'
Description: AWS DevOps Agent - Agent Space with IAM roles, operator app, and AWS association
Parameters:
AgentSpaceName:
Type: String
Default: MyCloudFormationAgentSpace
Description: Name for the agent space
AgentSpaceDescription:
Type: String
Default: Agent space deployed with CloudFormation
Description: Description for the agent space
Resources:
# IAM role assumed by the DevOps Agent service to monitor the account
DevOpsAgentSpaceRole:
Type: AWS::IAM::Role
Properties:
RoleName: DevOpsAgentRole-AgentSpace
AssumeRolePolicyDocument:
Version: '2012-10-17'
Statement:
- Effect: Allow
Principal:
Service: aidevops.amazonaws.com
Action: sts:AssumeRole
Condition:
StringEquals:
aws:SourceAccount: !Ref AWS::AccountId
ArnLike:
aws:SourceArn: !Sub arn:aws:aidevops:${AWS::Region}:${AWS::AccountId}:agentspace/*
ManagedPolicyArns:
- arn:aws:iam::aws:policy/AIDevOpsAgentAccessPolicy
Policies:
- PolicyName: AllowCreateServiceLinkedRoles
PolicyDocument:
Version: '2012-10-17'
Statement:
- Sid: AllowCreateServiceLinkedRoles
Effect: Allow
Action:
- iam:CreateServiceLinkedRole
Resource:
- !Sub arn:aws:iam::${AWS::AccountId}:role/aws-service-role/resource-explorer-2.amazonaws.com/AWSServiceRoleForResourceExplorer
# IAM role for the operator app interface
DevOpsOperatorRole:
Type: AWS::IAM::Role
Properties:
RoleName: DevOpsAgentRole-WebappAdmin
AssumeRolePolicyDocument:
Version: '2012-10-17'
Statement:
- Effect: Allow
Principal:
Service: aidevops.amazonaws.com
Action:
- sts:AssumeRole
- sts:TagSession
Condition:
StringEquals:
aws:SourceAccount: !Ref AWS::AccountId
ArnLike:
aws:SourceArn: !Sub arn:aws:aidevops:${AWS::Region}:${AWS::AccountId}:agentspace/*
ManagedPolicyArns:
- arn:aws:iam::aws:policy/AIDevOpsOperatorAppAccessPolicy
# The agent space resource
AgentSpace:
Type: AWS::DevOpsAgent::AgentSpace
DependsOn:
- DevOpsAgentSpaceRole
- DevOpsOperatorRole
Properties:
Name: !Ref AgentSpaceName
Description: !Ref AgentSpaceDescription
OperatorApp:
Iam:
OperatorAppRoleArn: !GetAtt DevOpsOperatorRole.Arn
# Association linking the monitoring account to the agent space
MonitorAssociation:
Type: AWS::DevOpsAgent::Association
Properties:
AgentSpaceId: !GetAtt AgentSpace.AgentSpaceId
ServiceId: aws
Configuration:
Aws:
AssumableRoleArn: !GetAtt DevOpsAgentSpaceRole.Arn
AccountId: !Ref AWS::AccountId
AccountType: monitor
Outputs:
AgentSpaceId:
Description: The agent space ID
Value: !GetAtt AgentSpace.AgentSpaceId
AgentSpaceArn:
Description: The agent space ARN
Value: !GetAtt AgentSpace.Arn
AgentSpaceRoleArn:
Description: The agent space IAM role ARN
Value: !GetAtt DevOpsAgentSpaceRole.Arn
OperatorRoleArn:
Description: The operator app IAM role ARN
Value: !GetAtt DevOpsOperatorRole.Arn
```
### 第 2 步：部署堆栈
运行以下命令来部署堆栈。``替换为[支持的区域：](about-aws-devops-agent-supported-regions.md)（例如，`us-east-1`）。
```
aws cloudformation deploy \
--template-file devops-agent-stack.yaml \
--stack-name DevOpsAgentStack \
--capabilities CAPABILITY_NAMED_IAM \
--region
```
### 第 3 步：记录堆栈输出
部署完成后，运行以下命令来检索堆栈输出。记录这些值以备日后使用。
```
aws cloudformation describe-stacks \
--stack-name DevOpsAgentStack \
--query 'Stacks[0].Outputs' \
--region
```
以下示例显示了预期的输出：
```
[
{
"OutputKey": "AgentSpaceId",
"OutputValue": "abc123def456"
},
{
"OutputKey": "AgentSpaceArn",
"OutputValue": "arn:aws:aidevops:::agentspace/abc123def456"
},
{
"OutputKey": "AgentSpaceRoleArn",
"OutputValue": "arn:aws:iam:::role/DevOpsAgentRole-AgentSpace"
},
{
"OutputKey": "OperatorRoleArn",
"OutputValue": "arn:aws:iam:::role/DevOpsAgentRole-WebappAdmin"
}
]
```
如果您计划完成第 2 部分，请保存该`AgentSpaceArn`值。你需要它来配置跨账户角色。
### 步骤 4：验证部署
要验证代理空间是否已成功创建，请运行以下 AWS CLI 命令：
```
aws devops-agent get-agent-space \
--agent-space-id \
--region
```
此时，您的代理空间已部署完毕，同时启用了操作员应用程序并关联了您的监控帐户。代理可以监控此账户中的问题。
## 第 2 部分（可选）：添加跨账户监控
在本节中，您将扩展设置，以便您的代理空间可以监控第二个 AWS 帐户（服务帐户）中的资源。这涉及两个操作：
1. 在信任代理空间的服务账户中部署 IAM 角色。
1. 在监控账户中添加指向服务帐号的源 AWS 关联。
必须先完成第 1 部分，然后才能继续。服务帐号模板需要第 1 部分`AgentSpaceArn`中的堆栈输出。
### 第 1 步：创建服务帐号模板
将以下模板另存为`devops-agent-service-account.yaml`。此模板在辅助账户中创建跨账户 IAM 角色。
```
AWSTemplateFormatVersion: '2010-09-09'
Description: AWS DevOps Agent - Cross-account IAM role for secondary account monitoring
Parameters:
MonitoringAccountId:
Type: String
Description: The 12-digit AWS account ID of the monitoring account
AgentSpaceArn:
Type: String
Description: The ARN of the agent space from the monitoring account
Resources:
# Cross-account IAM role trusted by the agent space
DevOpsSecondaryAccountRole:
Type: AWS::IAM::Role
Properties:
RoleName: DevOpsAgentRole-SecondaryAccount
AssumeRolePolicyDocument:
Version: '2012-10-17'
Statement:
- Effect: Allow
Principal:
Service: aidevops.amazonaws.com
Action: sts:AssumeRole
Condition:
StringEquals:
aws:SourceAccount: !Ref MonitoringAccountId
ArnLike:
aws:SourceArn: !Ref AgentSpaceArn
ManagedPolicyArns:
- arn:aws:iam::aws:policy/AIDevOpsAgentAccessPolicy
Policies:
- PolicyName: AllowCreateServiceLinkedRoles
PolicyDocument:
Version: '2012-10-17'
Statement:
- Sid: AllowCreateServiceLinkedRoles
Effect: Allow
Action:
- iam:CreateServiceLinkedRole
Resource:
- !Sub arn:aws:iam::${AWS::AccountId}:role/aws-service-role/resource-explorer-2.amazonaws.com/AWSServiceRoleForResourceExplorer
Outputs:
SecondaryAccountRoleArn:
Description: The cross-account IAM role ARN
Value: !GetAtt DevOpsSecondaryAccountRole.Arn
```
### 第 2 步：部署服务帐号堆栈
使用服务帐号的证书，运行以下命令：
```
aws cloudformation deploy \
--template-file devops-agent-service-account.yaml \
--stack-name DevOpsAgentServiceAccountStack \
--capabilities CAPABILITY_NAMED_IAM \
--parameter-overrides \
MonitoringAccountId= \
AgentSpaceArn= \
--region
```
### 第 3 步：添加来源 AWS 关联
切换回监控账户并创建源 AWS 关联。您可以通过创建单独的堆栈或更新原始模板来完成此操作。以下示例使用独立模板。
将以下模板另存为`devops-agent-source-association.yaml`：
```
AWSTemplateFormatVersion: '2010-09-09'
Description: AWS DevOps Agent - Source AWS association for cross-account monitoring
Parameters:
AgentSpaceId:
Type: String
Description: The agent space ID from the monitoring account stack
ServiceAccountId:
Type: String
Description: The 12-digit AWS account ID of the service account
ServiceAccountRoleArn:
Type: String
Description: The ARN of the DevOpsAgentRole-SecondaryAccount role in the service account
Resources:
SourceAssociation:
Type: AWS::DevOpsAgent::Association
Properties:
AgentSpaceId: !Ref AgentSpaceId
ServiceId: aws
Configuration:
SourceAws:
AccountId: !Ref ServiceAccountId
AccountType: source
AssumableRoleArn: !Ref ServiceAccountRoleArn
Outputs:
SourceAssociationId:
Description: The source association ID
Value: !Ref SourceAssociation
```
使用监控账户凭证部署关联堆栈：
```
aws cloudformation deploy \
--template-file devops-agent-source-association.yaml \
--stack-name DevOpsAgentSourceAssociationStack \
--parameter-overrides \
AgentSpaceId= \
ServiceAccountId= \
ServiceAccountRoleArn=arn:aws:iam:::role/DevOpsAgentRole-SecondaryAccount \
--region
```
## 第 3 部分：添加技能、自定义代理和预定触发器
这部分是可选的。在本节中，您将向第 1 部分中创建的代理空间添加三个资源。第一个是代理在相关时加载**的**技能。第二个是**自定义代理**，它将代理的范围限定为特定的工作流程。第三个是自动运行自定义代理的**定时触发器**。这些资源使用`AWS::DevOpsAgent::Asset`和`AWS::DevOpsAgent::Trigger`资源类型。有关将资产作为基础架构即代码进行管理的更多信息，请参阅[管理资产](about-aws-devops-agent-managing-assets.md)。
必须先完成第 1 部分，然后才能继续。此模板需要第 1 部分`AgentSpaceId`的堆栈输出。
### 第 1 步：创建模板
将以下模板另存为`devops-agent-content.yaml`。基于时间的触发器的操作在表单`custom:`中按资产 ID 引用自定义代理。模板会自动将其与之连接`Fn::GetAtt`。
```
AWSTemplateFormatVersion: '2010-09-09'
Description: AWS DevOps Agent - Example skill, custom agent, and scheduled trigger
Parameters:
AgentSpaceId:
Type: String
Description: The agent space ID from the Part 1 stack outputs
Resources:
# A skill the agent loads when relevant
ExampleSkill:
Type: AWS::DevOpsAgent::Asset
Properties:
AgentSpaceId: !Ref AgentSpaceId
AssetType: skill
Metadata:
name: rds-performance-investigation
description: Investigation procedures for RDS performance issues.
agent_types:
- GENERIC
Files:
- Path: SKILL.md
ContentText: |
# RDS Performance Investigation
Use this skill when investigating database latency, connection
errors, or query timeouts.
# A custom agent that a trigger can invoke
ExampleCustomAgent:
Type: AWS::DevOpsAgent::Asset
Properties:
AgentSpaceId: !Ref AgentSpaceId
AssetType: custom_agent
Metadata:
name: rds-firefighter
skills:
- rds-performance-investigation
Files:
- Path: AGENT.md
ContentText: |
# RDS Firefighter
Custom agent for RDS incidents.
# A time-based trigger that runs the custom agent on a schedule
DailyTrigger:
Type: AWS::DevOpsAgent::Trigger
Properties:
AgentSpaceId: !Ref AgentSpaceId
Type: TIME_BASED
Condition:
Schedule:
Expression: rate(1 day)
Action:
actionType: create:task
task:
agent: !Sub
- custom:${AssetId}
- AssetId: !GetAtt ExampleCustomAgent.AssetId
Status: Active
Outputs:
SkillAssetId:
Description: The skill asset ID
Value: !GetAtt ExampleSkill.AssetId
CustomAgentAssetId:
Description: The custom agent asset ID
Value: !GetAtt ExampleCustomAgent.AssetId
TriggerId:
Description: The trigger ID
Value: !GetAtt DailyTrigger.TriggerId
```
### 第 2 步：部署堆栈
使用监控账户凭据运行以下命令。``替换为第 1 部分输出的值。
```
aws cloudformation deploy \
--template-file devops-agent-content.yaml \
--stack-name DevOpsAgentContentStack \
--parameter-overrides AgentSpaceId= \
--region
```
`AgentSpaceId`、`Type``Condition`、和`Action`属性仅供创建。更改其中任何一个都将取代资源。您可以就地更新触发器`Status`（`Active`或`Inactive`），将其设置为在不删除触发器`Inactive`的情况下暂停触发器。有关其他资产类型和完整属性参考的更多信息，请参阅[管理资产](about-aws-devops-agent-managing-assets.md)。
## 验证
运行以下 AWS CLI 命令验证您的设置：
```
# List your agent spaces
aws devops-agent list-agent-spaces \
--region
# Get details of a specific agent space
aws devops-agent get-agent-space \
--agent-space-id \
--region
# List associations for an agent space
aws devops-agent list-associations \
--agent-space-id \
--region
```
## 问题排查
本节介绍常见问题及其解决方法。
**CloudFormation 未找到资源类型 **
+ 确认您正在部署[支持的区域：](about-aws-devops-agent-supported-regions.md)。
+ 确认您的 AWS CLI 已配置了相应的权限。
**IAM 角色创建失败 **
+ 验证您的部署凭证是否有权使用自定义名称创建 IAM 角色 (`CAPABILITY_NAMED_IAM`)。
+ 检查信任政策条件是否与您的账户 ID 相符。
**Cross-account 部署失败 **
+ 每个堆栈都必须使用目标账户的证书进行部署。使用该`--profile`标志指定正确的 AWS CLI 配置文件。
+ 验证`AgentSpaceArn`参数是否与第 1 部分堆栈输出中的确切 ARN 相匹配。
**IAM 传播延迟 **
+ IAM 角色更改可能需要几分钟才能传播。如果在创建角色后代理空间创建立即失败，请等待几分钟并重新部署。
## 资源清理
要移除所有资源，请按相反的顺序删除堆栈。
**警告：**此操作会永久删除您的代理空间和所有关联数据。此操作无法撤消。在继续操作之前，请确保已备份所有重要信息。
运行以下命令删除堆栈：
```
# If you deployed the Part 3 content stack, delete it first
aws cloudformation delete-stack \
--stack-name DevOpsAgentContentStack \
--region
aws cloudformation wait stack-delete-complete \
--stack-name DevOpsAgentContentStack \
--region
# If you deployed the source association stack, delete it next
aws cloudformation delete-stack \
--stack-name DevOpsAgentSourceAssociationStack \
--region
aws cloudformation wait stack-delete-complete \
--stack-name DevOpsAgentSourceAssociationStack \
--region
# If you deployed the service account stack, delete it next (using service account credentials)
aws cloudformation delete-stack \
--stack-name DevOpsAgentServiceAccountStack \
--region
aws cloudformation wait stack-delete-complete \
--stack-name DevOpsAgentServiceAccountStack \
--region
# Delete the main stack last
aws cloudformation delete-stack \
--stack-name DevOpsAgentStack \
--region
```
## 后续步骤
使用 AWS CloudFormation以下命令部署 AWS DevOps 代理后：
+ 要连接其他集成，请参阅[配置集成和知识](configuring-integrations-and-knowledge.md)。
+ 如果您注册了第三方集成，请通过在控制台中轮换 webhook 来获取其 webhook 网址和密钥。 AWS CloudFormation 不会将 webhook 密钥作为堆栈输出返回，因为它很敏感。有关管理 webhook 凭据的说明，请参阅[管理 webhook 凭据。](configuring-integrations-and-knowledge-invoking-devops-agent-through-webhook.md)
+ 要了解代理技能和能力，请参阅[DevOps 代理技能](about-aws-devops-agent-devops-agent-skills.md)。
+ 有关将技能、自定义代理和其他资产作为基础架构即代码进行管理的更多信息，请参阅[管理资产](about-aws-devops-agent-managing-assets.md)。
+ 要了解运营商 Web 应用程序，请参阅[什么是 DevOps 代理 Web 应用程序？](about-aws-devops-agent-what-is-a-devops-agent-web-app.md)。
+ 有关本指南中使用的 CloudFormation 资源类型的详细属性参考，请参阅*AWS CloudFormation 模板参考[中的](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/AWS_DevOpsAgent.html)AWS DevOps 代理资源类型参考*。