AWS IoT Greengrass
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

AWS IoT Greengrass 核心软件的 OTA 更新

此功能适用于 AWS IoT Greengrass Core 1.3 及更高版本。

AWS IoT Greengrass 核心软件打包了一个代理,此代理可以将核心的软件或代理本身更新到最新版本。这些更新通过无线 (OTA) 方式发送。OTA 更新是用于更新 AWS IoT Greengrass Core 设备上的 AWS IoT Greengrass 软件的建议方法。您可以使用 AWS IoT 控制台 或 CreateSoftwareUpdateJob API 启动更新。通过使用 OTA 更新,您可以:

  • 修复安全漏洞。

  • 解决软件稳定性问题。

  • 部署新的或改进的功能。

您不必执行手动步骤,也不必具有实际运行核心软件的设备。在更新失败时,OTA 更新代理执行回滚。

为支持 AWS IoT Greengrass 软件的 OTA 更新,您的 Greengrass 核心设备必须:

  • 拥有三倍于核心运行时用量要求的可用本地存储。有关更多信息,请参阅 Amazon Web Services 一般参考 中的 AWS IoT Greengrass 核心限制

  • 未在包含 Greengrass 核心平台软件的分区中启用可信引导。(AWS IoT Greengrass Core可在启用了可信引导的分区中安装和运行,但无法执行 OTA 更新。)

  • 对包含 Greengrass 核心平台软件的分区具有读/写权限。

  • 未配置为使用网络代理。在 AWS IoT Greengrass 核心版本 1.9.3 中,当 MQTT 流量配置为使用端口 443 而不是默认端口 8883 时,OTA 更新代理 支持通过端口 443 进行更新。但是,OTA 更新代理 不支持通过网络代理进行更新。有关更多信息,请参阅 通过端口 443 或网络代理进行连接

  • 具有到 AWS 云的连接。

  • 具有正确配置的 AWS IoT Greengrass Core和相应的证书。

在对 Greengrass 核心软件启动 OTA 更新之前,要注意该操作对 Greengrass 组中设备的影响,不仅影响核心设备,还会影响在本地连接至该核心的客户端设备:

  • 核心在更新期间会关闭。

  • 在核心上运行的任何 Lambda 函数都将关闭。如果这些函数写入到本地资源,除非正常关闭,否则它们可能会导致这些资源的状态不正确。

  • 在核心的停机时间内,与 AWS 云的所有连接都将丢失。客户端设备通过核心路由的消息将丢失。

  • 凭证缓存会丢失。

  • 容纳 Lambda 函数的待处理工作的队列将丢失。

  • 长时间生存的 Lambda 函数将丢失其动态状态信息,并且将丢弃所有待处理工作。

OTA 更新期间保留以下状态信息:

  • 本地影子

  • Greengrass 日志

  • OTA 更新代理日志

Greengrass OTA 更新代理

Greengrass OTA 更新代理是设备上的软件组件,可处理在云中创建和部署的更新作业。Greengrass OTA 更新代理 分布在与 AWS IoT Greengrass 核心软件相同的软件包中。代理位于 ./greengrass/ota/ota_agent/ggc-ota。它在 /var/log/greengrass/ota/ggc_ota.txt 中创建其日志。

您可以通过手动执行二进制文件或通过作为 init 脚本的一部分(如 systemd 服务文件)集成来启动 Greengrass OTA 更新代理。该二进制文件应作为根命令运行。当它启动时,Greengrass OTA 更新代理将侦听云中的 Greengrass 更新作业,并按顺序执行这些作业。Greengrass OTA 更新代理将忽略所有其他 IoT 作业类型。

请勿启动多个 OTA 更新代理实例,因为这可能导致冲突。

如果您的 Greengrass 核心或 Greengrass OTA 更新代理由初始化系统托管,请参阅与初始化系统集成以了解相关配置。

CreateSoftwareUpdateJob API

CreateSoftwareUpdateJob API 为一个或几个核心创建软件更新。此 API 可用来更新 OTA 更新代理和 Greengrass 核心软件。它利用 AWS IoT 作业(可提供其他命令)来管理 Greengrass 核心上的软件更新作业。有关更多信息,请参阅任务

以下示例介绍如何使用 CLI 创建用于更新核心设备上的 AWS IoT Greengrass 核心软件的作业:

aws greengrass create-software-update-job \ --update-targets-architecture x86_64 \ --update-targets arn:aws-cn::iot:区域:123456789012:thing/myDevice \ --update-targets-operating-system ubuntu \ --software-to-update core \ --s3-url-signer-role arn:aws-cn::iam::123456789012:role/IotS3UrlPresigningRole \ --update-agent-log-level WARN \ --amzn-client-token myClientToken1

create-software-update-job 命令会返回一个 JSON 响应,其中包含作业 ID、作业 ARN 和更新所安装的软件版本:

{ "IotJobId": "Greengrass-OTA-c3bd7f36-ee80-4d42-8321-a1da0e5b1303", "IotJobArn": "arn:aws-cn::iot:区域:123456789012:job/Greengrass-OTA-c3bd7f36-ee80-4d42-8321-a1da0e5b1303", "PlatformSoftwareVersion": "1.9.2" }

create-software-update-job 命令包含以下参数:

--update-targets-architecture

核心设备的架构。必须为以下值之一:armv7larmv6lx86_64aarch64

--update-targets

要应用 OTA 更新的目标列表。该列表可能包含事物(核心)的 ARN 以及事物组(其成员为核心)的 ARN。有关更多信息,请参阅 IoT 事物组

--update-targets-operating-system

核心设备的操作系统。必须为以下值之一:ubuntuamazon_linuxraspbianopenwrt

--software-to-update

指定应该更新核心的软件还是 OTA 更新代理软件。必须为以下值之一:coreota_agent

--s3-url-signer-role

用于预签名 S3 URL(链接至 AWS IoT Greengrass 软件更新)的 IAM 角色。您必须提供一个附加了适当权限策略的角色。以下示例策略允许访问指定的 AWS 区域中的 AWS IoT Greengrass 软件更新:

{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowAccessToGreengrassOTAUpdateArtifacts", "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::us-east-1-greengrass-updates/*", "arn:aws:s3:::us-west-2-greengrass-updates/*", "arn:aws:s3:::ap-northeast-1-greengrass-updates/*", "arn:aws:s3:::ap-southeast-2-greengrass-updates/*", "arn:aws:s3:::eu-central-1-greengrass-updates/*", "arn:aws:s3:::eu-west-1-greengrass-updates/*" ] } ] }

注意

您还可以为 Resource 属性使用通配符 * 命名方案以允许访问 AWS IoT Greengrass 软件更新。例如,以下格式允许访问使用 aws 分区的所有受支持 AWS 区域(当前和未来)的软件更新。请确保为您要支持的 AWS 区域使用正确的分区。

"Resource": "arn:aws:s3:::*-greengrass-updates/*"

有关更多信息,请参阅 IAM 用户指南 中的添加和删除 IAM 策略

下面是一个包含要求最低的可信实体的 AssumeRole 策略文档示例:

{ "Version": "2012-10-17", "Statement": [ { "Action": "sts:AssumeRole", "Principal": { "Service": "iot.amazonaws.com.cn" }, "Effect": "Allow", "Sid": "AllowIotToAssumeRole" } ] }
--amzn-client-token

(可选)用于进行幂等请求的客户端令牌。请提供一个唯一令牌,以防止因内部重试而创建重复更新。

--update-agent-log-level

(可选)OTA 更新代理生成的日志语句的日志记录级别。必须为以下值之一:NONETRACEDEBUGVERBOSEINFOWARNERRORFATAL。默认为 ERROR

下面是一个具有调用 API 所需的最低权限的 IAM 策略示例:

{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowCreateSoftwareUpdateJob", "Action": [ "greengrass:CreateSoftwareUpdateJob" ], "Effect": "Allow", "Resource": "*" }, { "Effect": "Allow", "Action": [ "iam:PassRole" ], "Resource": "arn:aws:s3:us-east-1:123456789012:role/IotS3UrlPresigningRole" }, { "Effect": "Allow", "Action": [ "iot:CreateJob" ], "Resource": "*" } ] }

注意

由于 AWS IoT Greengrass 仅在使用此命令实现的架构和操作系统组合的子集上受支持,因此 CreateSoftwareUpdateJob 将拒绝请求,除非是以下受支持的平台:

  • ubuntu/x86_64

  • ubuntu/aarch64

  • amazon_linux/x86_64

  • raspbian/armv7l

  • raspbian/armv6l

  • openwrt/aarch64

  • openwrt/armv7l

与初始化系统集成

在 OTA 更新期间,系统将更新并重新启动二进制文件(包括某些正在运行的文件)。如果在更新期间初始化系统正在监控 AWS IoT Greengrass 核心软件或 Greengrass OTA 更新代理的状态,那么上述操作可能引起冲突。为了帮助将 OTA 更新机制与您的监控策略集成,您可以编写在更新前后运行的 shell 脚本。要告诉 OTA 更新代理运行这些 shell 脚本,您必须在 ./greengrass/config/config.json 文件中包含 "managedRespawn" : true 标志。例如:

{ "coreThing": { … }, "runtime": { … }, "managedRespawn": true }

managedRespawn 设置为 true 后,脚本必须存在于此目录中。否则,更新将失败。该目录树应如下所示:

<greengrass_root> |-- certs |-- config | |-- config.json |-- ggc |-- usr/scripts | |-- ggc_pre_update.sh | |-- ggc_post_update.sh | |-- ota_pre_update.sh | |-- ota_post_update.sh |-- ota

使用托管的 Respawn 执行 OTA 自行更新

由于 OTA 更新代理准备执行自行更新,如果 managedRespawn 设置为 true,则 OTA 更新代理将在 ./greengrass/usr/scripts 目录中查找 ota_pre_update.sh 脚本并运行它。

OTA 更新代理完成更新后,将尝试从 ./greengrass/usr/scripts 目录运行 ota_post_update.sh 脚本。

使用托管的 Respawn 执行 AWS IoT Greengrass 核心更新

由于 OTA 更新代理准备执行 AWS IoT Greengrass Core 更新,如果 managedRespawn 设置为 true,则 OTA 更新代理将在 ./greengrass/usr/scripts 目录中查找 ggc_pre_update.sh 脚本并运行它。

OTA 更新代理完成更新后,将尝试从 ./greengrass/usr/scripts 目录运行 ggc_post_update.sh 脚本。

  • ./greengrass/usr/scripts 中的用户定义的脚本应归 root 所有,且只能由 root 执行。

  • 如果 managedRespawn 设置为 true,则脚本必须存在并返回成功的返回代码。

  • 如果 managedRespawn 设置为 false,则即使脚本存在于设备上,也不会运行。

  • 作为更新目标的设备不得针对同一 AWS IoT 事物运行两个 OTA 更新代理 实例。这样做会导致两个代理处理相同的任务,因此产生冲突。

OTA 更新代理自行更新

按照以下步骤执行 OTA 更新代理的自行更新:

  1. 确保使用有效的 config.json 文件条目和需要的证书确保正确预配置 AWS IoT Greengrass Core 设备。

  2. 如果 OTA 更新代理正在由初始化系统托管,在 config.json 文件中,确保 managedRespawn 属性设置为 true。此外,确保 ota_pre_update.shota_post_update.sh 脚本位于 ./greengrass/usr/scripts 目录中。

  3. 运行 ./greengrass/ota/ota_agent/ggc-ota

  4. 使用 CreateSoftwareUpdateJob API 创建 OTA 自行更新作业。确保将 --software-to-update 参数设置为 ota_agent

Greengrass 核心软件更新

按照以下步骤执行 AWS IoT Greengrass 核心软件更新:

  1. 确保使用有效的 config.json 文件条目和需要的证书确保正确预配置 AWS IoT Greengrass Core 设备。

  2. 如果 AWS IoT Greengrass 核心软件正在由初始化系统托管,在 config.json 文件中,确保 managedRespawn 属性设置为 true。此外,确保 ggc_pre_update.shggc_post_update.sh 脚本位于 ./greengrass/usr/scripts 目录中。

  3. 运行 ./greengrass/ota/ota_agent/ggc-ota

  4. 使用 CreateSoftwareUpdateJob API 创建核心软件的更新作业。确保将 --software-to-update 参数设置为 core