Amazon IoT Greengrass Version 12023 年 6 月 30 日进入延长寿命阶段。有关更多信息,请参阅Amazon IoT Greengrass V1维护政策。在此日期之后,Amazon IoT Greengrass V1不会发布提供功能、增强功能、错误修复或安全补丁的更新。在上面运行的设备Amazon IoT Greengrass V1不会中断,将继续运行并连接到云端。我们强烈建议您迁移到 Amazon IoT Greengrass Version 2,这样可以添加重要的新功能并支持其他平台。
本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
为组创建批量部署
您可以使用简单 API 调用一次部署大量 Greengrass 组。这些部署通过具有固定上限的自适应速率触发。
本教程介绍如何使用 Amazon CLI 在 Amazon IoT Greengrass 中创建和监控批量组部署。本教程中的批量部署示例包含多个组。您可以在您的实施中使用该示例根据需要添加任意数量的组。
本教程包含以下概括步骤:
先决条件
要完成此教程,需要:
-
一个或多个可部署的 Greengrass 组。有关创建 Amazon IoT Greengrass 组和核心的更多信息,请参阅Amazon IoT Greengrass 入门。
-
在您的计算机上安装并配置 Amazon CLI。有关信息,请参阅 Amazon CLI 用户指南。
-
在中创建一个 S3 存储桶Amazon Web Services 区域如同Amazon IoT Greengrass. 想要了解有关信息,请参阅创建和配置 S3 存储桶中的Amazon Simple Storage In.
注意
目前,不支持启用了 SSE KMS 的存储桶。
第 1 步:创建并上传批量部署输入文件
在此步骤中,您将创建一个部署输入文件并将其上传到 Amazon S3 存储桶。此文件是一个行分隔的序列化 JSON 文件,包含有关批量部署中的每个组的信息。Amazon IoT Greengrass 在初始化批量组部署时使用此信息代表您部署每个组。
-
运行以下命令以获取要部署的每个组的
groupId
。在批量部署输入文件中输入groupId
,让 Amazon IoT Greengrass 可以识别要部署的每个组。注意
您还可以在中找到这些值Amazon IoT控制台。组 ID 显示在组的设置页面上。组版本 ID 显示在组的部署选项卡。
aws greengrass list-groups
该响应包含有关您 Amazon IoT Greengrass 账户中的每个组的信息:
{ "Groups": [ { "Name": "string", "Id": "
string
", "Arn": "string", "LastUpdatedTimestamp": "string", "CreationTimestamp": "string", "LatestVersion": "string", "LatestVersionArn": "string" } ], "NextToken": "string" }运行以下命令以获取要部署的每个组的
groupVersionId
。list-group-versions --group-id
groupId
该响应包含有关组中的所有版本的信息。记录下
Version
要使用的组版本的值。{ "Versions": [ { "Arn": "string", "Id": "string", "Version": "
string
", "CreationTimestamp": "string" } ], "NextToken": "string" } -
在您的计算机终端或所选的编辑器中,创建一个文件,
MyBulkDeploymentInputFile
,来自以下示例。此文件包含有关要包含在批量部署中的每个 Amazon IoT Greengrass 组的信息。虽然此示例定义多个组,但在本教程中,您的文件只能包含一个组。注意
此文件的大小必须小于 100 MB。
{"GroupId":"
groupId1
", "GroupVersionId":"groupVersionId1
", "DeploymentType":"NewDeployment"} {"GroupId":"groupId2
", "GroupVersionId":"groupVersionId2
", "DeploymentType":"NewDeployment"} {"GroupId":"groupId3
", "GroupVersionId":"groupVersionId3
", "DeploymentType":"NewDeployment"} ...每个记录(或行)包含一个组对象。每个组对象包含其相应
GroupId
、GroupVersionId
和DeploymentType
。目前,Amazon IoT Greengrass 仅支持NewDeployment
批量部署类型。保存并关闭该文件。记下该文件的位置。
-
在您的终端中使用以下命令将输入文件上传到 Amazon S3 存储桶。将文件路径替换为该文件的位置和名称。有关信息,请参阅将对象添加到存储桶。
aws s3 cp
path/MyBulkDeploymentInputFile
s3://my-bucket
/
第 2 步:创建并配置 IAM 执行角色
在此步骤中,您将使用 IAM 控制台创建一个独立的执行角色。然后,在该角色与之间建立信任关系Amazon IoT Greengrass并确保您的 IAM 用户具有PassRole
该执行角色的权限。这使 Amazon IoT Greengrass 可以担任该执行角色并代表您创建部署。
-
使用以下策略创建一个执行角色。此策略文档允许 Amazon IoT Greengrass 在代表您创建每个部署时访问批量部署输入文件。
有关创建 IAM 角色及委派权限的更多信息,请参阅创建 IAM 角色。
{ "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": "greengrass:CreateDeployment", "Resource": [ "arn:aws:greengrass:
region
:accountId
:/greengrass/groups/groupId1
", "arn:aws:greengrass:region
:accountId
:/greengrass/groups/groupId2
", "arn:aws:greengrass:region
:accountId
:/greengrass/groups/groupId3
", ... ] } ] }注意
此策略必须在批量部署输入文件中包含要由 Amazon IoT Greengrass 部署的每个组或组版本的资源。要允许访问所有组,请为
Resource
指定一个星号:"Resource": ["*"]
-
修改该执行角色的信任关系以包含 Amazon IoT Greengrass。这允许 Amazon IoT Greengrass 使用该执行角色及向其附加的权限。有关信息,请参阅编辑现有角色的信任关系。
我们还建议您包含
aws:SourceArn
和aws:SourceAccount
信任策略中的全局条件上下文密钥,以帮助防止混淆代理问题安全问题。条件上下文键将访问权限限制为仅允许来自指定账户和 Greengrass 工作区的那些请求。有关混淆代理人问题的更多信息,请参阅防止跨服务混淆代理.{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "greengrass.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "
account-id
" }, "ArnLike": { "aws:SourceArn": "arn:aws:greengrass:region
:account-id
:*" } } } ] } -
给 IAM
PassRole
将该执行角色的权限授予您的 IAM 用户。此 IAM 用户是用于启动批量部署的用户。PassRole
权限允许您的 IAM 用户将该执行角色传递给Amazon IoT Greengrass供使用。有关更多信息,请参阅向用户授予将角色传递给 Amazon 服务的权限。使用以下示例更新附加到您的执行角色的 IAM 策略。根据需要修改此示例。
{ "Version": "2012-10-17", "Statement": [ { "Sid": "Stmt1508193814000", "Effect": "Allow", "Action": [ "iam:PassRole" ], "Resource": [ "arn:aws:iam::
account-id
:user/executionRoleArn
" ] "Condition": { "StringEquals": { "iam:PassedToService": "greengrass.amazonaws.com" } } } ] }
第 3 步:允许您的执行角色访问您的 S3 存储桶
要启动批量部署,您的执行角色必须能够从 Amazon S3 存储桶读取批量部署输入文件。将以下示例策略附加到 Amazon S3 存储桶,这样就可以GetObject
权限可供您的执行角色访问。
有关更多信息,请参阅如何添加 S3 存储桶策略?
{ "Version": "2008-10-17", "Id": "examplePolicy", "Statement": [ { "Sid": "Stmt1535408982966", "Effect": "Allow", "Principal": { "AWS": [ "
executionRoleArn
" ] }, "Action": "s3:GetObject", "Resource": "arn:aws:s3:::my-bucket
/objectKey
" } ] }
您可以在终端中使用以下命令检查存储桶的策略:
aws s3api get-bucket-policy --bucket
my-bucket
注意
您可以直接修改您的执行角色,向该角色授予对您的 Amazon S3 存储桶的权限GetObject
权限。为此,请将以下示例策略附加到您的执行角色。
{ "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::
my-bucket
/objectKey
" } ] }
第 4 步:部署组
在此步骤中,您将对批量部署输入文件中配置的所有组版本启动一个批量部署操作。每个组版本的部署操作均为 NewDeploymentType
类型。
注意
当同一账户中的其他批量部署仍在运行时,您无法调用 StartBulkDeployment。请求被拒绝。
-
使用以下命令启动批量部署。
我们建议您在每个 StartBulkDeployment 请求中包含
X-Amzn-Client-Token
令牌。这些请求在令牌和请求参数方面是幂等的。此令牌可以是唯一的、区分大小写的且最多不超过 64 个 ASCII 字符的任意字符串。aws greengrass start-bulk-deployment --cli-input-json "{ "InputFileUri":"
URI of file in S3 bucket
", "ExecutionRoleArn":"ARN of execution role
", "AmznClientToken":"your Amazon client token
" }"该命令应生成成功状态代码
200
,以及以下响应:{ "bulkDeploymentId":
UUID
}记下批量部署 ID。它可用于检查批量部署的状态。
注意
虽然目前不支持批量部署操作,但您可以创建 Amazon EventBridge 事件规则以获取有关各个组部署状态更改的通知。有关更多信息,请参阅 获取部署通知。
-
使用以下命令检查批量部署的状态。
aws greengrass get-bulk-deployment-status --bulk-deployment-id
1234567
除了 JSON 信息负载之外,该命令还应返回一个成功状态代码
200
:{ "BulkDeploymentStatus":
Running
, "Statistics": { "RecordsProcessed":integer
, "InvalidInputRecords":integer
, "RetryAttempts":integer
}, "CreatedAt": "string", "ErrorMessage": "string", "ErrorDetails": [ { "DetailedErrorCode": "string", "DetailedErrorMessage": "string" } ] }BulkDeploymentStatus
包含批量执行的当前状态。该执行可具有六个不同的状态之一:-
Initializing
. 批量部署请求已收到,并且执行正在准备启动。 -
Running
. 批量部署执行已启动。 -
Completed
. 批量部署执行已完成所有记录的处理。 -
Stopping
. 批量部署执行已收到停止命令,并将很快终止。当之前的部署处于Stopping
状态时,您无法启动新的批量部署。 -
Stopped
. 批量部署执行已手动停止。 -
Failed
. 批量部署执行遇到了错误并终止。您可以在ErrorDetails
字段中找到错误详细信息。
JSON 负载还包含有关批量部署进度的统计信息。您可以使用此信息确定多少个组已处理以及多少个组已失败。统计信息包含:
-
RecordsProcessed
:已尝试的组记录的数量。 -
InvalidInputRecords
:返回了不可重试错误的记录总数。例如,如果输入文件中的组记录使用无效格式或指定不存在的组版本,或者执行未授予部署组或组版本的权限,则可能会发生此错误。 -
RetryAttempts
:返回了可重试错误的部署尝试次数。例如,如果部署组的尝试返回一个限流错误,则将触发重试。一个组部署最多可重试五次。
如果批量部署执行失败,则此负载还包含一个
ErrorDetails
节,可用于排查问题。该节包含有关执行失败原因的信息。您可以定期检查批量部署的状态,以确认它正在正常进行处理。在部署完成后,
RecordsProcessed
应等于批量部署输入文件中的部署组的数量。这表示每个记录均已得到处理。 -
第 5 步:测试部署
使用 ListBulkDeployments 命令找到批量部署的 ID。
aws greengrass list-bulk-deployments
此命令会返回所有批量部署的列表(从新到旧),包括 BulkDeploymentId
。
{ "BulkDeployments": [ { "BulkDeploymentId":
1234567
, "BulkDeploymentArn": "string", "CreatedAt": "string" } ], "NextToken": "string" }
现在,调用 ListBulkDeploymentDetailedReports 命令以收集有关每个部署的详细信息。
aws greengrass list-bulk-deployment-detailed-reports --bulk-deployment-id
1234567
该命令应返回一个成功状态代码 200
以及 JSON 信息负载:
{ "BulkDeploymentResults": [ { "DeploymentId": "string", "GroupVersionedArn": "string", "CreatedAt": "string", "DeploymentStatus": "string", "ErrorMessage": "string", "ErrorDetails": [ { "DetailedErrorCode": "string", "DetailedErrorMessage": "string" } ] } ], "NextToken": "string" }
此负载通常包含每个部署及其部署状态的分页列表(从新到旧)。此外,还包含批量部署执行失败时的更多信息。同样,列出的部署总数应等于批量部署输入文件中标识的组的数量。
返回的信息可能会有所有变化,直到部署处于最终状态(成功或失败)。您可以在此之前定期调用此命令。
批量部署问题排查
如果批量部署未成功,您可以尝试以下问题排查步骤。在您的终端中运行命令。
排查输入文件错误
如果批量部署输入文件中存在语法错误,则批量部署可能会失败。这会返回批量部署状态 Failed
,并显示一条错误消息,指出第一个验证错误的行号。有四个可能的错误:
-
InvalidInputFile: Missing
GroupId
at line number:line number
此错误指出给定输入文件行无法注册指定的参数。可能缺少参数的是
GroupId
和GroupVersionId
。 -
InvalidInputFile: Invalid deployment type at line number :
line number
. Only valid type is 'NewDeployment'.此错误指出给定输入文件行列出了无效的部署类型。此时,唯一受支持的部署类型为
NewDeployment
。 -
Line
%s
is too long in S3 File. Valid line is less than 256 chars.此错误指出给定输入文件行过长,必须缩短。
-
Failed to parse input file at line number:
line number
此错误指出给定输入文件行被视为无效 json。
检查是否存在并发批量部署
当其他部署仍在运行或处于非最终状态时,您无法启动新的批量部署。这可能会导致 Concurrent Deployment Error
。您可以使用 ListBulkDeployments 命令来验证批量部署当前是否正在运行。此命令列出您的批量部署(从新到旧)。
{ "BulkDeployments": [ { "BulkDeploymentId":
BulkDeploymentId
, "BulkDeploymentArn": "string", "CreatedAt": "string" } ], "NextToken": "string" }
使用第一个列出的批量部署的 BulkDeploymentId
运行 GetBulkDeploymentStatus 命令。如果最新批量部署处于正在运行状态(Initializing
或 Running
),请使用以下命令停止批量部署。
aws greengrass stop-bulk-deployment --bulk-deployment-id
BulkDeploymentId
此操作会生成 Stopping
状态,直到该部署的状态变为 Stopped
。在该部署达到 Stopped
状态后,您便可启动一个新的批量部署。
Check ErrorDetails
运行 GetBulkDeploymentStatus
命令以返回一个 JSON 负载,其中包含关于所有批量部署执行失败的详细信息。
"Message": "string", "ErrorDetails": [ { "DetailedErrorCode": "string", "DetailedErrorMessage": "string" } ]
如果退出时出现错误,则此调用返回的 ErrorDetails
JSON 负载包含有关批量部署执行失败的更多信息。例如,400
系列中的错误状态代码指示输入参数或调用方依赖项中的输入错误。
检查 Amazon IoT Greengrass 核心日志
您可以通过查看 Amazon IoT Greengrass 核心日志来排查问题:使用以下命令查看 runtime.log
:
cd /greengrass/ggc/var/log sudo cat system/runtime.log | more
有关 Amazon IoT Greengrass 日志记录的更多信息,请参阅 利用 Amazon IoT Greengrass 日志进行监控。
另请参阅
有关更多信息,请参阅以下 资源:
-
Amazon S3 API 命令中的Amazon CLI命令参考
-
Amazon IoT Greengrass命令中的Amazon CLI命令参考