本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 开始使用 AWS DevOps 代理 AWS CloudFormation ## 概述 本指南向您介绍如何使用 AWS CloudFormation 模板来创建和部署 AWS DevOps 代理资源。这些模板可以自动创建代理空间、Ident AWS ity and Access Management 角色、操作员应用程序 AWS 和账户关联作为基础架构即代码。 该 CloudFormation 方法通过在声明式 YAML 模板中定义所有必需的资源，自动执行 [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)。 ## 先决条件 开始之前，请确保您拥有： + 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：部署堆栈 运行以下命令部署堆栈。``替换为[支持的区域：](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 ``` ## 验证 通过运行以下 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 相符。 **跨账户部署失败** + 每个堆栈都必须使用目标账户的凭据进行部署。使用该`--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 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 代理后： + 要连接其他集成，请参阅[为 AWS DevOps 代理配置功能](configuring-capabilities-for-aws-devops-agent.md)。 + 要了解代理技能和能力，请参阅[DevOps 特工技能](about-aws-devops-agent-devops-agent-skills.md)。 + 要了解操作员 Web 应用程序，请参阅[什么是 DevOps 代理 Web 应用程序？](about-aws-devops-agent-what-is-a-devops-agent-web-app.md)。