概述先决条件本指南涵盖的内容第 1 部分：部署代理空间第 2 部分（可选）：添加跨账户监控第 3 部分：添加技能、自定义代理和预定触发器验证问题排查资源清理后续步骤

开始使用 AWS DevOps 代理使用 AWS CloudFormation

概述

本指南向您介绍如何使用 AWS CloudFormation 模板创建和部署 AWS DevOps 代理资源。这些模板以基础设施即代码的形式自动创建代理空间、 AWS 身份和访问管理 (IAM) 角色、运营商应用程序和 AWS 账户关联。

该 CloudFormation 方法通过在声明式 YAML 模板中定义所有必需的资源，自动执行 CLI 入门指南中描述的手动步骤。

AWS DevOps 代理在多个 AWS 地区可用。完整列表请参阅支持的区域：。

先决条件

开始之前，请确保您拥有：

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 步：部署堆栈

运行以下命令来部署堆栈。<REGION>替换为支持的区域：（例如，us-east-1）。


aws cloudformation deploy \
  --template-file devops-agent-stack.yaml \
  --stack-name DevOpsAgentStack \
  --capabilities CAPABILITY_NAMED_IAM \
  --region <REGION>

第 3 步：记录堆栈输出

部署完成后，运行以下命令来检索堆栈输出。记录这些值以备日后使用。


aws cloudformation describe-stacks \
  --stack-name DevOpsAgentStack \
  --query 'Stacks[0].Outputs' \
  --region <REGION>

以下示例显示了预期的输出：


[
  {
    "OutputKey": "AgentSpaceId",
    "OutputValue": "abc123def456"
  },
  {
    "OutputKey": "AgentSpaceArn",
    "OutputValue": "arn:aws:aidevops:<REGION>:<ACCOUNT_ID>:agentspace/abc123def456"
  },
  {
    "OutputKey": "AgentSpaceRoleArn",
    "OutputValue": "arn:aws:iam::<ACCOUNT_ID>:role/DevOpsAgentRole-AgentSpace"
  },
  {
    "OutputKey": "OperatorRoleArn",
    "OutputValue": "arn:aws:iam::<ACCOUNT_ID>:role/DevOpsAgentRole-WebappAdmin"
  }
]

如果您计划完成第 2 部分，请保存该AgentSpaceArn值。你需要它来配置跨账户角色。

步骤 4：验证部署

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


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

此时，您的代理空间已部署完毕，同时启用了操作员应用程序并关联了您的监控帐户。代理可以监控此账户中的问题。

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

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

在信任代理空间的服务账户中部署 IAM 角色。
在监控账户中添加指向服务帐号的源 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=<MONITORING_ACCOUNT_ID> \
    AgentSpaceArn=<AGENT_SPACE_ARN> \
  --region <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=<AGENT_SPACE_ID> \
    ServiceAccountId=<SERVICE_ACCOUNT_ID> \
    ServiceAccountRoleArn=arn:aws:iam::<SERVICE_ACCOUNT_ID>:role/DevOpsAgentRole-SecondaryAccount \
  --region <REGION>

第 3 部分：添加技能、自定义代理和预定触发器

这部分是可选的。在本节中，您将向第 1 部分中创建的代理空间添加三个资源。第一个是代理在相关时加载的技能。第二个是自定义代理，它将代理的范围限定为特定的工作流程。第三个是自动运行自定义代理的定时触发器。这些资源使用AWS::DevOpsAgent::Asset和AWS::DevOpsAgent::Trigger资源类型。有关将资产作为基础架构即代码进行管理的更多信息，请参阅管理资产。

必须先完成第 1 部分，然后才能继续。此模板需要第 1 部分AgentSpaceId的堆栈输出。

第 1 步：创建模板

将以下模板另存为devops-agent-content.yaml。基于时间的触发器的操作在表单custom:<assetId>中按资产 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 步：部署堆栈

使用监控账户凭据运行以下命令。<AGENT_SPACE_ID>替换为第 1 部分输出的值。


aws cloudformation deploy \
  --template-file devops-agent-content.yaml \
  --stack-name DevOpsAgentContentStack \
  --parameter-overrides AgentSpaceId=<AGENT_SPACE_ID> \
  --region <REGION>

AgentSpaceId、TypeCondition、和Action属性仅供创建。更改其中任何一个都将取代资源。您可以就地更新触发器Status（Active或Inactive），将其设置为在不删除触发器Inactive的情况下暂停触发器。有关其他资产类型和完整属性参考的更多信息，请参阅管理资产。

验证

运行以下 AWS CLI 命令验证您的设置：


# List your agent spaces
aws devops-agent list-agent-spaces \
  --region <REGION>

# Get details of a specific agent space
aws devops-agent get-agent-space \
  --agent-space-id <AGENT_SPACE_ID> \
  --region <REGION>

# List associations for an agent space
aws devops-agent list-associations \
  --agent-space-id <AGENT_SPACE_ID> \
  --region <REGION>

问题排查

本节介绍常见问题及其解决方法。

CloudFormation 未找到资源类型

确认您正在部署支持的区域：。
确认您的 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 <REGION>

aws cloudformation wait stack-delete-complete \
  --stack-name DevOpsAgentContentStack \
  --region <REGION>

# If you deployed the source association stack, delete it next
aws cloudformation delete-stack \
  --stack-name DevOpsAgentSourceAssociationStack \
  --region <REGION>

aws cloudformation wait stack-delete-complete \
  --stack-name DevOpsAgentSourceAssociationStack \
  --region <REGION>

# If you deployed the service account stack, delete it next (using service account credentials)
aws cloudformation delete-stack \
  --stack-name DevOpsAgentServiceAccountStack \
  --region <REGION>

aws cloudformation wait stack-delete-complete \
  --stack-name DevOpsAgentServiceAccountStack \
  --region <REGION>

# Delete the main stack last
aws cloudformation delete-stack \
  --stack-name DevOpsAgentStack \
  --region <REGION>

后续步骤

使用 AWS CloudFormation以下命令部署 AWS DevOps 代理后：

要连接其他集成，请参阅配置集成和知识。
如果您注册了第三方集成，请通过在控制台中轮换 webhook 来获取其 webhook 网址和密钥。 AWS CloudFormation 不会将 webhook 密钥作为堆栈输出返回，因为它很敏感。有关管理 webhook 凭据的说明，请参阅管理 webhook 凭据。
要了解代理技能和能力，请参阅DevOps 代理技能。
有关将技能、自定义代理和其他资产作为基础架构即代码进行管理的更多信息，请参阅管理资产。
要了解运营商 Web 应用程序，请参阅什么是 DevOps 代理 Web 应用程序？。
有关本指南中使用的 CloudFormation 资源类型的详细属性参考，请参阅AWS CloudFormation 模板参考中的AWS DevOps 代理资源类型参考。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

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

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