AWS DevOps 代理 CLI 入门指南

概述

使用 AWS DevOps Agent，您可以监控和管理您的 AWS 基础架构。本指南引导您使用 AWS 命令行界面 (AWS CLI) 设置 AWS DevOps 代理。您可以创建 IAM 角色、设置代理空间并关联您的 AWS 账户。您还可以启用运营商应用程序，也可以选择连接第三方集成。本指南大约需要 20 分钟才能完成。

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

先决条件

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

AWS CLI 版本 2 已安装并配置
对您的 AWS 监控账户进行身份验证
创建 AWS 身份和访问管理 (IAM) 角色和附加策略的权限
用作监控账户的账户 AWS
熟悉 AWS CLI 和 JSON 语法

在本指南中，将以下占位符值替换为自己的占位符值：

<MONITORING_ACCOUNT_ID>— 您的监控（主要） AWS 账户的 12 位数账户 ID
<EXTERNAL_ACCOUNT_ID>— 要监控的辅助 AWS 账户的 12 位数账户 ID（在步骤 4 中使用）
<REGION>— 您的代理空间的 AWS 区域代码（例如，us-east-1或eu-central-1）
<AGENT_SPACE_ID>— create-agent-space 命令返回的代理空间标识符

IAM 角色设置

1. 创建 DevOps 代理空间角色

通过运行以下命令创建 IAM 信任策略：


cat > devops-agentspace-trust-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "aidevops.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "<MONITORING_ACCOUNT_ID>"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/*"
        }
      }
    }
  ]
}
EOF

创建 IAM 角色：


aws iam create-role \
  --region <REGION> \
  --role-name DevOpsAgentRole-AgentSpace \
  --assume-role-policy-document file://devops-agentspace-trust-policy.json

通过运行以下命令保存角色 ARN：


aws iam get-role --role-name DevOpsAgentRole-AgentSpace --query 'Role.Arn' --output text

附上 AWS 托管策略：


aws iam attach-role-policy \
  --role-name DevOpsAgentRole-AgentSpace \
  --policy-arn arn:aws:iam::aws:policy/AIDevOpsAgentAccessPolicy

创建并附加一个允许创建资源管理器服务相关角色的内联策略：


cat > devops-agentspace-additional-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCreateServiceLinkedRoles",
      "Effect": "Allow",
      "Action": [
        "iam:CreateServiceLinkedRole"
      ],
      "Resource": [
        "arn:aws:iam::<MONITORING_ACCOUNT_ID>:role/aws-service-role/resource-explorer-2.amazonaws.com/AWSServiceRoleForResourceExplorer"
      ]
    }
  ]
}
EOF

aws iam put-role-policy \
  --role-name DevOpsAgentRole-AgentSpace \
  --policy-name AllowCreateServiceLinkedRoles \
  --policy-document file://devops-agentspace-additional-policy.json

2. 创建运营商应用程序 IAM 角色

通过运行以下命令创建 IAM 信任策略：


cat > devops-operator-trust-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "aidevops.amazonaws.com"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession"
      ],
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "<MONITORING_ACCOUNT_ID>"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/*"
        }
      }
    }
  ]
}
EOF

创建 IAM 角色：


aws iam create-role \
  --role-name DevOpsAgentRole-WebappAdmin \
  --assume-role-policy-document file://devops-operator-trust-policy.json \
  --region <REGION>

通过运行以下命令保存角色 ARN：


aws iam get-role --role-name DevOpsAgentRole-WebappAdmin --query 'Role.Arn' --output text

附上 AWS 托管运营商应用程序政策：


aws iam attach-role-policy \
  --role-name DevOpsAgentRole-WebappAdmin \
  --policy-arn arn:aws:iam::aws:policy/AIDevOpsOperatorAppAccessPolicy

此托管策略授予运营商应用程序访问代理空间功能的权限。这些功能包括调查、建议、知识管理、聊天和 AWS 支持集成。该策略使用aws:PrincipalTag/AgentSpaceId条件限制对特定代理空间的访问权限。有关完整操作列表的更多信息，请参阅DevOps 代理 IAM 权限。

入职步骤

1. 创建代理空间

运行以下命令创建代理空间：


aws devops-agent create-agent-space \
  --name "MyAgentSpace" \
  --description "AgentSpace for monitoring my application" \
  --region <REGION>

（可选）指定--kms-key-arn使用客户管理的 AWS KMS 密钥进行加密。您还可以使用--tags添加资源标签和--locale设置代理响应的语言。

保存响应agentSpaceId中的（位于agentSpace.agentSpaceId）。

要稍后列出您的代理空间，请运行以下命令：


aws devops-agent list-agent-spaces \
  --region <REGION>

2. 关联你的 AWS 账户

关联您的 AWS 账户以开启拓扑发现。将设置accountType为以下值之一：

monitor— 代理空间存在的主账户。此账户托管代理并用于拓扑发现。
source— 代理监控的另一个帐户。在步骤 4 中关联外部帐户时使用此类型。


aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id aws \
  --configuration '{
    "aws": {
      "assumableRoleArn": "arn:aws:iam::<MONITORING_ACCOUNT_ID>:role/DevOpsAgentRole-AgentSpace",
      "accountId": "<MONITORING_ACCOUNT_ID>",
      "accountType": "monitor"
    }
  }' \
  --region <REGION>

3. 启用操作员应用程序

身份验证流程可以使用 IAM、IAM 身份中心 (IDC) 或外部身份提供商 (IdP)。运行以下命令为您的代理空间启用操作员应用程序：


aws devops-agent enable-operator-app \
  --agent-space-id <AGENT_SPACE_ID> \
  --auth-flow iam \
  --operator-app-role-arn "arn:aws:iam::<MONITORING_ACCOUNT_ID>:role/DevOpsAgentRole-WebappAdmin" \
  --region <REGION>

对于 IAM 身份中心身份验证，请使用--auth-flow idc并提供--idc-instance-arn。对于外部身份提供商，使用--auth-flow idp并提供--issuer-url--idp-client-id、和--idp-client-secret。有关更多信息，请参阅设置 IAM 身份中心身份验证和设置外部身份提供商 (IdP) 身份验证。

4. （可选）关联其他来源账户

要使用 AWS DevOps 代理监控其他账户，请创建 IAM 跨账户角色。

在外部账户中创建跨账户角色

切换到外部账户并创建信任策略。通过此信任策略， AWS DevOps 代理服务委托人 (aidevops.amazonaws.com) 可以直接在辅助账户中扮演角色。aws:SourceAccount和aws:SourceArn条件使副手的预防变得混乱。这种安全控制可防止未经授权的服务使用您的角色访问您的资源。这些条件仅允许您的主账户中的代理空间代入该角色。MONITORING_ACCOUNT_ID替换为您在步骤 2 中设置的托管代理空间的主帐户的 ID。

运行以下命令来创建信任策略：


cat > devops-cross-account-trust-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "aidevops.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "<MONITORING_ACCOUNT_ID>"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/<AGENT_SPACE_ID>"
        }
      }
    }
  ]
}
EOF

创建跨账户 IAM 角色：


aws iam create-role \
  --role-name DevOpsAgentCrossAccountRole \
  --assume-role-policy-document file://devops-cross-account-trust-policy.json

通过运行以下命令保存角色 ARN：


aws iam get-role --role-name DevOpsAgentCrossAccountRole --query 'Role.Arn' --output text

附上 AWS 托管策略：


aws iam attach-role-policy \
  --role-name DevOpsAgentCrossAccountRole \
  --policy-arn arn:aws:iam::aws:policy/AIDevOpsAgentAccessPolicy

附加内联策略以允许在外部账户中创建资源管理器服务相关角色：


cat > devops-cross-account-additional-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCreateServiceLinkedRoles",
      "Effect": "Allow",
      "Action": [
        "iam:CreateServiceLinkedRole"
      ],
      "Resource": [
        "arn:aws:iam::<EXTERNAL_ACCOUNT_ID>:role/aws-service-role/resource-explorer-2.amazonaws.com/AWSServiceRoleForResourceExplorer"
      ]
    }
  ]
}
EOF

aws iam put-role-policy \
  --role-name DevOpsAgentCrossAccountRole \
  --policy-name AllowCreateServiceLinkedRoles \
  --policy-document file://devops-cross-account-additional-policy.json

关联外部账户

切换回您的监控账户，然后运行以下命令来关联外部账户：


aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id aws \
  --configuration '{
    "sourceAws": {
      "accountId": "<EXTERNAL_ACCOUNT_ID>",
      "accountType": "source",
      "assumableRoleArn": "arn:aws:iam::<EXTERNAL_ACCOUNT_ID>:role/DevOpsAgentCrossAccountRole"
    }
  }' \
  --region <REGION>

5. （可选）助理 GitHub

有关 GitHub 通过控制台注册的说明，请参阅连接到 CI/CD 管道。

列出注册的服务：


aws devops-agent list-services \
  --region <REGION>

保存为 servic <SERVICE_ID> eType:。github

在控制台 GitHub 中注册后，通过运行以下命令关联 GitHub 存储库：


aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id <SERVICE_ID> \
  --configuration '{
    "github": {
      "repoName": "<GITHUB_REPO_NAME>",
      "repoId": "<GITHUB_REPO_ID>",
      "owner": "<GITHUB_OWNER>",
      "ownerType": "organization"
    }
  }' \
  --region <REGION>

6. （可选）注册并关联 ServiceNow

首先，使用 OAuth 凭据注册 ServiceNow 服务：


aws devops-agent register-service \
  --service servicenow \
  --service-details  '{
    "servicenow": {
      "instanceUrl": "<SERVICENOW_INSTANCE_URL>",
      "authorizationConfig": {
        "oAuthClientCredentials": {
            "clientName": "<SERVICENOW_CLIENT_NAME>",
            "clientId": "<SERVICENOW_CLIENT_ID>",
            "clientSecret": "<SERVICENOW_CLIENT_SECRET>"
        }
      }
    }
  }' \
  --region <REGION>

保存退回的<SERVICE_ID>内容，然后关联 ServiceNow：


aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id <SERVICE_ID> \
  --configuration '{
    "servicenow": {
      "instanceUrl": "<SERVICENOW_INSTANCE_URL>"
    }
  }' \
  --region <REGION>

7. （可选）注册并关联 Dynatrace

首先，使用 OAuth 凭据注册 Dynatrace 服务：


aws devops-agent register-service \
  --service dynatrace \
  --service-details '{
  "dynatrace": {
    "accountUrn": "<DYNATRACE_ACCOUNT_URN>",
    "authorizationConfig": {
        "oAuthClientCredentials": {
            "clientName": "<DYNATRACE_CLIENT_NAME>",
            "clientId": "<DYNATRACE_CLIENT_ID>",
            "clientSecret": "<DYNATRACE_CLIENT_SECRET>"
        }
      }
    }
  }' \
  --region <REGION>

保存退回的内容<SERVICE_ID>，然后关联 Dynatrace。资源是可选的。该环境指定与哪个 Dynatrace 环境相关联。


aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id <SERVICE_ID> \
  --configuration '{
    "dynatrace": {
      "envId": "<DYNATRACE_ENVIRONMENT_ID>",
      "resources": [
        "<DYNATRACE_RESOURCE_1>",
        "<DYNATRACE_RESOURCE_2>"
      ]
    }
  }' \
  --region <REGION>

该响应包含用于集成的 webhook 信息。你可以使用这个网络挂钩来触发 Dynatrace 的调查。有关更多信息，请参阅连接 Dynatrace。

8. （可选）注册并关联 Splunk

首先，使用 BearerToken 证书注册 Splunk 服务。

该端点使用以下格式：https://<XXX>.api.scs.splunk.com/<XXX>/mcp/v1/


aws devops-agent register-service \
  --service mcpserversplunk \
  --service-details '{
  "mcpserversplunk": {
    "name": "<SPLUNK_NAME>",
    "endpoint": "<SPLUNK_ENDPOINT>",
    "authorizationConfig": {
        "bearerToken": {
            "tokenName": "<SPLUNK_TOKEN_NAME>",
            "tokenValue": "<SPLUNK_TOKEN_VALUE>"
        }
      }
    }
  }' \
  --region <REGION>

保存返回的内容<SERVICE_ID>，然后关联 Splunk：


aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id <SERVICE_ID> \
  --configuration '{
    "mcpserversplunk":  {
      "name": "<SPLUNK_NAME>",
      "endpoint": "<SPLUNK_ENDPOINT>"
    }
  }' \
  --region <REGION>

该响应包含用于集成的 webhook 信息。你可以使用这个网络挂钩来触发 Splunk 的调查。有关更多信息，请参阅连接 Splunk。

9. （可选）注册并关联 New Relic

首先，使用 API 密钥凭据注册 New Relic 服务。

地区：US或者EU。

可选字段：applicationIds、entityGuids、alertPolicyIds


aws devops-agent register-service \
  --service mcpservernewrelic \
  --service-details '{
    "mcpservernewrelic": {
      "authorizationConfig": {
        "apiKey": {
          "apiKey": "<YOUR_NEW_RELIC_API_KEY>",
          "accountId": "<YOUR_ACCOUNT_ID>",
          "region": "US",
          "applicationIds": ["<APP_ID_1>", "<APP_ID_2>"],
          "entityGuids": ["<ENTITY_GUID_1>"],
          "alertPolicyIds": ["<POLICY_ID_1>"]
        }
      }
    }
  }' \
  --region <REGION>

保存返回的内容<SERVICE_ID>，然后关联 New Relic：


aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id <SERVICE_ID> \
  --configuration '{
    "mcpservernewrelic":  {
      "accountId": "<YOUR_ACCOUNT_ID>",
      "endpoint": "https://mcp.newrelic.com/mcp/"
    }
  }' \
  --region <REGION>

该响应包含用于集成的 webhook 信息。你可以使用这个网络挂钩来触发 New Relic 的调查。有关更多信息，请参阅连接新遗物。

10. （可选）注册并关联 Datadog

必须先使用 OAuth 流程通过 AWS DevOps 代理控制台注册 Datadog，然后才能通过 CLI 将其关联。有关更多信息，请参阅正在连接 DataDog。

列出注册的服务：


aws devops-agent list-services \
  --region <REGION>

保存为 servic <SERVICE_ID> eType:。mcpserverdatadog

然后关联 Datadog：


aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id <SERVICE_ID> \
  --configuration '{
    "mcpserverdatadog": {
      "name": "Datadog-MCP-Server",
      "endpoint": "<DATADOG_MCP_ENDPOINT>"
    }
  }' \
  --region <REGION>

该响应包含用于集成的 webhook 信息。你可以使用这个网络挂钩来触发来自 Datadog 的调查。有关更多信息，请参阅正在连接 DataDog。

11. （可选）创建技能、自定义代理和预定触发器

您可以向代理提供自定义知识，并通过在代理空间中创建资产和触发器来按计划实现自动化。此示例创建了一项技能、一个自定义代理和一个基于时间的触发器，该触发器每天运行自定义代理。有关管理资产的更多信息，请参阅管理资产。

创建相关时代理加载的技能：


aws devops-agent create-asset \
  --agent-space-id <AGENT_SPACE_ID> \
  --asset-type skill \
  --metadata '{"name":"rds-performance-investigation","description":"Investigation procedures for RDS performance issues.","agent_types":["GENERIC"]}' \
  --content '{"file":{"path":"SKILL.md","body":{"text":"# RDS Performance Investigation\nUse this skill when investigating database latency, connection errors, or query timeouts."}}}' \
  --region <REGION>

创建触发器可以调用的自定义代理。请注意响应assetId中的——触发器将其引用为：custom:<assetId>


aws devops-agent create-asset \
  --agent-space-id <AGENT_SPACE_ID> \
  --asset-type custom_agent \
  --metadata '{"name":"rds-firefighter","skills":["rds-performance-investigation"]}' \
  --content '{"file":{"path":"AGENT.md","body":{"text":"# RDS Firefighter\nCustom agent for RDS incidents."}}}' \
  --region <REGION>

创建基于时间的触发器，每天运行自定义代理。<CUSTOM_AGENT_ASSET_ID>替换为先前回复assetId中的内容：


aws devops-agent create-trigger \
  --agent-space-id <AGENT_SPACE_ID> \
  --type TIME_BASED \
  --condition '{"schedule":{"expression":"rate(1 day)"}}' \
  --action '{"actionType":"create:task","task":{"agent":"custom:<CUSTOM_AGENT_ASSET_ID>"}}' \
  --status Active \
  --region <REGION>

回应包括triggerId. 记下这个值——你可以像在下一个命令<TRIGGER_ID>中一样使用它。

要在不删除触发器的情况下暂停触发器，请将其状态更新为Inactive：


aws devops-agent update-trigger \
  --agent-space-id <AGENT_SPACE_ID> \
  --trigger-id <TRIGGER_ID> \
  --status Inactive \
  --region <REGION>

12. （可选）删除代理空间

删除代理空间会删除该代理空间的所有关联、配置和调查数据。此操作无法撤消。

要删除代理空间，请运行以下命令：


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

验证

要验证您的设置，请运行以下命令：


# 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>

后续步骤

要连接其他集成，请参阅配置集成和知识。
要了解代理技能和能力，请参阅DevOps 代理技能。
有关将技能、自定义代理和其他资产作为基础架构即代码进行管理的更多信息，请参阅管理资产。
要了解运营商 Web 应用程序，请参阅什么是 DevOps 代理 Web 应用程序？。

注意

将<AGENT_SPACE_ID>、<MONITORING_ACCOUNT_ID>、<EXTERNAL_ACCOUNT_ID><REGION>、等替换为您的实际值。
有关受支持区域的列表，请参阅支持的区域：。

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

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

文档惯例

创建代理空间

创建测试环境