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

为组创建批量部署

您可以使用简单 API 调用一次部署大量 Greengrass 组。这些部署通过具有固定上限的自适应速率触发。

本教程介绍如何使用 AWS CLI 在 AWS IoT Greengrass 中创建和监控批量组部署。本教程中的批量部署示例包含多个组。您可以在您的实施中使用该示例根据需要添加任意数量的组。

本教程包含以下概括步骤:

先决条件

要完成此教程,需要:

  • 一个或多个可部署的 Greengrass 组。有关创建 AWS IoT Greengrass 组和核心的更多信息,请参阅AWS IoT Greengrass 入门

  • 在您的计算机上安装并配置 AWS CLI。有关信息,请参阅 AWS CLI 用户指南

  • 在 AWS IoT Greengrass 所在的同一区域中创建一个 S3 存储桶。有关信息,请参阅创建和配置 S3 存储桶

    注意

    目前,不支持启用了 SSE KMS 的存储桶。

步骤 1:创建并上传批量部署输入文件

在此步骤中,您将创建一个部署输入文件并将其上传到您的 Amazon S3 存储桶。此文件是一个行分隔的序列化 JSON 文件,包含有关批量部署中的每个组的信息。AWS IoT Greengrass 在初始化批量组部署时使用此信息代表您部署每个组。

  1. 运行以下命令以获取要部署的每个组的 groupId。在批量部署输入文件中输入 groupId,让 AWS IoT Greengrass 可以识别要部署的每个组。

    注意

    在 AWS IoT 控制台 中,您还可以在组的设置页面上找到组 ID,并在部署页面上找到组版本 ID。

    aws greengrass list-groups

    该响应包含有关您 AWS 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

    该响应包含有关组中的所有版本的信息。记下要使用的组版本的 ID。

    { "Versions": [ { "Arn": "string", "Id": "string", "Version": "string", "CreationTimestamp": "string" } ], "NextToken": "string" }
  2. 在您的计算机终端或所选的编辑器中,从以下示例创建一个文件 MyBulkDeploymentInputFile。此文件包含有关要包含在批量部署中的每个 AWS IoT Greengrass 组的信息。虽然此示例定义多个组,但在本教程中,您的文件只能包含一个组。

    注意

    此文件的大小必须小于 100 MB。

    {"GroupId":"groupId1", "GroupVersionId":"groupVersionId1", "DeploymentType":"NewDeployment"} {"GroupId":"groupId2", "GroupVersionId":"groupVersionId2", "DeploymentType":"NewDeployment"} {"GroupId":"groupId3", "GroupVersionId":"groupVersionId3", "DeploymentType":"NewDeployment"} ...

    每个记录(或行)包含一个组对象。每个组对象包含其相应 groupIdgroupVersionIdDeploymentType。目前,AWS IoT Greengrass 仅支持 NewDeployment 批量部署类型。

    保存并关闭该文件。记下该文件的位置。

  3. 在您的终端中使用以下命令将输入文件上传到 Amazon S3 存储桶。将文件路径替换为该文件的位置和名称。有关信息,请参阅将对象添加到存储桶

    aws s3 cp path/MyBulkDeploymentInputFile s3://my-bucket/

步骤 2:创建并配置 IAM 执行角色

在此步骤中,您将使用 IAM 控制台创建一个独立的执行角色。然后,在该角色与 AWS IoT Greengrass 之间建立信任关系,并确保您的 IAM 用户对该执行角色具有 PassRole 权限。这使 AWS IoT Greengrass 可以担任该执行角色并代表您创建部署。

  1. 使用以下策略创建一个执行角色。此策略文档允许 AWS IoT Greengrass 在代表您创建每个部署时访问批量部署输入文件。

    有关创建 IAM 角色及委派权限的更多信息,请参阅创建 IAM 角色

    { "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": "greengrass:CreateDeployment", "Resource": [ "arn:aws-cn:greengrass:region:accountId:/greengrass/groups/groupId1", "arn:aws-cn:greengrass:region:accountId:/greengrass/groups/groupId2", "arn:aws-cn:greengrass:region:accountId:/greengrass/groups/groupId3", ... ] } ] }

    注意

    此策略必须在批量部署输入文件中包含要由 AWS IoT Greengrass 部署的每个组或组版本的资源。要允许访问所有组,请为资源指定一个星号:

    "Resource": ["*"]
  2. 修改该执行角色的信任关系以包含 AWS IoT Greengrass。这允许 AWS IoT Greengrass 使用该执行角色及向其附加的权限。有关信息,请参阅编辑现有角色的信任关系

    { "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "greengrass.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
  3. 将该执行角色的 IAM PassRole 权限授予您的 IAM 用户。此 IAM 用户是用于启动批量部署的用户。PassRole 权限允许您的 IAM 用户将该执行角色传递给 AWS IoT Greengrass 以供使用。有关更多信息,请参阅向用户授予权限以将角色传递给 AWS 服务

    使用以下示例更新您的信任策略文档。根据需要修改此示例。

    { "Version": "2012-10-17", "Statement": [ { "Sid": "Stmt1508193814000", "Effect": "Allow", "Action": [ "iam:PassRole" ], "Resource": [ "arn:aws-cn:iam::123456789012:user/executionRoleArn" ] } ] }

步骤 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-cn: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-cn:s3:::my-bucket/objectKey" } ] }

步骤 4:部署组

在此步骤中,您将对批量部署输入文件中配置的所有组版本启动一个批量部署操作。每个组版本的部署操作均为 NewDeploymentType 类型。

注意

当同一账户中的其他批量部署仍在运行时,您无法调用 StartBulkDeployment。请求被拒绝。

  1. 使用以下命令启动批量部署。

    我们建议您在每个 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。它可用于检查批量部署的状态。

  2. 使用以下命令检查批量部署的状态。

    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

    此错误指出给定输入文件行无法注册指定的参数。可能缺少参数的是 GroupIdGroupVersionId

  • 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 命令。如果最新批量部署处于正在运行状态(InitializingRunning),请使用以下命令停止批量部署。

aws greengrass stop-bulk-deployment --bulk-deployment-id BulkDeploymentId

此操作会生成 Stopping 状态,直到该部署的状态变为 Stopped。在该部署达到 Stopped 状态后,您便可启动一个新的批量部署。

检查 ErrorDetails

运行 GetBulkDeploymentStatus 命令以返回一个 JSON 负载,其中包含有关任何批量部署执行失败的详细信息。

"Message": "string", "ErrorDetails": [ { "DetailedErrorCode": "string", "DetailedErrorMessage": "string" } ]

如果退出时出现错误,则此调用返回的 ErrorDetails JSON 负载包含有关批量部署执行失败的更多信息。例如,400 系列中的错误状态代码指示输入参数或调用方依赖项中的输入错误。

检查 AWS IoT Greengrass 核心日志

您可以通过查看 AWS IoT Greengrass 核心日志来排查问题:使用以下命令查看 runtime.log

cd /greengrass/ggc/var/log sudo cat system/runtime.log | more

有关 AWS IoT Greengrass 日志记录的更多信息,请参阅 利用 AWS IoT Greengrass 日志进行监控

其他资源

有关详细信息,请参阅以下资源: