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

# AWS DevOps 代理 CLI 入门指南
<a name="getting-started-with-aws-devops-agent-cli-onboarding-guide"></a>

## 概述
<a name="overview"></a>

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

AWS DevOps 代理可在六个 AWS 地区使用：美国东部（弗吉尼亚北部）、美国西部（俄勒冈）、亚太地区（悉尼）、亚太地区（东京）、欧洲（法兰克福）和欧洲（爱尔兰）。有关支持的区域的更多信息，请参阅[支持的区域：](about-aws-devops-agent-supported-regions.md)。

## 先决条件
<a name="prerequisites"></a>

开始之前，请确保您拥有：
+ AWS 已安装并配置 CLI 版本 2
+ 对您的 AWS 监控账户进行身份验证
+ 创建 AWS 身份和访问管理 (IAM) Access Management 角色和附加策略的权限
+ 用作监控 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 角色设置
<a name="iam-roles-setup"></a>

### 1. 创建 DevOps 代理空间角色
<a name="1-create-the-devops-agent-space-role"></a>

通过运行以下命令创建 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 角色
<a name="2-create-the-operator-app-iam-role"></a>

通过运行以下命令创建 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
```

此托管策略向操作员应用程序授予访问代理空间功能的权限。这些功能包括调查、推荐、知识管理、聊天和 Su AWS pport 集成。该策略使用`aws:PrincipalTag/AgentSpaceId`条件限制对特定代理空间的访问权限。有关完整操作列表的更多信息，请参阅[DevOps 代理 IAM 权限](aws-devops-agent-security-devops-agent-iam-permissions.md)。

## 入职步骤
<a name="onboarding-steps"></a>

### 1. 创建代理空间
<a name="1-create-an-agent-space"></a>

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

```
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 账户
<a name="2-associate-your-aws-account"></a>

关联您的 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. 启用操作员应用程序
<a name="3-enable-the-operator-app"></a>

身份验证流程可以使用 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 身份中心身份验证](aws-devops-agent-security-setting-up-iam-identity-center-authentication.md)和[设置外部身份提供商 (IdP) 身份验证](aws-devops-agent-security-setting-up-external-identity-provider-idp-authentication.md)。

**注意：**如果您之前为账户中的其他座席空间创建了操作员应用程序角色，则可以重复使用该角色 ARN。

### 4. （可选）关联其他源账户
<a name="4-optional-associate-additional-source-accounts"></a>

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

#### 在外部账户中创建跨账户角色
<a name="create-the-cross-account-role-in-the-external-account"></a>

切换到外部账户并创建信任策略。`MONITORING_ACCOUNT_ID`是托管您在步骤 2 中设置的代理空间的主账户。此配置允许 AWS DevOps 代理服务代表监控帐户在辅助源帐户中扮演角色。

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

```
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>",
          "sts:ExternalId": "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
```

#### 关联外部账户
<a name="associate-the-external-account"></a>

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

```
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
<a name="5-optional-associate-github"></a>

**注意：**必须先使用 OAuth 流程 GitHub 通过 AWS DevOps 代理控制台进行注册，然后才能通过 CLI 进行关联。

有关 GitHub 通过控制台进行注册的说明，请参阅[连接到 CI/CD 管道](configuring-capabilities-for-aws-devops-agent-connecting-to-cicd-pipelines-index.md)。

列出注册的服务：

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

保存`<SERVICE_ID>`服务类型：。`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
<a name="6-optional-register-and-associate-servicenow"></a>

首先，使用 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
<a name="7-optional-register-and-associate-dynatrace"></a>

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

```
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 信息。你可以使用这个 webhook 来触发 Dynatrace 的调查。有关更多信息，请参阅 [连接 Dynatrace](connecting-telemetry-sources-connecting-dynatrace.md)。

### 8. （可选）注册并关联 Splunk
<a name="8-optional-register-and-associate-splunk"></a>

首先，使用 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 信息。你可以使用这个 webhook 来触发 Splunk 的调查。有关更多信息，请参阅 [连接 Splunk](connecting-telemetry-sources-connecting-splunk.md)。

### 9. （可选）注册并关联新遗物
<a name="9-optional-register-and-associate-new-relic"></a>

首先，使用 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>`，然后关联新遗物：

```
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 信息。你可以使用这个 webhook 来触发来自 New Relic 的调查。有关更多信息，请参阅 [连接新遗物](connecting-telemetry-sources-connecting-new-relic.md)。

### 10. （可选）注册并关联 Datadog
<a name="10-optional-register-and-associate-datadog"></a>

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

列出注册的服务：

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

保存`<SERVICE_ID>`服务类型：。`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 信息。你可以使用这个 webhook 来触发 Datadog 的调查。有关更多信息，请参阅 [正在连接 DataDog](connecting-telemetry-sources-connecting-datadog.md)。

### 11. （可选）删除代理空间
<a name="11-optional-delete-an-agent-space"></a>

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

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

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

## 验证
<a name="verification"></a>

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

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

## 后续步骤
<a name="next-steps"></a>
+ 要连接其他集成，请参阅[为 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)。

## 注意
<a name="notes"></a>
+ 将`<AGENT_SPACE_ID>`、`<MONITORING_ACCOUNT_ID>``<EXTERNAL_ACCOUNT_ID>`、`<REGION>`、等替换为实际值。
+ 有关受支持区域的列表，请参阅[支持的区域：](about-aws-devops-agent-supported-regions.md)。