Deploying groups (console)Deploying groups (API)Overview of the group object model See also

Amazon IoT Greengrass Version 1 entered the extended life phase on June 30, 2023. For more information, see the Amazon IoT Greengrass V1 maintenance policy. After this date, Amazon IoT Greengrass V1 won't release updates that provide features, enhancements, bug fixes, or security patches. Devices that run on Amazon IoT Greengrass V1 won't be disrupted and will continue to operate and to connect to the cloud. We strongly recommend that you migrate to Amazon IoT Greengrass Version 2, which adds significant new features and support for additional platforms.

Deploy Amazon IoT Greengrass groups to an Amazon IoT Greengrass core

Use Amazon 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 Amazon Web Services 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, which is an Amazon IoT device that runs the Amazon IoT Greengrass Core software. The core acts as an edge gateway and provides Amazon 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 Amazon IoT registry. These devices must run FreeRTOS or use the Amazon IoT Device SDK or Amazon IoT Greengrass Discovery API 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 Amazon Lambda and referenced from a Greengrass group. For more information, see Run Lambda functions on the Amazon IoT Greengrass core.
Connectors. Predefined serverless applications that run code on the core. Connectors can provide built-in integration with local infrastructure, device protocols, Amazon, and other cloud services. For more information, see Integrate with services and protocols using Greengrass connectors.
Subscriptions. Defines the publishers, subscribers, and MQTT topics (or subjects) that are authorized for MQTT communication.
Resources. References to local devices and volumes, machine learning models, and secrets, used for access control by Greengrass Lambda functions and connectors.
Logs. Logging configurations for Amazon IoT Greengrass system components and Lambda functions. For more information, see Monitoring with Amazon IoT Greengrass logs.

You manage your Greengrass group in the Amazon Web Services 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.

Note

During a deployment, the Greengrass daemon process on the core device stops and then restarts.

Deploying groups from the Amazon IoT console

You can deploy a group and manage its deployments from the group's configuration page in the Amazon 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.

From the group configuration page, choose the Deployments tab.
To see more information about a deployment, including error messages, choose Deployments from the Amazon 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.

From the Amazon IoT console, choose Greengrass devices, and then choose Groups (V1).
Choose the Deployments tab.
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.

From the Amazon IoT console, choose Greengrass devices, and then choose Groups (V1).
Choose the Deployments tab.
Choose the deployment you want to reset and choose Reset deployments.

Deploying groups with the Amazon IoT Greengrass API

The Amazon IoT Greengrass API provides the following actions to deploy Amazon IoT Greengrass groups and manage group deployments. You can call these actions from the Amazon CLI, Amazon IoT Greengrass API, or Amazon SDK.

Action	Description
CreateDeployment	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	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.
ListDeployments	Returns the deployment history for the group.
ResetDeployments	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.

Note

For information about bulk deployment operations, see Create bulk deployments for groups.

Getting the group ID

The group ID is commonly used in API actions. You can use the ListGroups action to find the ID of the target group from your list of groups. For example, in the Amazon 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.

Note

You can also find these values in the Amazon 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 Amazon Web Services Region, Amazon 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 Amazon IoT Greengrass group object model

When programming with the Amazon IoT Greengrass API, it's helpful to understand the Greengrass group object model.

Groups

In the Amazon 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.

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.

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 Amazon 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:

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.

Updating groups

In the Amazon 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 must be associated with your Amazon Web Services account in the Amazon Web Services 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 Amazon resources

Greengrass Lambda functions and secret resources define Greengrass-specific properties and also reference corresponding Amazon resources. To update these entities, you might make changes to the corresponding Amazon resource instead of your Greengrass objects. For example, Lambda functions reference a function in Amazon 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 Amazon Lambda. During the next group deployment, these changes are retrieved from Amazon Lambda and copied to your local environment.
To update Greengrass-specific properties, 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 Amazon Lambda. For more information, see Reference Lambda functions by alias or version.