Amazon IoT Greengrass Version 12023 年 6 月 30 日进入延长寿命阶段。有关更多信息,请参阅Amazon IoT Greengrass V1维护政策。在此日期之后,Amazon IoT Greengrass V1不会发布提供功能、增强功能、错误修复或安全补丁的更新。在上运行的设备Amazon IoT Greengrass V1不会受到干扰,将继续运行并连接到云端。我们强烈建议你迁移到Amazon IoT Greengrass Version 2,它补充说重要的新功能和支持其他平台。
本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
Amazon IoT Greengrass Core 软件的 OTA 更新
Amazon IoT GreengrassCore 软件包包含可以执行Amazon IoT Greengrass软件更新 over-the-air (OTA) 的更新代理。您可以使用 OTA 更新在一个或多个内核上安装最新版本的Amazon IoT Greengrass核心软件或 OTA 更新代理软件。通过 OTA 更新,您的核心设备无需物理连接。
我们建议您尽可能使用 OTA 更新。这提供了一种可用于跟踪更新状态和更新历史记录的机制。如果更新失败,OTA 更新代理会回滚到以前的软件版本。
注意
使用 apt
安装 Amazon IoT Greengrass Core 软件时,不支持 OTA 更新。对于这些安装,建议您使用 apt
升级软件。有关更多信息,请参阅从 APT 存储库安装 Amazon IoT Greengrass Core 软件:
OTA 更新可以更高效地执行以下操作:
-
修复安全漏洞。
-
解决软件稳定性问题。
-
部署新的或改进的功能。
此功能与 Amazon IoT 作业集成。
要求
以下要求适用于 Amazon IoT Greengrass 软件的 OTA 更新。
-
Greengrass 核心必须在本地存储中至少有 400 MB 的可用磁盘空间。OTA 更新代理需要的运行时使用量约为 Amazon IoT Greengrass Core 软件的三倍。有关更多信息,请参阅中的 Greengrass 核心的Amazon Web Services 一般参考服务配额。
-
Greengrass 核心必须与... 建立连接。Amazon Web Services 云
-
必须使用证书和密钥正确配置和预置 Greengrass Core 以便对 Amazon IoT Core 和 Amazon IoT Greengrass 进行身份验证。有关更多信息,请参阅X.509 证书:
-
Greengrass Core 不能配置为使用网络代理。
注意
从 Amazon IoT Greengrass v1.9.3 开始,将 MQTT 流量配置为使用端口 443 而不是默认端口 8883 的核心支持 OTA 更新。但是,OTA 更新代理不支持通过网络代理进行更新。有关更多信息,请参阅通过端口 443 或网络代理进行连接:
-
无法在包含 Amazon IoT Greengrass Core 软件的分区中启用可信引导。
注意
您可以在启用了可信引导的分区上安装和运行 Amazon IoT Greengrass Core 软件,但这不支持 OTA 更新。
-
Amazon IoT Greengrass 必须具有对包含 Amazon IoT Greengrass Core 软件的分区的读/写权限。
-
如果您使用 init 系统来管理 Greengrass Core,则必须配置 OTA 更新以与 init 系统集成。有关更多信息,请参阅与初始化系统集成:
-
您必须创建一个用于将 Amazon S3 网址预先分配给Amazon IoT Greengrass软件更新构件的角色。此签名者角色Amazon IoT Core允许代表您访问存储在 Amazon S3 中的软件更新项目。有关更多信息,请参阅OTA 更新的 IAM 权限:
OTA 更新的 IAM 权限
Amazon IoT Greengrass发布新版本的Amazon IoT Greengrass核心软件时,会Amazon IoT Greengrass更新存储在 Amazon S3 中用于 OTA 更新的软件构件。
您Amazon Web Services 账户必须包含可用于访问这些构件的 Amazon S3 网址签名者角色。该角色必须具有允许对目标 Amazon Web Services 区域 s 中的存储桶s3:GetObject
执行操作的权限策略。该角色还必须具有信任策略,允许 iot.amazonaws.com
作为可信实体代入角色。
- 权限策略
-
对于角色权限,您可以使用 Amazon 托管策略或创建自定义策略。
-
使用 Amazon 托管策略
GreenGrassota UpdateArtifactAccess
管理政策由提供。Amazon IoT Greengrass如果您想允许访问当前和未来支持的所有亚马逊网络服务区域Amazon IoT Greengrass,请使用此政策。 注意
在中国区域,您必须创建自定义策略。请确保在资源 ARN 中使用正确的分区。
"Resource": "arn:aws-cn:s3:::cn-north-1-greengrass-updates/*"
-
创建自定义策略
如果您想明确指定部署内核的 Amazon Web Services 区域,则应创建自定义策略。以下示例策略允许访问六个区域中的 Amazon 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/*" ] } ] }
-
- 信任策略
-
附加到角色的信任策略必须允许
sts:AssumeRole
操作并将iot.amazonaws.com
定义为委托人。这允许 Amazon IoT Core 代入该角色作为可信实体。以下是示例策略文档:{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowIotToAssumeRole", "Action": "sts:AssumeRole", "Principal": { "Service": "iot.amazonaws.com" }, "Effect": "Allow" } ] }
此外,启动 OTA 更新的用户必须具有使用 greengrass:CreateSoftwareUpdateJob
和 iot:CreateJob
的权限,并可以使用 iam:PassRole
来传递签署人角色的权限。以下是 IAM 策略示例:
{ "Version": "2012-10-17", "Statement": [ { "Action": [ "greengrass:CreateSoftwareUpdateJob" ], "Effect": "Allow", "Resource": "*" }, { "Effect": "Allow", "Action": [ "iot:CreateJob" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "iam:PassRole" ], "Resource": "
arn-of-s3-url-signer-role
" } ] }
注意事项
在对 Greengrass 核心软件启动 OTA 更新之前,要注意该操作对 Greengrass 组中设备的影响,不仅影响核心设备,还会影响在本地连接至该核心的客户端设备:
-
核心在更新期间会关闭。
-
在核心上运行的任何 Lambda 函数都将关闭。如果这些函数写入到本地资源,除非正常关闭,否则它们可能会导致这些资源的状态不正确。
-
在内核停机期间,它与的所有连接Amazon Web Services 云都将中断。客户端设备通过核心路由的消息将丢失。
-
凭证缓存会丢失。
-
容纳 Lambda 函数的待处理工作的队列将丢失。
-
长期存在的 Lambda 函数会丢失其动态状态信息,所有待处理的工作都被丢弃。
OTA 更新期间保留以下状态信息:
-
Core 配置文件
-
Greengrass 组配置
-
本地影子
-
Greengrass 日志
-
OTA 更新代理日志
Greengrass OTA 更新代理
Greengrass OTA 更新代理是设备上的软件组件,用于处理在云中创建和部署的更新作业。OTA 更新代理与 Amazon IoT Greengrass Core 软件在同一个软件包中分发。代理位于 /
。它将日志写入到 greengrass-root
/ota/ota_agent/ggc-ota/var/log/greengrass/ota/ggc_ota.txt
。
注意
greengrass-root
表示在您的设备上安装 Amazon IoT Greengrass 核心软件的路径。通常,这是 /greengrass
目录。
您可以通过手动执行二进制文件或将其集成为初始脚本(例如 systemd 服务文件)的一部分来启动 OTA 更新代理。如果您手动执行二进制文件,则应以 root 身份运行。启动时,OTA 更新代理会监听来自的Amazon IoT Greengrass软件更新任务Amazon IoT Core并按顺序执行这些任务。OTA 更新代理会忽略所有其他Amazon IoT作业类型。
以下摘录显示了用于启动、停止和重新启动 OTA 更新代理的 systemd 服务文件示例:
[Unit] Description=Greengrass OTA Daemon [Service] Type=forking Restart=on-failure ExecStart=/greengrass/ota/ota_agent/ggc-ota [Install] WantedBy=multi-user.target
作为更新目标的核心不得运行两个 OTA 更新代理实例。这样做会导致两个代理处理相同的任务,因此产生冲突。
与初始化系统集成
在 OTA 更新期间,OTA 更新代理在核心设备上重新启动二进制文件。如果二进制文件正在运行,在更新期间,当 init 系统监控 Amazon IoT Greengrass Core 软件或代理的状态时,这可能会导致冲突。为了帮助将 OTA 更新机制与您的 init 监控策略集成,您可以编写在更新前后运行的 shell 脚本。例如,您可以使用ggc_pre_update.sh
脚本在设备关闭之前备份数据或停止进程。
要让 OTA 更新代理运行这些脚本,必须在 config.json 文件中包含"managedRespawn" : true
标志。以下摘录显示了此设置:
{ "coreThing": { … }, "runtime": { … }, "managedRespawn": true … }
使用 OTA 更新的托管 Respawn
以下要求适用于managedRespawn
设置为的 OTA 更新true
:
-
/
目录中必须存在以下 shell 脚本:greengrass-root
/usr/scripts-
ggc_pre_update.sh
-
ggc_post_update.sh
-
ota_pre_update.sh
-
ota_post_update.sh
-
-
脚本必须返回成功的返回代码。
-
脚本必须由 root 拥有,并且只能由 root 执行。
-
该
ggc_pre_update.sh
脚本必须停止 Greengrass 守护进程。 -
该
ggc_post_update.sh
脚本必须启动 Greengrass 守护进程。
注意
由于 OTA 更新代理管理自己的进程,因此ota_pre_update.sh
和ota_post_update.sh
脚本无需停止或启动 OTA 服务。
OTA 更新代理从运行脚本/
。该目录树应如下所示:greengrass-root
/usr/scripts
<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
当设置managedRespawn
为时true
,OTA 更新代理会在软件更新之前和之后检查/
目录中是否有这些脚本。如果脚本不存在,则更新将失败。 Amazon IoT Greengrass不验证这些脚本的内容。最佳做法是,验证您的脚本是否正常运行,并针对错误发出相应的退出代码。greengrass-root
/usr/scripts
对于 Amazon IoT Greengrass Core 软件的 OTA 更新:
-
开始更新之前,代理运行
ggc_pre_update.sh
脚本。使用此脚本执行需要在 OTA 更新代理启动 Amazon IoT Greengrass Core 软件更新之前运行的命令,例如备份数据或停止任何正在运行的进程。以下示例显示了停止 Greengrass 守护程序的简单脚本。#!/bin/bash set -euo pipefail systemctl stop greengrass
-
完成更新后,代理运行
ggc_post_update.sh
脚本。使用此脚本执行在 OTA 更新代理启动 Amazon IoT Greengrass Core 软件更新后需要运行的命令,例如重启进程。以下示例显示了启动 Greengrass 守护程序的简单脚本。#!/bin/bash set -euo pipefail systemctl start greengrass
对于 OTA 更新代理的 OTA 更新:
-
开始更新之前,代理运行
ota_pre_update.sh
脚本。使用此脚本执行需要在 OTA 更新代理自行更新之前运行的命令,例如备份数据或停止任何正在运行的进程。 -
完成更新后,代理运行
ota_post_update.sh
脚本。将此脚本用于需要在 OTA 更新代理自行更新后运行的命令,例如重新启动进程。
注意
如果设置managedRespawn
为false
,则 OTA 更新代理不运行脚本。
创建 OTA 更新
按照以下步骤在一个或多个核心上执行 Amazon IoT Greengrass 软件的 OTA 更新:
-
确保您的核心满足 OTA 更新的要求。
注意
如果您将初始化系统配置为管理Amazon IoT Greengrass核心软件或 OTA 更新代理,请在内核上验证以下内容:
-
config.json 文件指定
"managedRespawn" : true
。 -
/
greengrassroot
/usr/scripts 目录包含以下脚本:-
ggc_pre_update.sh
-
ggc_post_update.sh
-
ota_pre_update.sh
-
ota_post_update.sh
-
有关更多信息,请参阅与初始化系统集成:
-
-
在核心设备终端中,启动 OTA 更新代理。
cd /
greengrass-root
/ota/ota_agent sudo ./ggc-ota注意
greengrass-root
表示在您的设备上安装 Amazon IoT Greengrass 核心软件的路径。通常,这是/greengrass
目录。不要在核心上启动 OTA 更新代理的多个实例,因为它可能会导致冲突。
-
使用 Amazon IoT Greengrass API 创建软件更新任务。
-
调用 CreateSoftwareUpdateJob API。在此示例过程中,我们使用 Amazon CLI 命令。
以下命令创建一个作业,用于更新核心上的 Amazon IoT Greengrass Core 软件。替换示例值,然后运行命令。
此命令将返回以下响应。
{ "IotJobId": "GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE", "IotJobArn": "arn:aws:iot:
region
:123456789012:job/GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE", "PlatformSoftwareVersion": "1.10.1" } -
从响应复制
IoTJobId
。 -
调用 DescribeJobAmazon IoT CoreAPI 以查看任务状态。将示例值替换为您的作业 ID,然后运行命令。
aws iot describe-job --job-id GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE
该命令返回一个响应对象,其中包含有关作业的信息,包括
status
和jobProcessDetails
。{ "job": { "jobArn": "arn:aws:iot:
region
:123456789012:job/GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE", "jobId": "GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE", "targetSelection": "SNAPSHOT", "status": "IN_PROGRESS", "targets": [ "arn:aws:iot:region
:123456789012:thing/myCoreDevice" ], "description": "This job was created by Greengrass to update the Greengrass Cores in the targets with version 1.10.1 of the core software running on x86_64 architecture.", "presignedUrlConfig": { "roleArn": "arn:aws::iam::123456789012:role/myS3UrlSignerRole", "expiresInSec": 3600 }, "jobExecutionsRolloutConfig": {}, "createdAt": 1588718249.079, "lastUpdatedAt": 1588718253.419, "jobProcessDetails": { "numberOfCanceledThings": 0, "numberOfSucceededThings": 0, "numberOfFailedThings": 0, "numberOfRejectedThings": 0, "numberOfQueuedThings": 1, "numberOfInProgressThings": 0, "numberOfRemovedThings": 0, "numberOfTimedOutThings": 0 }, "timeoutConfig": {} } }
有关问题排查帮助,请参阅排除 Amazon IoT Greengrass 的故障。
-
CreateSoftwareUpdateJob API
您可以使用 CreateSoftwareUpdateJob
API 更新核心设备上的Amazon IoT Greengrass核心软件或 OTA 更新代理软件。此 API 创建一个 Amazon IoT 快照作业,在更新可用时通知设备。调用 CreateSoftwareUpdateJob
后,您可以使用其他 Amazon IoT 作业命令来跟踪软件更新。有关更多信息,请参阅《Amazon IoT开发者指南》中的作业。
以下示例介绍如何使用 Amazon CLI 创建用于更新核心设备上的 Amazon IoT Greengrass Core 软件的作业:
aws greengrass create-software-update-job \ --update-targets-architecture x86_64 \ --update-targets [\"arn:aws:iot:
region
:123456789012:thing/myCoreDevice\"] \ --update-targets-operating-system ubuntu \ --software-to-update core \ --s3-url-signer-role arn:aws:iam::123456789012:role/myS3UrlSignerRole \ --update-agent-log-level WARN \ --amzn-client-token myClientToken1
create-software-update-job
命令会返回一个 JSON 响应,其中包含作业 ID、作业 ARN 和更新所安装的软件版本:
{
"IotJobId": "GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE",
"IotJobArn": "arn:aws:iot:region
:123456789012:job/GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE",
"PlatformSoftwareVersion": "1.9.2"
}
有关演示如何使用 create-software-update-job
更新核心设备的步骤,请参阅创建 OTA 更新。
create-software-update-job
命令包含以下参数:
--update-targets-architecture
-
核心设备的架构。
有效值:
armv7l
、armv6l
、x86_64
或aarch64
--update-targets
-
要更新的核心。该列表可以包含单个核心的 ARN 和其成员为核心的事物组的 ARN。有关事物组的更多信息,请参阅Amazon IoT开发人员指南中的静态事物组。
--update-targets-operating-system
-
核心设备的操作系统。
有效值:
ubuntu
、amazon_linux
、raspbian
或openwrt
--software-to-update
-
指定应更新内核的软件还是 OTA 更新代理软件。
有效值:
core
或ota_agent
--s3-url-signer-role
-
IAM 角色的 ARN 用于预签链接到Amazon IoT Greengrass软件更新构件的 Amazon S3 网址。该角色的附加权限策略必须允许对目标Amazon Web Services 区域中的存储桶
s3:GetObject
执行操作。角色还必须允许iot.amazonaws.com
代入角色作为可信实体。有关更多信息,请参阅OTA 更新的 IAM 权限: --amzn-client-token
-
(可选)用于进行幂等请求的客户端令牌。请提供一个唯一令牌,以防止因内部重试而创建重复更新。
--update-agent-log-level
-
(可选)OTA 更新代理生成的日志语句的日志级别。默认为
ERROR
。有效值:
NONE
、TRACE
、DEBUG
、VERBOSE
、INFO
、WARN
、ERROR
或FATAL
注意
CreateSoftwareUpdateJob
仅接受对以下受支持的架构和操作系统组合的请求:
-
ubuntu/x86_64
-
ubuntu/aarch64
-
amazon_linux/x86_64
-
raspbian/armv7l
-
raspbian/armv6l
-
openwrt/aarch64
-
openwrt/armv7l