View a markdown version of this page

开始使用 AWS DevOps 代理 AWS CloudFormation - AWS DevOps 代理人
概述先决条件本指南涵盖的内容第 1 部分：部署代理空间第 2 部分（可选）：添加跨账户监控验证问题排查清理后续步骤

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

开始使用 AWS DevOps 代理 AWS CloudFormation

概述

本指南向您介绍如何使用 AWS CloudFormation 模板来创建和部署 AWS DevOps 代理资源。这些模板可以自动创建代理空间、Ident AWS ity and Access Management 角色、操作员应用程序 AWS 和账户关联作为基础架构即代码。

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

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

先决条件

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

  • AWS 已安装命令行接口 (AWS CLI)，并使用相应的凭据进行配置

  • 创建 IAM 角色和 CloudFormation 堆栈的权限

  • 一个 AWS 用于监控（主要）账户的账户

  • （可选）如果您想设置跨 AWS 账户监控，则需要第二个账户

本指南涵盖的内容

本指南分为两部分：

  • 第 1 部分 — 在您的监控账户中部署带有操作员应用程序和 AWS 关联的代理空间。完成本部分后，代理可以监控该账户中的问题。

  • 第 2 部分（可选）— 将跨账户 IAM 角色部署到辅助账户并添加源 AWS 关联。此配置使代理空间能够跨账户监控资源。

第 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 帐户（服务帐户）中的资源。这涉及两个操作：

  1. 在信任代理空间的服务账户中部署 IAM 角色。

  2. 在监控账户中添加指向服务帐号的源 AWS 关联。

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

验证

通过运行以下 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 相符。

跨账户部署失败

  • 每个堆栈都必须使用目标账户的凭据进行部署。使用该--profile标志指定正确的 AWS CLI 配置文件。

  • 验证AgentSpaceArn参数是否与第 1 部分堆栈输出中的精确 ARN 相匹配。

IAM 传播延迟

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

清理

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

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

运行以下命令删除堆栈：

# If you deployed the source association stack, delete it first
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 代理后：