Create bulk deployments for groups

You can use simple API calls to deploy large numbers of Greengrass groups at once. These deployments are triggered with an adaptive rate that has a fixed upper limit.

This tutorial describes how to use the AWS CLI to create and monitor a bulk group deployment in AWS IoT Greengrass. The bulk deployment example in this tutorial contains multiple groups. You can use the example in your implementation to add as many groups as you need.

The tutorial contains the following high-level steps:

Prerequisites

To complete this tutorial, you need:

Step 1: Create and upload the bulk deployment input file

In this step, you create a deployment input file and upload it to your Amazon S3 bucket. This file is a serialized, line-delimited JSON file that contains information about each group in your bulk deployment. AWS IoT Greengrass uses this information to deploy each group on your behalf when you initialize your bulk group deployment.

Step 2: Create and configure an IAM execution role

In this step, you use the IAM console to create a standalone execution role. You then establish a trust relationship between the role and AWS IoT Greengrass and ensure that your IAM user has PassRole privileges for your execution role. This allows AWS IoT Greengrass to assume your execution role and create the deployments on your behalf.

Step 3: Allow your execution role access to your S3 Bucket

To start your bulk deployment, your execution role must be able to read your bulk deployment input file from your Amazon S3 bucket. Attach the following example policy to your Amazon S3 bucket so its GetObject permissions are accessible to your execution role.

For more information, see How do I add an S3 bucket policy?

{
    "Version": "2008-10-17",
    "Id": "examplePolicy",
    "Statement": [
        {
            "Sid": "Stmt1535408982966",
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "executionRoleArn"
                ]
            },
            "Action": "s3:GetObject",
            "Resource":
            "arn:aws:s3:::my-bucket/objectKey"
        }
    ]
}      
    

You can use the following command in your terminal to check your bucket's policy:

aws s3api get-bucket-policy --bucket my-bucket

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::my-bucket/objectKey"
        }
    ]
}       
      

Step 4: Deploy the groups

In this step, you start a bulk deployment operation for all group versions configured in your bulk deployment input file. The deployment action for each of your group versions is of type NewDeploymentType.

Step 5: Test the deployment

Use the ListBulkDeployments command to find the ID of your bulk deployment.

aws greengrass list-bulk-deployments
    

This command returns a list of all of your bulk deployments from most to least recent, including your BulkDeploymentId.

{
  "BulkDeployments": [
    {
      "BulkDeploymentId": 1234567,
      "BulkDeploymentArn": "string",
      "CreatedAt": "string"
    }
  ],
  "NextToken": "string"
}
    

Now call the ListBulkDeploymentDetailedReports command to gather detailed information about each deployment.

aws greengrass list-bulk-deployment-detailed-reports --bulk-deployment-id 1234567 
    

The command should return a successful status code of 200 along with a JSON payload of information:

{ 
  "BulkDeploymentResults": [
    {
      "DeploymentId": "string",
      "GroupVersionedArn": "string",
      "CreatedAt": "string",
      "DeploymentStatus": "string",
      "ErrorMessage": "string",
      "ErrorDetails": [
        {
          "DetailedErrorCode": "string",
          "DetailedErrorMessage": "string"
        }
      ]
    }
  ],
  "NextToken": "string"
}
    

This payload usually contains a paginated list of each deployment and its deployment status from most to least recent. It also contains more information in the event of a bulk deployment execution failure. Again, the total number of deployments listed should be equal to the number of groups you identified in your bulk deployment input file.

The information returned can change until the deployments are in a terminal state (success or failure). You can call this command periodically until then.

Troubleshooting bulk deployments

If the bulk deployment is not successful, you can try the following troubleshooting steps. Run the commands in your terminal.

Troubleshoot input file errors

The bulk deployment can fail in the event of syntax errors in the bulk deployment input file. This returns a bulk deployment status of Failed with an error message indicating the line number of the first validation error. There are four possible errors:

Check for concurrent bulk deployments

You cannot start a new bulk deployment while another one is still running or in a non-terminal state. This can result in a Concurrent Deployment Error. You can use the ListBulkDeployments command to verify that a bulk deployment is not currently running. This command lists your bulk deployments from most to least recent.

{
  "BulkDeployments": [
    {
      "BulkDeploymentId": BulkDeploymentId,
      "BulkDeploymentArn": "string",
      "CreatedAt": "string"
    }
  ],
  "NextToken": "string"
}
            

Use the BulkDeploymentId of the first listed bulk deployment to run the GetBulkDeploymentStatus command. If your most recent bulk deployment is in a running state (Initializing or Running), use the following command to stop the bulk deployment.

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

This action results in a status of Stopping until the deployment is Stopped. After the deployment has reached a Stopped status, you can start a new bulk deployment.

Check ErrorDetails

Run the GetBulkDeploymentStatus command to return a JSON payload that contains information about any bulk deployment execution failure.

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

When exiting with an error, the ErrorDetails JSON payload that is returned by this call contains more information about the bulk deployment execution failure. An error status code in the 400 series, for example, indicates an input error, either in the input parameters or the caller dependencies.

Check the AWS IoT Greengrass core log

You can troubleshoot issues by viewing the AWS IoT Greengrass core logs. Use the following commands to view runtime.log:

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

For more information about AWS IoT Greengrass logging, see Monitoring with AWS IoT Greengrass logs.

See also

For more information, see the following resources: