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

# Systems Manager Agent
<a name="systems-manager-agent-component"></a>

 Amazon Systems Manager 代理组件 (`aws.greengrass.SystemsManagerAgent`) 会安装 Systems Manager 代理，因此您可以使用 Systems Manager 管理核心设备。Systems Manager 是一项可用于查看和控制基础设施的 Amazon 服务 Amazon，包括亚马逊 EC2 实例、本地服务器和虚拟机 (VMs) 以及边缘设备。Systems Manager 允许您查看操作数据、自动执行操作任务以及维护安全与合规性。有关更多信息，请参阅[什么是 Amazon Systems Manager？](https://docs.amazonaws.cn/systems-manager/latest/userguide/what-is-systems-manager.html) 以及《*Amazon Systems Manager 用户指南》*中的 “[关于 Systems Manager 代理](https://docs.amazonaws.cn/systems-manager/latest/userguide/prereqs-ssm-agent.html)”。

<a name="about-systems-manager-capabilities"></a>Systems Manager 的工具和功能称为*功能*。Greengrass 核心设备支持 Systems Manager 的所有功能。有关这些功能以及如何使用 Systems Manager 管理核心设备的更多信息，请参阅《Amazon Systems Manager 用户指南》**中的 [Systems Manager 功能](https://docs.amazonaws.cn/systems-manager/latest/userguide/features.html)。

**Topics**
+ [版本](#systems-manager-agent-component-versions)
+ [Type](#systems-manager-agent-component-type)
+ [操作系统](#systems-manager-agent-component-os-support)
+ [要求](#systems-manager-agent-component-requirements)
+ [依赖项](#systems-manager-agent-component-dependencies)
+ [配置](#systems-manager-agent-component-configuration)
+ [本地日志文件](#systems-manager-agent-component-log-file)
+ [另请参阅](#systems-manager-agent-component-see-also)
+ [更改日志](#systems-manager-agent-component-changelog)

## 版本
<a name="systems-manager-agent-component-versions"></a>

此组件具有以下版本：
+ 1.3.x
+ 1.2.x
+ 1.1.x
+ 1.0.x

## Type
<a name="systems-manager-agent-component-type"></a>

<a name="public-component-type-generic"></a>此<a name="public-component-type-generic-phrase"></a>组件是一个通用组件 (`aws.greengrass.generic`)。[Greengrass Nucleus](greengrass-nucleus-component.md) 运行组件的生命周期脚本。

<a name="public-component-type-more-information"></a>有关更多信息，请参阅[组件类型](develop-greengrass-components.md#component-types)。

## 操作系统
<a name="systems-manager-agent-component-os-support"></a>

此组件只能安装在 Linux 核心设备上。

## 要求
<a name="systems-manager-agent-component-requirements"></a>

此组件具有以下要求：
+ 一款在 64 位 Linux 平台上运行的 Greengrass 核心设备：Armv8 () 或 x86\$164。AArch64
+ 您必须拥有 Systems Manager 可以担任的 Amazon Identity and Access Management (IAM) 服务角色。此角色必须包含 [Amazon SSMManaged InstanceCore](https://console.amazonaws.cn/iam/home#/policies/arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore) 托管策略或定义等效权限的自定义策略。有关更多信息，请参阅《Amazon Systems Manager 用户指南》[https://docs.amazonaws.cn/systems-manager/latest/userguide/systems-manager-setting-up-edge-devices.html#systems-manager-setting-up-edge-devices-service-role](https://docs.amazonaws.cn/systems-manager/latest/userguide/systems-manager-setting-up-edge-devices.html#systems-manager-setting-up-edge-devices-service-role)中的*为边缘设备创建 IAM 服务角色*。

  部署此组件时，您必须为 `SSMRegistrationRole` 配置参数指定此角色的名称。
+ [Greengrass 设备](device-service-role.md)角色必须允许 `ssm:AddTagsToResource` 和 `ssm:RegisterManagedInstance` 操作。设备角色还必须允许针对满足先前要求的 IAM 服务角色的 `iam:PassRole` 操作。以下示例 IAM 策略授予这些权限。

  ```
  {
    "Version": "2012-10-17",		 	 	 
    "Statement": [
      {
        "Action": [
          "iam:PassRole"
        ],
        "Effect": "Allow",
        "Resource": [
          "arn:aws:iam::account-id:role/SSMServiceRole"
        ]
      },
      {
        "Action": [
          "ssm:AddTagsToResource",
          "ssm:RegisterManagedInstance"
        ],
        "Effect": "Allow",
        "Resource": "*"
      }
    ]
  }
  ```

### 端点和端口
<a name="systems-manager-agent-component-endpoints"></a>

除基本操作所需的端点和端口外，此组件还必须能够对以下端点和端口执行出站请求。有关更多信息，请参阅 [允许设备流量通过代理或防火墙](allow-device-traffic.md)。


| 终端节点 | 端口 | 必需 | 描述 | 
| --- | --- | --- | --- | 
|  `ec2messages.region.amazonaws.com`  | 443 | 是 |  在 Amazon Web Services 云中与 Systems Manager 服务通信。  | 
|  `ssm.region.amazonaws.com`  | 443 | 是 |  将核心设备注册为 Systems Manager 托管节点。  | 
|  `ssmmessages.region.amazonaws.com`  | 443 | 是 |  在 Amazon Web Services 云中与 Systems Manager 的一项功能 Session Manager 通信。  | 

有关更多信息，请参阅《Amazon Systems Manager 用户指南》**中的[参考：ec2messages、ssmmessages 和其它 API 调用](https://docs.amazonaws.cn/systems-manager/latest/userguide/systems-manager-setting-up-messageAPIs.html)。

## 依赖项
<a name="systems-manager-agent-component-dependencies"></a>

部署组件时， Amazon IoT Greengrass 还会部署其依赖项的兼容版本。这意味着您必须满足组件及其所有依赖关系的要求，才能成功部署组件。本部分列出了此组件的[已发布版本](#systems-manager-agent-component-changelog)的依赖关系，以及定义每个依赖关系的组件版本的语义版本约束。您还可以在 [Amazon IoT Greengrass 控制台](https://console.amazonaws.cn//greengrass)中查看每个组件版本的依赖关系。在组件详细信息页面上，查找**依赖关系**列表。

下表列出了此组件的 1.0.0 到 1.3.0 版本的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [令牌交换服务](token-exchange-service-component.md) |  >=2.0.0 <3.0.0 | 硬性 | 

有关组件依赖关系的更多信息，请参阅[组件配方参考](component-recipe-reference.md#recipe-reference-component-dependencies)。

## 配置
<a name="systems-manager-agent-component-configuration"></a>

此组件提供您可以在部署组件时自定义的以下配置参数。

`SSMRegistrationRole`  
Systems Manager 可以担任的 IAM 服务角色，其中包括[亚马逊SSMManagedInstanceCore](https://console.amazonaws.cn/iam/home#/policies/arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore)托管策略或定义等效权限的自定义策略。有关更多信息，请参阅《Amazon Systems Manager 用户指南》[https://docs.amazonaws.cn/systems-manager/latest/userguide/systems-manager-setting-up-edge-devices-service-role.html](https://docs.amazonaws.cn/systems-manager/latest/userguide/systems-manager-setting-up-edge-devices-service-role.html)中的*为边缘设备创建 IAM 服务角色*。

`SSMOverrideExistingRegistration`  
（可选）如果核心设备已经运行通过混合激活注册的 Systems Manager Agent，您可以覆盖该设备的现有 Systems Manager Agent 注册。将此选项设置为 `true`，使用此组件提供的 Systems Manager Agent 将核心设备注册为托管节点。  
此选项仅适用于通过混合激活注册的设备。如果核心设备在安装了 Systems Manager 代理并配置了 EC2 实例配置文件角色的亚马逊实例上运行，则亚马逊 EC2 实例的现有托管节点 ID 以开头`i-`。当您安装 Systems Manager Agent 组件时，Systems Manager Agent 会注册一个新的托管节点，该节点的 ID 以 `mi-`（而不是 `i-`）开头。然后，您可以使用 ID 以 `mi-` 开头的托管节点通过 Systems Manager 管理核心设备。
默认值：`false`

`SSMResourceTags`  
（可选）要添加到此组件为核心设备创建的 Systems Manager 托管节点的标签。您可以使用这些标签通过 Systems Manager 管理核心设备组。例如，您可以在所有带您指定的标签的设备上运行命令。  
指定一个列表，其中每个标签都是带 `Key` 和 `Value` 的对象。例如，`SSMResourceTags` 的以下值指示此组件在核心设备的托管节点上将 **Owner** 标签设置为 **richard-roe**。  

```
[
  {
    "Key": "Owner",
    "Value": "richard-roe"
  }
]
```
如果托管节点已经存在并且 `SSMOverrideExistingRegistration` 为 `false`，则此组件将忽略这些标签。

**Example 示例：配置合并更新**  
以下示例配置指定使用名为 `SSMServiceRole` 的服务角色，以允许核心设备注册 Systems Manager 并与其通信。  

```
{
  "SSMRegistrationRole": "SSMServiceRole",
  "SSMOverrideExistingRegistration": false,
  "SSMResourceTags": [
    {
      "Key": "Owner",
      "Value": "richard-roe"
    },
    {
      "Key": "Team",
      "Value": "solar"
    }
  ]
}
```

## 本地日志文件
<a name="systems-manager-agent-component-log-file"></a>

Systems Manager Agent 软件将日志写入 Greengrass 根文件夹之外的文件夹。有关更多信息，请参阅《Amazon Systems Manager 用户指南》**中的[查看 Systems Manager Agent 日志](https://docs.amazonaws.cn/systems-manager/latest/userguide/sysman-agent-logs.html)。

Systems Manager Agent 组件使用 Shell 脚本安装、启动和停止 Systems Manager Agent。您可以在以下日志文件中找到这些脚本的输出。

```
/greengrass/v2/logs/aws.greengrass.SystemsManagerAgent.log
```

**查看此组件的日志**
+ 在核心设备上运行以下命令可实时查看此组件的日志文件。`/greengrass/v2`替换为 Amazon IoT Greengrass 根文件夹的路径。

  ```
  sudo tail -f /greengrass/v2/logs/aws.greengrass.SystemsManagerAgent.log
  ```

## 另请参阅
<a name="systems-manager-agent-component-see-also"></a>
+ [通过 Amazon Systems Manager 管理 Greengrass 核心设备](manage-with-systems-manager.md)
+ *Amazon Systems Manager 用户指南* 中的[什么是 Amazon Systems Manager？](https://docs.amazonaws.cn/systems-manager/latest/userguide/what-is-systems-manager.html)
+ 《Amazon Systems Manager 用户指南》**中的[关于 Systems Manager Agent](https://docs.amazonaws.cn/systems-manager/latest/userguide/prereqs-ssm-agent.html)

## 更改日志
<a name="systems-manager-agent-component-changelog"></a>

下表介绍每个组件版本的更改。


|  **版本**  |  **更改**  | 
| --- | --- | 
|  1.3.0  |  [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/greengrass/v2/developerguide/systems-manager-agent-component.html)  | 
|  1.2.4  |  [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/greengrass/v2/developerguide/systems-manager-agent-component.html)  | 
|  1.2.3  |  [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/greengrass/v2/developerguide/systems-manager-agent-component.html)  | 
|  1.1.0  |  此版本包含错误修复和改进。  | 
|  1.0.0  |  初始版本。  |