Amazon IoT Greengrass Core 软件的 OTA 更新 - Amazon IoT Greengrass
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

Amazon IoT Greengrass Version 1在 2023 年 6 月 30 日之前,将不再接收功能更新,并且将仅收到安全补丁和错误修复。有关更多信息,请参阅Amazon IoT Greengrass V1维护时段。我们强烈建议您迁移到Amazon IoT Greengrass Version 2,这增加了重要的新功能支持其他平台

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

Amazon IoT Greengrass Core 软件的 OTA 更新

这些区域有:Amazon IoT GreengrassCore 软件包中包含可执行的更新代理 over-the-air(OTA) 更新Amazon IoT Greengrass软件。您可以使用 OTA 更新安装最新版本的 OTA 更新来安装最新版本的 OTA 更新。Amazon IoT GreengrassCore 软件核心上的核心软件或 OTA 更新代理软件。通过 OTA 更新,您的核心设备无需物理连接。

我们建议您尽可能使用 OTA 更新。这提供了一种可用于跟踪更新状态和更新历史记录的机制。如果更新失败,OTA 更新代理将回滚到以前的软件版本。

注意

使用 apt 安装 Amazon IoT Greengrass Core 软件时,不支持 OTA 更新。对于这些安装,建议您使用 apt 升级软件。有关更多信息,请参阅 从 APT 存储库安装 Amazon IoT Greengrass Core 软件

OTA 更新可以更高效地执行以下操作:

  • 修复安全漏洞。

  • 解决软件稳定性问题。

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

此功能与 Amazon IoT 作业集成。

要求

以下要求适用于 Amazon IoT Greengrass 软件的 OTA 更新。

  • Greengrass Core 在本地存储中必须至少有400 MB磁盘空间可用。OTA 更新代理的运行时使用需求是Amazon IoT GreengrassCore 软件。有关更多信息,请参阅 。服务配额在的 Greengrass 核心Amazon Web Services 一般参考.

  • Greengrass 核心必须具有到 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 URL 预签名的角色。Amazon IoT Greengrass软件更新构件。此签名者角色允许Amazon IoT Core以代表您访问存储在 Amazon S3 中的软件更新项目。有关更多信息,请参阅 OTA 更新的 IAM 权限

OTA 更新的 IAM 权限

何时Amazon IoT Greengrass发布了新版本的Amazon IoT GreengrassCore 软件核心软件,Amazon IoT Greengrass更新存储在 Amazon S3 中用于 OTA 更新的中的软件构件。

您的Amazon Web Services 账户必须包含可用于访问这些构件的 Amazon S3 URL 签署人角色。该角色必须具有允许s3:GetObject对目标中的存储桶的操作Amazon Web Services 区域。该角色还必须具有信任策略,允许 iot.amazonaws.com 作为可信实体代入角色。

权限策略

对于角色权限,您可以使用 Amazon 托管策略或创建自定义策略。

  • 使用 Amazon 托管策略

    这些区域有:绿色格拉索塔UpdateArtifactAccess托管策略由提供Amazon IoT Greengrass. 如果您希望允许访问支持的所有Amazon Web Services 科技区域,请使用此策略Amazon IoT Greengrass,包括当前和future。

    注意

    在中国区域中,您必须创建自定义策略。请确保在资源 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:CreateSoftwareUpdateJobiot: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 更新代理分布在与 OTA 更新代理相同的软件包中。Amazon IoT GreengrassCore 软件。代理位于 /greengrass-root/ota/ota_agent/ggc-ota。它将日志写入到 /var/log/greengrass/ota/ggc_ota.txt

注意

greengrass-root 表示在您的设备上安装 Amazon IoT Greengrass 核心软件的路径。通常,这是 /greengrass 目录。

您可以通过手动执行二进制文件或通过作为 init 脚本的一部分(如 systemd 服务文件)集成来启动 OTA 更新代理。如果您手动执行该二进制文件,则应作为根命令运行。当它启动时,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 更新代理运行这些脚本,您必须包含 OTA 更新代理运行这些脚本。"managedRespawn" : true在中标志config.json文件。以下摘录显示了此设置:

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

使用 OTA 更新的托管 Respawn

以下要求适用于具有以下要求的 OTA 更新。managedRespawn设置为true

  • 下列 shell 脚本必须存在于/greengrass-root/usr/scriptsdirecor

    • 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.shota_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 更新代理检查 OTA 更新代理检查/greengrass-root/usr/scripts软件更新前后这些脚本的目录。如果脚本不存在,则更新将失败。Amazon IoT Greengrass不验证这些脚本的内容。作为最佳实践,请验证脚本是否正常运行,并为错误发出相应的退出代码。

对于 Amazon IoT Greengrass Core 软件的 OTA 更新:
  • 开始更新之前,代理运行 ggc_pre_update.sh 脚本。对于需要在 OTA 更新代理启动之前运行的命令,请使用此脚本Amazon IoT Greengrass核心软件更新,例如备份数据或停止任何正在运行的进程。以下示例显示停止 Greengrass 守护程序的简单脚本。

    #!/bin/bash set -euo pipefail systemctl stop greengrass
  • 完成更新后,代理运行 ggc_post_update.sh 脚本。对于需要在 OTA 更新代理启动后运行的命令,请使用此脚本Amazon IoT Greengrass核心软件更新,例如重新启动进程。以下示例显示启动 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 更新:

  1. 确保您的核心满足 OTA 更新的要求

    注意

    如果您将 init 系统配置为管理 init 系统来管理Amazon IoT GreengrassCore 软件或 OTA 更新代理,验证核心上的以下内容:

    • config.json 文件指定 "managedRespawn" : true

    • /greengrass/usr/scripts 目录包含以下脚本:

      • ggc_pre_update.sh

      • ggc_post_update.sh

      • ota_pre_update.sh

      • ota_post_update.sh

    有关更多信息,请参阅 与初始化系统集成

  2. 在核心设备终端中,启动 OTA 更新代理。

    cd /greengrass-root/ota/ota_agent sudo ./ggc-ota
    注意

    greengrass-root 表示在您的设备上安装 Amazon IoT Greengrass 核心软件的路径。通常,这是 /greengrass 目录。

    不要在核心上启动多个 OTA 更新代理实例,因为这可能会导致冲突。

  3. 使用Amazon IoT控制台或Amazon IoT Greengrass用于创建软件更新任务的 API。

     

    使用控制台
    1. 导航到 Amazon IoT 控制台。

    2. UNDERManage,展开远程操作,然后选择作业.

    3. 选择创建作业,选择创建 Greengrass V1 核心更新作业,然后选择下一步.

    4. 创建 Greengrass 更新页面上,定义更新作业的属性,然后选择创建。例如:

      • 选择要更新的设备中,选择要更新的核心。您可以选择单个核心事物以及包含核心的事物组。

      • 对于 S3 URL 签署人角色,请选择您的签署人角色

      • 适用于更新代理日志级别中,选择日志级别。

      • 适用于架构架构类型中,选择您的架构类型。

      • 适用于选择要更新的 Greengrass Core 组件,选择更新Amazon IoT GreengrassCore 软件核心软件或以更新 OTA 更新代理软件。

    5. 作业页面上,选择新作业以查看更新状态。

     

    使用 API
    1. 调用 CreateSoftwareUpdateJob API。在此示例过程中,我们使用 Amazon CLI 命令。

      以下命令创建一个作业,用于更新核心上的 Amazon IoT Greengrass Core 软件。替换示例值,然后运行命令。

      Linux or macOS terminal
      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
      Windows command prompt
      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

      此命令将返回以下响应。

      { "IotJobId": "GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE", "IotJobArn": "arn:aws:iot:region:123456789012:job/GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE", "PlatformSoftwareVersion": "1.10.1" }
    2. 从响应复制 IoTJobId

    3. CallDescribeJob中的Amazon IoT CoreAPI 以查看任务状态的 API。将示例值替换为您的作业 ID,然后运行命令。

      aws iot describe-job --job-id GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE

      该命令返回一个响应对象,其中包含有关作业的信息,包括 statusjobProcessDetails

      { "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用于更新Amazon IoT GreengrassCore 设备上的核心软件或 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

核心设备的架构。

有效值:armv7larmv6lx86_64aarch64

--update-targets

要更新的核心。该列表可以包含单个核心的 ARN 和其成员为核心的事物组的 ARN。有关事物组的更多信息,请参阅。静态事物组中的Amazon IoT开发人员指南.

--update-targets-operating-system

核心设备的操作系统。

有效值:ubuntuamazon_linuxraspbianopenwrt

--software-to-update

指定应该更新核心的软件还是 OTA 更新代理软件。

有效值:coreota_agent

--s3-url-signer-role

用于预签名 Amazon S3 URL(链接至Amazon IoT Greengrass软件更新构件。角色的附加权限策略必须允许s3:GetObject对目标中的存储桶的操作Amazon Web Services 区域。角色还必须允许 iot.amazonaws.com 代入角色作为可信实体。有关更多信息,请参阅 OTA 更新的 IAM 权限

--amzn-client-token

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

--update-agent-log-level

(可选)OTA 更新代理生成的日志记录级别。默认为 ERROR

有效值:NONETRACEDEBUGVERBOSEINFOWARNERRORFATAL

注意

CreateSoftwareUpdateJob 仅接受对以下受支持的架构和操作系统组合的请求:

  • ubuntu/x86_64

  • ubuntu/aarch64

  • amazon_linux/x86_64

  • raspbian/armv7l

  • raspbian/armv6l

  • openwrt/aarch64

  • openwrt/armv7l