AWS Greengrass is a great technology. If you’re reading this, you likely already think so too. If you don’t — check out re:Invent keynote and AWS Greengrass intro, and you’ll come back convinced and inspired to hack.

To master Greengrass beyond the tutorials, to define and deploy setups in automated, reliable, repeatable way, one must hit the AWS API or CLI — we long live in the bright DevOps world.

There is a big problem here: while AWS documentation on Greengrass lists individual calls, it gives no clue on where to start. There is no map to show how to wire the calls together. All parts are in place, but the assembly manual is missing. Or, was missing — until this post.

Getting Started

I’ll begin with the high level: concept definitions, a map of the model, some theory on how things work … but my millennial readers are eager to learn by doing, so let’s get started with some working code. No worries, you’ll still find the map and concepts below.

This is the code to create a Greengrass group with a single core.

As a bonus, get this code in a Jupyter Notebook for your convenience and immediate gratification!

When you click a single “Create Group” button in the AWS console to create Greengrass Core, the code provided below is what happens bend the scenes. It’s quite a lot … 7 calls across 3 AWS services — 5 entities created explicitly, 2 implicitly.

Creating the group is just the beginning — you’ll still need to:

create Lambda functions with AWS Lambda

register them with IoT via Lambda definitions

define resources for your Lambdas to access

configure loggers and register devices

setup MQTT subscriptions for every point-to-point communication

deploy the whole shebang to a Greengrass core

And by the way, all of this must be properly installed and configured, carry the right certificates, and run on your edge device. If it sounds a bit complex, it is because it is a bit complex. Time to elevate to the concepts and get oriented.

The Lifecycle Workflow

First, let’s review the steps of a Greengrass operation lifecycle workflow.

Create Greengrass group definition in AWS IoT — a number of calls to AWS API to create and connect all necessary entities. Setup Greengrass core “on the edge” — configure a box Raspberry Pi or other compatible device, or VM / Docker for dev & testing. Download and install a proper version of greengrass, put certificates in place, adjust `config.json`, and launch the Greengrass daemon. Deploy — tell AWS to push Greengrass group definition to the Greengrass Core runtime(s). Clean up — the steps 1–3 produce a slew of artifacts that would pollute your AWS account if not properly recycled.

The Model

Next let’s understand the model. The group definition — step 1 above — is by far the most complex. To help you navigate it, I created a “Greengrass Entity Map”. While the map is not a topologically precise representation of AWS API, it would help you grasp the model and not be lost.

Greengrass is intertwined with other AWS services — most notably IoT, Lambda, and IAM & security which are color-coded on the map. Take a look at the map. Spot the objects created by the code above. Explore the rest. Enjoy!