AWS IoT Greengrass Version 1 於 2023 年 6 月 30 日進入延長使用壽命階段。如需詳細資訊,請參閱AWS IoT Greengrass V1 維護政策。在此日期之後, AWS IoT Greengrass V1 將不會發行提供功能、增強功能、錯誤修正或安全性修補程式的更新。在上運行的設備 AWS IoT Greengrass V1 不會中斷,並將繼續運行並連接到雲。我們強烈建議您移轉至 AWS IoT Greengrass Version 2,這會增加重要的新功能,並支援其他平台。
本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
建立群組的大量部署
您可以使用簡單的 API 呼叫,一次部署大量 Greengrass 群組。這些部署由固定上限的自適性速率所觸發。
本教學課程描述如何使用 AWS CLI 在 AWS IoT Greengrass 中建立和監控大量群組部署。本教學課程中的大量部署範例包含多個群組。您可以在實作中使用此範例來新增所需的群組數量。
本教學課程所述以下高階執行步驟:
先決條件
為完成此教學課程您需要:
-
一或多個可部署的 Greengrass 群組。如需建立 AWS IoT Greengrass 群組和核心的詳細資訊,請參閱 開始使用 AWS IoT Greengrass。
-
在您的機器上安裝和設定的 AWS CLI。如需更多詳細資訊,請參閱 AWS CLI 使用者指南相關文章。
-
在同一儲存貯體中建立的 S3 儲存貯體AWS 區域如AWS IoT Greengrass。如需相關資訊,請參閱「」。建立與設定 S3 儲存貯體中的Amazon Simple Simple Service 使用指南。
注意
目前,不支援已啟用 SSE KMS 的儲存貯體。
步驟 1:建立和上傳大量部署輸入檔
在此步驟中,您將建立部署輸入檔並將其上傳到 Amazon S3 儲存貯體。這個檔案是序列化、以列分隔的 JSON 檔案,其中包含大量部署中每個群組的相關資訊。當您初始化大量群組部署時,AWS IoT Greengrass 會使用此資訊來替您部署每個群組。
-
執行以下命令為您要部署的每個群組取得
groupId
。您需要將groupId
輸入大量部署輸入檔中,讓 AWS IoT Greengrass 可以識別每個要部署的群組。注意
您也可以在中找到這些值AWS IoT主控台。群組 ID 會顯示在群組的 Settings (設定) 頁面上。群組版本 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
回應包含群組中所有版本的相關資訊。記下
Version
要使用之群組版本的值。{ "Versions": [ { "Arn": "string", "Id": "string", "Version": "
string
", "CreationTimestamp": "string" } ], "NextToken": "string" } -
在您的電腦終端機或您選擇的編輯器中,建立檔案,
MyBulkDeploymentInputFile
,從下面的例子。這個檔案包含要納入大量部署中的每個 AWS 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
。目前,AWS IoT Greengrass 僅支援NewDeployment
大量部署類型。儲存並關閉檔案。請記下檔案的位置。
-
在終端機中使用下列命令,將輸入檔上傳到 Amazon S3 儲存貯體。以您的檔案位置與名稱取代檔案路徑。如需相關資訊,請參閱將物件新增至儲存貯體。
aws s3 cp
path/MyBulkDeploymentInputFile
s3://my-bucket
/
步驟 2:建立和設定 IAM 執行角色
在此步驟中,您將使用 IAM 主控台來建立獨立執行角色。然後,您會建立角色和之間的信任關係AWS IoT Greengrass並確保您的 IAM 使用者具有PassRole
執行角色的權限。這可讓 AWS IoT Greengrass 擔任您的執行角色,並替您建立部署。
-
使用下列政策來建立執行角色。此政策文件允許 AWS 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
", ... ] } ] }注意
對於大量部署輸入檔中要由 AWS IoT Greengrass 部署的每個群組或群組版本,此政策必須具有資源。若要允許存取所有群組,請為
Resource
指定星號:"Resource": ["*"]
-
將執行角色的信任關係修改為包含 AWS IoT Greengrass。這可讓 AWS 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
:*" } } } ] } -
給予身份管理
PassRole
IAM 使用者執行角色的許可。這個 IAM 使用者會用來啟動大量部署。PassRole
許可讓您的 IAM 使用者將執行角色傳給AWS IoT Greengrass供使用。如需詳細資訊,請參閱授予使用者將角色傳遞至 AWS 服務。使用以下範例,更新連接到執行角色的 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 S3 操作 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
除了 JSON 承載資訊,此命令還應該會傳回成功狀態碼 200
:
{ "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
系列中的錯誤狀態碼表示輸入參數或呼叫者相依性中的輸入錯誤。
檢查 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 日誌進行監控。
另請參閱
如需詳細資訊,請參閱下列資源:
-
Amazon S3 API 命令中的AWS CLI命令參考
-
AWS IoT Greengrass命令中的AWS CLI命令參考