Create bulk deployments for groups

Run the following command to get the groupId for each group you want to deploy. You enter the groupId into your bulk deployment input file so that Amazon IoT Greengrass can identify each group to be deployed.

aws greengrass list-groups
        

The response contains information about each group in your Amazon IoT Greengrass account:

{
  "Groups": [
    {
      "Name": "string",
      "Id": "string",
      "Arn": "string",
      "LastUpdatedTimestamp": "string",
      "CreationTimestamp": "string",
      "LatestVersion": "string",
      "LatestVersionArn": "string"
    }
  ],
  "NextToken": "string"
}          
        

Run the following command to get the groupVersionId of each group you want to deploy.

list-group-versions --group-id groupId
        

The response contains information about all of the versions in the group. Make a note of the Version value for the group version you want to use.

{
  "Versions": [
    {
      "Arn": "string",
      "Id": "string",
      "Version": "string",
      "CreationTimestamp": "string"
    }
  ],
  "NextToken": "string"
}
        

In your computer terminal or editor of choice, create a file, MyBulkDeploymentInputFile, from the following example. This file contains information about each Amazon IoT Greengrass group to be included in a bulk deployment. Although this example defines multiple groups, for this tutorial, your file can contain just one.

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

Each record (or line) contains a group object. Each group object contains its corresponding GroupId and GroupVersionId and a DeploymentType. Currently, Amazon IoT Greengrass supports NewDeployment bulk deployment types only.

Save and close your file. Make a note of the location of the file.

Use the following command in your terminal to upload your input file to your Amazon S3 bucket. Replace the file path with the location and name of your file. For information, see Add an object to a bucket.

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

Use the following policy to create an execution role. This policy document allows Amazon IoT Greengrass to access your bulk deployment input file when it creates each deployment on your behalf.

For more information about creating an IAM role and delegating permissions, see Creating IAM roles.

 {
    "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",
                ...
            ]
        }
    ]
}
        

"Resource": ["*"]

Modify the trust relationship for your execution role to include Amazon IoT Greengrass. This allows Amazon IoT Greengrass to use your execution role and the permissions attached to it. For information, see Editing the trust relationship for an existing role.

We recommend that you also include the aws:SourceArn and aws:SourceAccount global condition context keys in your trust policy to help prevent the confused deputy security problem. The condition context keys restrict access to allow only those requests that come from the specified account and Greengrass workspace. For more information about the confused deputy problem, see Cross-service confused deputy prevention.

{
  "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-cn:greengrass:region:account-id:*"
        }
      }
    }
  ]
}

Give IAM PassRole permissions for your execution role to your IAM user. This IAM user is the one used to initiate the bulk deployment. PassRole permissions allow your IAM user to pass your execution role to Amazon IoT Greengrass for use. For more information, see Granting a user permissions to pass a role to an Amazon service.

Use the following example to update the IAM policy attached to your execution role. Modify this example, as necessary.

 {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Stmt1508193814000",
            "Effect": "Allow",
            "Action": [
                "iam:PassRole"
            ],
            "Resource": [
                "arn:aws-cn:iam::account-id:user/executionRoleArn"
            ]
            "Condition": {
                "StringEquals": {
                    "iam:PassedToService": "greengrass.amazonaws.com"
                }
            }
        }
    ]
}
        

Use the following command to start the bulk deployment.

We recommend that you include an X-Amzn-Client-Token token in every StartBulkDeployment request. These requests are idempotent with respect to the token and the request parameters. This token can be any unique, case-sensitive string of up to 64 ASCII characters.

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"
          }"
        

The command should result in a successful status code of 200, along with the following response:

{
  "bulkDeploymentId": UUID
}
        

Make a note of the bulk deployment ID. It can be used to check the status of your bulk deployment.

Use the following command to check the status of your bulk deployment.

aws greengrass get-bulk-deployment-status --bulk-deployment-id 1234567

The command should return a successful status code of 200 in addition to a JSON payload of information:

 {
  "BulkDeploymentStatus": Running,
  "Statistics": {
     "RecordsProcessed": integer,
     "InvalidInputRecords": integer,
     "RetryAttempts": integer
  },
  "CreatedAt": "string",
  "ErrorMessage": "string",
  "ErrorDetails": [
    {
      "DetailedErrorCode": "string",
      "DetailedErrorMessage": "string"
    }
  ]
}
        

BulkDeploymentStatus contains the current status of the bulk execution. The execution can have one of six different statuses:

The JSON payload also includes statistical information about the progress of the bulk deployment. You can use this information to determine how many groups have been processed and how many have failed. The statistical information includes:

In the case of a bulk deployment execution failure, this payload also includes an ErrorDetails section that can be used for troubleshooting. It contains information about the cause of the execution failure.

You can periodically check the status of the bulk deployment to confirm that it is progressing as expected. After the deployment is complete, RecordsProcessed should be equal to the number of deployment groups in your bulk deployment input file. This indicates that each record has been processed.