End of support notice: On October 7th, 2026, AWS will discontinue support for AWS IoT Greengrass Version 1. After October 7th, 2026, you will no longer be able to access the AWS IoT Greengrass V1 resources. For more information, please visit [Migrate from AWS IoT Greengrass Version 1](https://docs.aws.amazon.com/greengrass/v2/developerguide/migrate-from-v1.html).
# Deploy AWS IoT Greengrass groups to an AWS IoT Greengrass core
Use AWS IoT Greengrass groups to organize entities in your edge environment. You also use groups to control how the entities in the group interact with each other and with the AWS Cloud. For example, only the Lambda functions in the group are deployed for running locally, and only the devices in the group can communicate using the local MQTT server.
A group must include a [core](gg-core.md), which is an AWS IoT device that runs the AWS IoT Greengrass Core software. The core acts as an edge gateway and provides AWS IoT Core capabilities in the edge environment. Depending on your business need, you can also add the following entities to a group:
+ **Client devices**. Represented as things in the AWS IoT registry. These devices must run [FreeRTOS](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-lib-gg-connectivity.html) or use the [AWS IoT Device SDK](what-is-gg.md#iot-device-sdk) or [AWS IoT Greengrass Discovery API](gg-discover-api.md) to get connection information for the core. Only client devices that are members of the group can connect to the core.
+ **Lambda functions**. User-defined serverless applications that run code on the core. Lambda functions are authored in AWS Lambda and referenced from a Greengrass group. For more information, see [Run Lambda functions on the AWS IoT Greengrass core](lambda-functions.md).
+ **Connectors**. Predefined serverless applications that run code on the core. Connectors can provide built-in integration with local infrastructure, device protocols, AWS, and other cloud services. For more information, see [Integrate with services and protocols using Greengrass connectors](connectors.md).
+ **Subscriptions**. Defines the publishers, subscribers, and MQTT topics (or subjects) that are authorized for MQTT communication.
+ **Resources**. References to local [devices and volumes](access-local-resources.md), [machine learning models](ml-inference.md), and [secrets](secrets.md), used for access control by Greengrass Lambda functions and connectors.
+ **Logs**. Logging configurations for AWS IoT Greengrass system components and Lambda functions. For more information, see [Monitoring with AWS IoT Greengrass logs](greengrass-logs-overview.md).
You manage your Greengrass group in the AWS Cloud and then deploy it to a core. The deployment copies the group configuration to the `group.json` file on the core device. This file is located in `greengrass-root/ggc/deployments/group`.
![\[Cloud definition of Greengrass group deployed to a core device.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/group-deploy.png)
**Note**
During a deployment, the Greengrass daemon process on the core device stops and then restarts.
## Deploying groups from the AWS IoT console
You can deploy a group and manage its deployments from the group's configuration page in the AWS IoT console.
**Note**
To open this page in the console, choose **Greengrass devices **, then **Groups (V1)**, and then under **Greengrass groups**, choose your group.
**To deploy the current version of the group**
+ From the group configuration page, choose **Deploy**.
**To view the deployment history of the group**
A group's deployment history includes the date and time, group version, and status of each deployment attempt.
1. From the group configuration page, choose the **Deployments** tab.
1. To see more information about a deployment, including error messages, choose **Deployments** from the AWS IoT console, under **Greengrass devices**.
**To redeploy a group deployment**
You might want to redeploy a deployment if the current deployment fails or revert to a different group version.
1. From the AWS IoT console, choose **Greengrass devices**, and then choose **Groups (V1)**.
1. Choose the **Deployments** tab.
1. Choose the deployment you want to redeploy and choose **Redeploy**.
**To reset group deployments**
You might want to reset group deployments to move or delete a group or to remove deployment information. For more information, see [Reset deployments](reset-deployments-scenario.md).
1. From the AWS IoT console, choose **Greengrass devices**, and then choose **Groups (V1)**.
1. Choose the **Deployments** tab.
1. Choose the deployment you want to reset and choose **Reset deployments**.
## Deploying groups with the AWS IoT Greengrass API
The AWS IoT Greengrass API provides the following actions to deploy AWS IoT Greengrass groups and manage group deployments. You can call these actions from the AWS CLI, AWS IoT Greengrass API, or AWS SDK.
| Action | Description |
| --- | --- |
| [CreateDeployment](https://docs.aws.amazon.com/greengrass/v1/apireference/createdeployment-post.html) | Creates a `NewDeployment` or `Redeployment` deployment. You might want to redeploy a deployment if the current deployment fails. Or you might want to redeploy to revert to a different group version. |
| [GetDeploymentStatus](https://docs.aws.amazon.com/greengrass/v1/apireference/getdeploymentstatus-get.html) | Returns the status of a deployment: `Building`, `InProgress`, `Success`, or `Failure`. You can configure Amazon EventBridge events to receive deployment notifications. For more information, see [Get deployment notifications](deployment-notifications.md). |
| [ListDeployments](https://docs.aws.amazon.com/greengrass/v1/apireference/listdeployments-get.html) | Returns the deployment history for the group. |
| [ResetDeployments](https://docs.aws.amazon.com/greengrass/v1/apireference/resetdeployments-post.html) | Resets the deployments for the group. You might want to reset group deployments to move or delete a group or to remove deployment information. For more information, see [Reset deployments](reset-deployments-scenario.md). |
**Note**
For information about bulk deployment operations, see [Create bulk deployments for groups](bulk-deploy-cli.md).
### Getting the group ID
The group ID is commonly used in API actions. You can use the [ListGroups](https://docs.aws.amazon.com/greengrass/v1/apireference/listgroups-get.html) action to find the ID of the target group from your list of groups. For example, in the AWS CLI, use the `list-groups` command.
```
aws greengrass list-groups
```
You can also include the `query` option to filter results. For example:
+ To get the most recently created group:
```
aws greengrass list-groups --query "reverse(sort_by(Groups, &CreationTimestamp))[0]"
```
+ To get a group by name:
```
aws greengrass list-groups --query "Groups[?Name=='MyGroup']"
```
Group names are not required to be unique, so multiple groups might be returned.
The following is an example `list-groups` response. The information for each group includes the ID of the group (in the `Id` property) and the ID of the most recent group version (in the `LatestVersion` property). To get other version IDs for a group, use the group ID with [ListGroupVersions](https://docs.aws.amazon.com/greengrass/v1/apireference/listgroupversions-get.html).
**Note**
You can also find these values in the AWS IoT console. The group ID is displayed on the group's **Settings** page. Group version IDs are displayed on the group's **Deployments** tab.
```
{
"Groups": [
{
"LatestVersionArn": "arn:aws:us-west-2:123456789012:/greengrass/groups/00dedaaa-ac16-484d-ad77-c3eedEXAMPLE/versions/4cbc3f07-fc5e-48c4-a50e-7d356EXAMPLE",
"Name": "MyFirstGroup",
"LastUpdatedTimestamp": "2019-11-11T05:47:31.435Z",
"LatestVersion": "4cbc3f07-fc5e-48c4-a50e-7d356EXAMPLE",
"CreationTimestamp": "2019-11-11T05:47:31.435Z",
"Id": "00dedaaa-ac16-484d-ad77-c3eedEXAMPLE",
"Arn": "arn:aws:us-west-2:123456789012:/greengrass/groups/00dedaaa-ac16-484d-ad77-c3eedEXAMPLE"
},
{
"LatestVersionArn": "arn:aws:us-west-2:123456789012:/greengrass/groups/036ceaf9-9319-4716-ba2a-237f9EXAMPLE/versions/8fe9e8ec-64d1-4647-b0b0-01dc8EXAMPLE",
"Name": "GreenhouseSensors",
"LastUpdatedTimestamp": "2020-01-07T19:58:36.774Z",
"LatestVersion": "8fe9e8ec-64d1-4647-b0b0-01dc8EXAMPLE",
"CreationTimestamp": "2020-01-07T19:58:36.774Z",
"Id": "036ceaf9-9319-4716-ba2a-237f9EXAMPLE",
"Arn": "arn:aws:us-west-2:123456789012:/greengrass/groups/036ceaf9-9319-4716-ba2a-237f9EXAMPLE"
},
...
]
}
```
If you don't specify an AWS Region, AWS CLI commands use the default Region from your profile. To return groups in a different Region, include the *region* option. For example:
```
aws greengrass list-groups --region us-east-1
```
## Overview of the AWS IoT Greengrass group object model
When programming with the AWS IoT Greengrass API, it's helpful to understand the Greengrass group object model.
### Groups
In the AWS IoT Greengrass API, the top-level `Group` object consists of metadata and a list of `GroupVersion` objects. `GroupVersion` objects are associated with a `Group` by ID.
![\[A diagram of a group, which consists of metadata and a list of group versions.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/om-group.png)
### Group versions
`GroupVersion` objects define group membership. Each `GroupVersion` references a `CoreDefinitionVersion` and other component versions by ARN. These references determine which entities to include in the group.
![\[A diagram of a group version that references other version types by ARN.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/om-groupversion.png)
For example, to include three Lambda functions, one device, and two subscriptions in the group, the `GroupVersion` references:
+ The `CoreDefinitionVersion` that contains the required core.
+ The `FunctionDefinitionVersion` that contains the three functions.
+ The `DeviceDefinitionVersion` that contains the client device.
+ The `SubscriptionDefinitionVersion` that contains the two subscriptions.
The `GroupVersion` deployed to a core device determines the entities that are available in the local environment and how they can interact.
### Group components
Components that you add to groups have a three-level hierarchy:
+ A *Definition* that references a list of *DefinitionVersion* objects of a given type. For example, a `DeviceDefinition` references a list of `DeviceDefinitionVersion` objects.
+ A *DefinitionVersion* that contains a set of entities of a given type. For example, a `DeviceDefinitionVersion` contains a list of `Device` objects.
+ Individual entities that define their properties and behavior. For example, a `Device` defines the ARN of the corresponding client device in the AWS IoT registry, the ARN of its device certificate, and whether its local shadow syncs automatically with the cloud.
You can add the following types of entities to a group:
+ [Connector](https://docs.aws.amazon.com/greengrass/v1/apireference/definitions-connector.html)
+ [Core](https://docs.aws.amazon.com/greengrass/v1/apireference/definitions-core.html)
+ [Device](https://docs.aws.amazon.com/greengrass/v1/apireference/definitions-device.html)
+ [Function](https://docs.aws.amazon.com/greengrass/v1/apireference/definitions-function.html)
+ [Logger](https://docs.aws.amazon.com/greengrass/v1/apireference/definitions-logger.html)
+ [Resource](https://docs.aws.amazon.com/greengrass/v1/apireference/definitions-resource.html)
+ [Subscription](https://docs.aws.amazon.com/greengrass/v1/apireference/definitions-subscription.html)
The following example `DeviceDefinition` references three `DeviceDefinitionVersion` objects that each contain multiple `Device` objects. Only one `DeviceDefinitionVersion` at a time is used in a group.
![\[A diagram of a device hierarchy, which consists of DeviceDefinition, DeviceDefinitionVersion, and Device objects.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/om-devicedefinition.png)
### Updating groups
In the AWS IoT Greengrass API, you use versions to update a group's configuration. Versions are immutable, so to add, remove, or change group components, you must create *DefinitionVersion* objects that contain new or updated entities.
You can associate new *DefinitionVersions* objects with new or existing *Definition* objects. For example, you can use the `CreateFunctionDefinition` action to create a `FunctionDefinition` that includes the `FunctionDefinitionVersion` as an initial version, or you can use the `CreateFunctionDefinitionVersion` action and reference an existing `FunctionDefinition`.
After you create your group components, you create a `GroupVersion` that contains all *DefinitionVersion* objects that you want to include in the group. Then, you deploy the `GroupVersion`.
To deploy a `GroupVersion`, it must reference a `CoreDefinitionVersion` that contains exactly one `Core`. All referenced entities must be members of the group. Also, a [Greengrass service role](service-role.md) must be associated with your AWS account in the AWS Region where you are deploying the `GroupVersion`.
**Note**
The `Update` actions in the API are used to change the name of a `Group` or component *Definition* object.
**Updating entities that reference AWS resources**
Greengrass Lambda functions and [secret resources](secrets.md) define Greengrass-specific properties and also reference corresponding AWS resources. To update these entities, you might make changes to the corresponding AWS resource instead of your Greengrass objects. For example, Lambda functions reference a function in AWS Lambda and also define lifecycle and other properties that are specific to the Greengrass group.
+ To update Lambda function code or packaged dependencies, make your changes in AWS Lambda. During the next group deployment, these changes are retrieved from AWS Lambda and copied to your local environment.
+ To update [Greengrass-specific properties](lambda-group-config.md), you create a `FunctionDefinitionVersion` that contains the updated `Function` properties.
**Note**
Greengrass Lambda functions can reference a Lambda function by alias ARN or version ARN. If you reference the alias ARN (recommended), you don't need to update your `FunctionDefinitionVersion` (or `SubscriptionDefinitionVersion`) when you publish a new function version in AWS Lambda. For more information, see [Reference Lambda functions by alias or version](lambda-functions.md#lambda-versions-aliases).
## See also
+ [Get deployment notifications](deployment-notifications.md)
+ [Reset deployments](reset-deployments-scenario.md)
+ [Create bulk deployments for groups](bulk-deploy-cli.md)
+ [Troubleshooting Deployment Issues](gg-troubleshooting.md#gg-troubleshooting-deploymentissues)
+ [AWS IoT Greengrass Version 1 API Reference](https://docs.aws.amazon.com/greengrass/v1/apireference/)
+ [AWS IoT Greengrass commands](https://docs.aws.amazon.com/cli/latest/reference/greengrass/index.html) in the *AWS CLI Command Reference*
# Get deployment notifications
Amazon EventBridge event rules provide you with notifications about state changes for your Greengrass group deployments. EventBridge delivers a near real-time stream of system events that describes changes in AWS resources. AWS IoT Greengrass sends these events to EventBridge on an *at least once* basis. This means that AWS IoT Greengrass might send multiple copies of a given event to ensure delivery. Additionally, your event listeners might not receive the events in the order that the events occurred.
**Note**
Amazon EventBridge is an event bus service that you can use to connect your applications with data from a variety of sources, such as [Greengrass core devices](telemetry.md) and deployment notifications. For more information, see [What is Amazon EventBridge?](https://docs.aws.amazon.com/eventbridge/latest/userguide/what-is-amazon-eventbridge.html) in the *Amazon EventBridge User Guide*.
AWS IoT Greengrass emits an event when group deployments change state. You can create an EventBridge rule that runs for all state transitions or transitions to states you specify. When a deployment enters a state that initiates a rule, EventBridge invokes the target actions defined in the rule. This allows you to send notifications, capture event information, take corrective action, or initiate other events in response to a state change. For example, you can create rules for the following use cases:
+ Initiate post-deployment operations, such as downloading assets and notifying personnel.
+ Send notifications upon a successful or failed deployment.
+ Publish custom metrics about deployment events.
AWS IoT Greengrass emits an event when a deployment enters the following states: `Building`, `InProgress`, `Success`, and `Failure`.
**Note**
Monitoring the status of a [bulk deployment](bulk-deploy-cli.md) operation is not currently supported. However, AWS IoT Greengrass emits state-change events for individual group deployments that are part of a bulk deployment.
## Group deployment status change event
The [event](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/CloudWatchEventsandEventPatterns.html) for a deployment state change uses the following format:
```
{
"version":"0",
"id":" cd4d811e-ab12-322b-8255-EXAMPLEb1bc8",
"detail-type":"Greengrass Deployment Status Change",
"source":"aws.greengrass",
"account":"123456789012",
"time":"2018-03-22T00:38:11Z",
"region":"us-west-2",
"resources":[],
"detail":{
"group-id": "284dcd4e-24bc-4c8c-a770-EXAMPLEf03b8",
"deployment-id": "4f38f1a7-3dd0-42a1-af48-EXAMPLE09681",
"deployment-type": "NewDeployment|Redeployment|ResetDeployment|ForceResetDeployment",
"status": "Building|InProgress|Success|Failure"
}
}
```
You can create rules that apply to one or more groups. You can filter rules by one or more of the following deployment types and deployment states:
**Deployment types**
+ `NewDeployment`. The first deployment of a group version.
+ `ReDeployment`. A redeployment of a group version.
+ `ResetDeployment`. Deletes deployment information stored in the AWS Cloud and on the AWS IoT Greengrass core. For more information, see [Reset deployments](reset-deployments-scenario.md).
+ `ForceResetDeployment`. Deletes deployment information stored in the AWS Cloud and reports success without waiting for the core to respond. Also deletes deployment information stored on the core if the core is connected or when it next connects.
**Deployment states**
+ `Building`. AWS IoT Greengrass is validating the group configuration and building deployment artifacts.
+ `InProgress`. The deployment is in progress on the AWS IoT Greengrass core.
+ `Success`. The deployment was successful.
+ `Failure`. The deployment failed.
It's possible that events might be duplicated or out of order. To determine the order of events, use the `time` property.
**Note**
AWS IoT Greengrass doesn't use the `resources` property, so it's always empty.
## Prerequisites for creating EventBridge rules
Before you create an EventBridge rule for AWS IoT Greengrass, do the following:
+ Familiarize yourself with events, rules, and targets in EventBridge.
+ Create and configure the targets invoked by your EventBridge rules. Rules can invoke many types of targets, including:
+ Amazon Simple Notification Service (Amazon SNS)
+ AWS Lambda functions
+ Amazon Kinesis Video Streams
+ Amazon Simple Queue Service (Amazon SQS) queues
For more information, see [What is Amazon EventBridge?](https://docs.aws.amazon.com/eventbridge/latest/userguide/what-is-amazon-eventbridge.html) and [Getting started with Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-getting-set-up.html) in the *Amazon EventBridge User Guide*.
## Configure deployment notifications (console)
Use the following steps to create an EventBridge rule that publishes an Amazon SNS topic when the deployment state changes for a group. This allows web servers, email addresses, and other topic subscribers to respond to the event. For more information, see [Creating a EventBridge rule that triggers on an event from an AWS resource](https://docs.aws.amazon.com/eventbridge/latest/userguide/create-eventbridge-rule.html) in the *Amazon EventBridge User Guide*.
1. Open the [Amazon EventBridge console](https://console.aws.amazon.com/events/).
1. In the navigation pane, choose **Rules**.
1. Choose **Create rule**.
1. Enter a name and description for the rule.
A rule can't have the same name as another rule in the same Region and on the same event bus.
1. For **Event bus**, choose the event bus that you want to associate with this rule. If you want this rule to match events that come from your account, select **AWS default event bus**. When an AWS service in your account emits an event, it always goes to your account's default event bus.
1. For **Rule type**, choose **Rule with an event pattern**.
1. Choose **Next**.
1. For **Event source**, choose **AWS services**.
1. For **Event pattern**, choose **AWS services**.
1. For **AWS service**, choose Greengrass.
1. For **Event type**, choose **Greengrass Deployment Status Change**.
**Note**
The **AWS API Call via CloudTrail** event type is based on AWS IoT Greengrass integration with AWS CloudTrail. You can use this option to create rules initiated by read or write calls to the AWS IoT Greengrass API. For more information, see [Logging AWS IoT Greengrass API calls with AWS CloudTrail](logging-using-cloudtrail.md).
1. Choose the deployment states that initiate a notification.
+ To receive notifications for all state change events, choose **Any state**.
+ To receive notifications for some state change events only, choose **Specific state(s)**, and then choose the target states.
1. Choose the deployment types that initiate a notification.
+ To receive notifications for all deployment types, choose **Any state**.
+ To receive notifications for some deployment types only, choose **Specific state(s)**, and then choose the target deployment types.
1. Choose **Next**.
1. For **Target types**, choose **AWS service**.
1. For **Select a target**, configure your target. This example uses an Amazon SNS topic, but you can configure other target types to send notifications.
1. For **Target**, choose **SNS topic**.
1. For **Topic**, choose your target topic.
1. Choose **Next**.
1. Under **Tags**, define tags for the rule or leave the fields empty.
1. Choose **Next**.
1. Review the details of the rule and choose **Create rule**.
## Configure deployment notifications (CLI)
Use the following steps to create an EventBridge rule that publishes an Amazon SNS topic when the deployment state changes for a group. This allows web servers, email addresses, and other topic subscribers to respond to the event.
1. Create the rule.
+ Replace *group-id* with the ID of your AWS IoT Greengrass group.
```
aws events put-rule \
--name TestRule \
--event-pattern "{\"source\": [\"aws.greengrass\"], \"detail\": {\"group-id\": [\"group-id\"]}}"
```
Properties that are omitted from the pattern are ignored.
1. Add the topic as a rule target.
+ Replace *topic-arn* with the ARN of your Amazon SNS topic.
```
aws events put-targets \
--rule TestRule \
--targets "Id"="1","Arn"="topic-arn"
```
**Note**
To allow Amazon EventBridge to call your target topic, you must add a resource-based policy to your topic. For more information, see [Amazon SNS permissions](https://docs.aws.amazon.com/eventbridge/latest/userguide/resource-based-policies-eventbridge.html#sns-permissions) in the *Amazon EventBridge User Guide*.
For more information, see [Events and event patterns in EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html) in the *Amazon EventBridge User Guide*.
## Configure deployment notifications (CloudFormation)
Use CloudFormation templates to create EventBridge rules that send notifications about state changes for your Greengrass group deployments. For more information, see [Amazon EventBridge resource type reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/AWS_Events.html) in the *AWS CloudFormation User Guide*.
## See also
+ [Deploy AWS IoT Greengrass groups to an AWS IoT Greengrass core](deployments.md)
+ [What is Amazon EventBridge?](https://docs.aws.amazon.com/eventbridge/latest/userguide/what-is-amazon-eventbridge.html) in the *Amazon EventBridge User Guide*
# Reset deployments
This feature is available for AWS IoT Greengrass Core v1.1 and later.
You might want to reset a group's deployments to:
+ Delete the group, such as when you want to move the group's core to another group, or the group's core has been reimaged. Before you delete a group, you must reset the group's deployments to use the core with another Greengrass group.
+ Move the group's core to a different group.
+ Revert the group to its state before any deployments.
+ Remove the deployment configuration from the core device.
+ Delete sensitive data from the core device or from the cloud.
+ Deploy a new group configuration to a core without having to replace the core with another in the current group.
**Note**
Reset deployments functionality is not available in AWS IoT Greengrass Core Software v1.0.0. You cannot delete a group that has been deployed using v1.0.0.
The reset deployments operation first cleans up all deployment information stored in the cloud for a given group. It then instructs the group's core device to clean up all of its deployment related information as well (Lambda functions, user logs, shadow database and server certificate, but not the user-defined `config.json` or the Greengrass core certificates). You cannot initiate a reset of deployments for a group if the group currently has a deployment with status of `In Progress` or `Building`.
## Reset deployments from the AWS IoT console
You can reset group deployments from group configuration page in the AWS IoT console.
1. In the AWS IoT console navigation pane, under **Manage**, expand **Greengrass devices**, and then choose **Groups (V1)**.
1. Choose the target group.
1. From the **Deployments** tab, choose **Reset deployments**.
1. In the **Reset deployments for this Greengrass Group** dialog box, type **confirm** to agree, and choose **Reset deployment**.
## Reset deployments with the AWS IoT Greengrass API
You can use the `ResetDeployments` action in the AWS CLI, AWS IoT Greengrass API, or AWS SDK to reset deployments. The examples in this topic use the CLI.
```
aws greengrass reset-deployments --group-id GroupId [--force]
```Arguments for the `reset-deployments` CLI command:
`--group-id`
The group ID. Use the `list-groups` command to get this value.
`--force`
Optional. Use this parameter if the group's core device has been lost, stolen, or destroyed. This option causes the reset deployment process to report success after all deployment information in the cloud has been cleaned up, without waiting for a core device to respond. However, if the core device is or becomes active, it also performs cleanup operations.
The output of the `reset-deployments` CLI command looks like this:
```
{
"DeploymentId": "4db95ef8-9309-4774-95a4-eea580b6ceef",
"DeploymentArn": "arn:aws:greengrass:us-west-2:106511594199:/greengrass/groups/b744ed45-a7df-4227-860a-8d4492caa412/deployments/4db95ef8-9309-4774-95a4-eea580b6ceef"
}
```
You can check the status of the reset deployment with the `get-deployment-status` CLI command:
```
aws greengrass get-deployment-status --deployment-id DeploymentId --group-id GroupId
```Arguments for the `get-deployment-status` CLI command:
`--deployment-id`
The deployment ID.
`--group-id`
The group ID.
The output of the `get-deployment-status` CLI command looks like this:
```
{
"DeploymentStatus": "Success",
"UpdatedAt": "2017-04-04T00:00:00.000Z"
}
```
The `DeploymentStatus` is set to `Building` when the reset deployment is being prepared. When the reset deployment is ready but the AWS IoT Greengrass core has not picked up the reset deployment, the `DeploymentStatus` is `InProgress`.
If the reset operation fails, error information is returned in the response.
## See also
+ [Deploy AWS IoT Greengrass groups to an AWS IoT Greengrass core](deployments.md)
+ [ResetDeployments ](https://docs.aws.amazon.com/greengrass/v1/apireference/resetdeployments-post.html) in the *AWS IoT Greengrass Version 1 API Reference*
+ [GetDeploymentStatus ](https://docs.aws.amazon.com/greengrass/v1/apireference/getdeploymentstatus-get.html) in the *AWS IoT Greengrass Version 1 API Reference*
# 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:
1. [Create and upload the bulk deployment input file](#bulk-deploy-cli-create-input-file)
1. [Create and configure an IAM execution role for bulk deployments](#bulk-deploy-cli-create-role)
1. [Allow your execution role access to your S3 Bucket](#bulk-deploy-cli-modify-bucket)
1. [Deploy the groups](#bulk-deploy-cli-start-bulk-deployments)
1. [Test the deployment](#bulk-deploy-cli-test)
## Prerequisites
To complete this tutorial, you need:
+ One or more deployable Greengrass groups. For more information about creating AWS IoT Greengrass groups and cores, see [Getting started with AWS IoT Greengrass](gg-gs.md).
+ The AWS CLI installed and configured on your machine. For information, see the [AWS CLI User Guide](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html).
+ An S3 bucket created in the same AWS Region as AWS IoT Greengrass. For information, see [ Creating and configuring an S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-configure-bucket.html) in the *Amazon Simple Storage Service User Guide*.
**Note**
Currently, SSE KMS enabled buckets are not supported.
## 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.
1. 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 AWS IoT Greengrass can identify each group to be deployed.
**Note**
You can also find these values in the AWS IoT console. The group ID is displayed on the group's **Settings** page. Group version IDs are displayed on the group's **Deployments** tab.
```
aws greengrass list-groups
```
The response contains information about each group in your AWS 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"
}
```
1. In your computer terminal or editor of choice, create a file, *MyBulkDeploymentInputFile*, from the following example. This file contains information about each AWS 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.
**Note**
The size of this file must be less than 100 MB.
```
{"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, AWS IoT Greengrass supports `NewDeployment` bulk deployment types only.
Save and close your file. Make a note of the location of the file.
1. 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](https://docs.aws.amazon.com/AmazonS3/latest/gsg/PuttingAnObjectInABucket.html).
```
aws s3 cp path/MyBulkDeploymentInputFile s3://amzn-s3-demo-bucket/
```
## 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.
1. Use the following policy to create an execution role. This policy document allows AWS 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "greengrass:CreateDeployment",
"Resource": [
"arn:aws:greengrass:us-east-1:123456789012:/greengrass/groups/groupId1",
"arn:aws:greengrass:us-east-1:123456789012:/greengrass/groups/groupId2",
"arn:aws:greengrass:us-east-1:123456789012:/greengrass/groups/groupId3"
]
}
]
}
```
------
**Note**
This policy must have a resource for each group or group version in your bulk deployment input file to be deployed by AWS IoT Greengrass. To allow access to all groups, for `Resource`, specify an asterisk:
```
"Resource": ["*"]
```
1. Modify the trust relationship for your execution role to include AWS IoT Greengrass. This allows AWS IoT Greengrass to use your execution role and the permissions attached to it. For information, see [Editing the trust relationship for an existing role](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/edit_trust.html).
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](cross-service-confused-deputy-prevention.md).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "greengrass.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:greengrass:us-east-1:123456789012:*"
}
}
}
]
}
```
------
1. 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 AWS IoT Greengrass for use. For more information, see [Granting a user permissions to pass a role to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html).
Use the following example to update the IAM policy attached to your execution role. Modify this example, as necessary.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1508193814000",
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": [
"arn:aws:iam::123456789012:user/executionRoleArn"
],
"Condition": {
"StringEquals": {
"iam:PassedToService": "greengrass.amazonaws.com"
}
}
}
]
}
```
------
## 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?](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/add-bucket-policy.html)
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "examplePolicy",
"Statement": [
{
"Sid": "Stmt1535408982966",
"Effect": "Allow",
"Principal": {
"AWS": [
"executionRoleArn"
]
},
"Action": "s3:GetObject",
"Resource":
"arn:aws:s3:::amzn-s3-demo-bucket/objectKey"
}
]
}
```
------
You can use the following command in your terminal to check your bucket's policy:
```
aws s3api get-bucket-policy --bucket amzn-s3-demo-bucket
```
**Note**
You can directly modify your execution role to grant it permission to your Amazon S3 bucket's `GetObject` permissions instead. To do this, attach the following example policy to your execution role.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-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`.
**Note**
You cannot call **StartBulkDeployment** while another bulk deployment from the same account is still running. The request is rejected.
1. 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.
**Note**
Although bulk deployment operations are not currently supported, you can create Amazon EventBridge event rules to get notifications about deployment status changes for individual groups. For more information, see [Get deployment notifications](deployment-notifications.md).
1. 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:
+ `Initializing`. The bulk deployment request has been received, and the execution is preparing to start.
+ `Running`. The bulk deployment execution has started.
+ `Completed`. The bulk deployment execution has finished processing all records.
+ `Stopping`. The bulk deployment execution has received a command to stop and will terminate shortly. You can't start a new bulk deployment while a previous deployment is in the `Stopping` state.
+ `Stopped`. The bulk deployment execution has been manually stopped.
+ `Failed`. The bulk deployment execution has encountered an error and terminated. You can find error details in the `ErrorDetails` field.
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:
+ `RecordsProcessed`: The number of group records that were attempted.
+ `InvalidInputRecords`: The total number of records that returned a non-retryable error. For example, this can occur if a group record from the input file uses an invalid format or specifies a nonexistent group version, or if the execution doesn't grant permission to deploy a group or group version.
+ `RetryAttempts`: The number of deployment attempts that returned a retryable error. For example, a retry is triggered if the attempt to deploy a group returns a throttling error. A group deployment can be retried up to five times.
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.
## 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:
+
```
InvalidInputFile: Missing GroupId at line number: line number
```
This error indicates that the given input file line is unable to register the specified parameter. The possible missing parameters are the `GroupId` and the `GroupVersionId`.
+
```
InvalidInputFile: Invalid deployment type at line number : line number. Only valid type is 'NewDeployment'.
```
This error indicates that the given input file line lists an invalid deployment type. At this time, the only supported deployment type is a `NewDeployment`.
+
```
Line %s is too long in S3 File. Valid line is less than 256 chars.
```
This error indicates that the given input file line is too long and must be shortened.
+
```
Failed to parse input file at line number: line number
```
This error indicates that the given input file line is not considered valid json.
### 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](greengrass-logs-overview.md).
## See also
For more information, see the following resources:
+ [Deploy AWS IoT Greengrass groups to an AWS IoT Greengrass core](deployments.md)
+ [Amazon S3 API commands](https://docs.aws.amazon.com/cli/latest/reference/s3api) in the *AWS CLI Command Reference*
+ [AWS IoT Greengrass commands](https://docs.aws.amazon.com/cli/latest/reference/greengrass/index.html) in the *AWS CLI Command Reference*