File-driven creation of an entire AWS Greengrass group
Greengrass gg_group_setup
is an example file-driven approach to the creation
of an entire AWS Greengrass group.
This repository demonstrates how one might automate the following discrete steps, but if you're doing full, complex, deployment management of Greengrass Groups you will want to explore the new Greengrass CloudFormation support and read this blog post.
Usually the following discrete steps are necessary to setup and deploy a Greengrass group.
create_thing
create_core_definition
create_device_definition
create_function_definition
create_logger_definition
create_subscription_definition
create_deployment
gg_group_setup
provides functioning example code of how a Greengrass Group is
created. It also provides a:
gg_group_setup
config file parser GroupConfigFile
which can be sub-classedGroupComnands
class
GroupCommands
class is also an example implementation of the steps
necessary to create a Greengrass Group.GroupType
which can be sub-classed for more complex GroupCommands
scenariosgg_group_setup
includes multiple commands:
create
, deploy
, create-core
, create-devices
, clean-core
,
clean-devices
, clean-file
, and clean-all
.
After installation you can use these commands from the Command Line Interface, or
you can use them from within a program via the GroupCommands
class.
The quickest way to get gg_group_setup
is to install the latest stable version via pip
.
pip install gg-group-setup
After installation, for command line help type:
gg_group_setup create -- --help
gg_group_setup deploy -- --help
gg_group_setup create-core -- --help
gg_group_setup create-devices -- --help
gg_group_setup clean-core -- --help
gg_group_setup clean-devices -- --help
gg_group_setup clean-file -- --help
gg_group_setup clean-all -- --help
gg_group_setup associate_devices -- --help
The high-level process to create a Greengrass group using gg_group_setup
is as
follows:
$ gg_group_setup create-core <thing_name> <config_file>
-- to create a Greengrass Core named thing_name
$ gg_group_setup create-devices '[<device_thing_name_01>,<device_thing_name_02,...]' <config_file>
-- to create things for use as devices in your Greengrass Group.<config_file>
. Example: cfg.json
lambda_functions
section
In the lambda_functions
section of the configuration, replace <function_name>
with the name of the Lambda function configured and aliased previously. Then for
that function enter the arn
and arn_qualifier
of the function.
"lambda_functions": {
"<function_name>": {
"arn": "<lambda_ARN>",
"arn_qualifier": "<alias>"
"environment_variables": {
"<name>": "<value>",
}
}
},
For example, if the Lambda function is created in us-west-2
, named
MyFirstGreengrassLambda
, and the alias named dev
pointing to version 1
,
the lambda_functions
section would contain these values.
"lambda_functions": {
"MyFirstGreengrassLambda": {
"arn": "arn:aws:lambda:us-west-2:<account_id>:function:MyFirstGreengrassLambda:dev",
"arn_qualifier": "dev"
"environment_variables": {
"SAY_HELLO_TO": "Miss. Mocking Bird",
}
}
},
MyFirstGreengrassLambda
and MockDeviceLambda
, the lambda_functions
section would
contain these values.
"lambda_functions": {
"MyFirstGreengrassLambda": {
"arn": "arn:aws:lambda:us-west-2:<account_id>:function:MyFirstGreengrassLambda:dev",
"arn_qualifier": "dev"
"environment_variables": {
"SAY_HELLO_TO": "Miss. Mocking Bird",
}
},
"MockDeviceLambda": {
"arn": "arn:aws:lambda:us-west-2:<account_id>:function:MockDeviceLambda:dev",
"arn_qualifier": "dev"
"environment_variables": {
"SAY_GOODBYE_TO": "Mr. Sleepy Owl",
"SAY_GOODBYE_AT": "8:00 PM",
}
}
},
subscriptions
section
MockDevice
Lambda function expects to use the following subscriptions:
"subscriptions": {
"errors": "/errors",
"telemetry": "/telemetry"
}
$ gg_group_setup create <group_type> <config_file>
-- to create the Greengrass group$ gg_group_setup deploy <config_file>
-- to deploy the Greengrass groupNote: gg_group_setup also includes a Mock Device Lambda function you can use to get started.
gg_group_setup
as a LibraryAfter the Quick Start, you will probably want to configure your own unique Greengrass
group with its own Lambda functions, devices, and subscription topology. To do
this you will need to implement a sub-class of GroupType
.
In the gg_group_setup
folder you will see an example mock_device
Lambda function
and a mock_group
.
After implementing a sub-class of GroupType
called CustomGroupType
, update
the group <config_file>
to reflect the custom group. The custom group can then
be used in code as follows:
config_file = "<filename>" # filename of the group's <config_file>
group_name = "<group_name>" # if `None`, the group_type value will be used
region = "<aws_region>" # AWS region in which the group will be created
gc = GroupCommands(group_types={
CustomGroupType.CUSTOM_TYPE: CustomGroupType
})
gc.create(
config_file, group_type=CustomGroupType.CUSTOM_TYPE,
group_name=group_name, region=region
)
If you add your account ID to the config_file
manually before running any
commandsgg_group_setup
will use the account ID to make a notch more
restrictive Core and Device policies. Specifically, if you enter a value here:
...
"misc": {
"account_id": "<account_id_here>",
"iot_endpoint": ""
},...
These instructions show you how to find your AWS account ID.
config_file
manuallyAlthough the helper commands create-core
and create-devices
will create
things and store the proper information in the given config_file
, you can also
ignore those commands if you want to enter all the information manually.
The create
, deploy
, and clean-all
Greengrass group commands will use the
config_file
information as stored.
gg_group_setup
The aws-greengrass-mini-fulfillment
repository creates and uses pretty complex custom group types.