Getting Started with Lambda Powered by Amazon IoT Greengrass - Amazon Snowball Edge Developer Guide
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Getting Started with Lambda Powered by Amazon IoT Greengrass

To get started with Amazon Lambda powered by Amazon IoT Greengrass functions on an Amazon Snowball Edge device, take the following steps:

Associating an Amazon IoT Greengrass Service Role with Your Account

Before you can use Amazon IoT Greengrass with a Snowball Edge as a core device, you must associate an Amazon IoT Greengrass service role with your account. This association allows Amazon IoT Greengrass to access your Lambda functions and Amazon IoT resources. If you try to create a job for a Snowball Edge before you associate the service role, the job creation request fails.

The following procedures show how to configure and store your Amazon IoT Greengrass settings in the cloud. This configuration means that you can push Lambda function changes to the Snowball Edge and changes to other devices in your Amazon IoT Greengrass group. The first procedure uses the Amazon Identity and Access Management (IAM) console, and the second procedure uses the Amazon Command Line Interface (Amazon CLI).

To create an Amazon IoT Greengrass service role in the IAM console

  1. Sign in to the Amazon Web Services Management Console and open the IAM console at https://console.amazonaws.cn/iam/.

  2. For Role Type, choose Amazon Greengrass Role.

  3. Select AWSGreengrassResourceAccessPolicy, and then choose Next Step.

  4. Enter a name for your role, and then choose Create Role.

After creating the role, make a note of the role Amazon Resource Name (ARN), and use it in the next procedure.

To associate the Amazon IoT Greengrass service role with your account

  1. Install the Amazon CLI on your computer, if you haven't already. For more information, see Installing the Amazon CLI in the Amazon Command Line Interface User Guide.

  2. Configure the Amazon CLI on your computer, if you haven't already. For more information, see Configuring the Amazon CLI in the Amazon Command Line Interface User Guide.

  3. Open a terminal on your computer and run the following Amazon CLI command, with the Amazon IoT Greengrass role ARN you created in the first procedure.

    aws greengrass associate-service-role-to-account --role-arn arn:aws:iam::123EXAMPLE12:role/GreengrassRole

Now you can create a job for a Snowball Edge and use Amazon Lambda powered by Amazon IoT Greengrass.

Configuring Amazon IoT Greengrass with a Snowball Edge

When you create a compute job for a Snowball Edge, the service automatically configures the following Amazon IoT Greengrass elements:

  • Amazon IoT Greengrass core software – The Amazon IoT Greengrass distributable has been pre-installed on the Snowball Edge.

  • Amazon IoT Greengrass group – When you create a compute job, an Amazon IoT Greengrass group named JobID_group is created and provisioned. The core of this group is named JobID_core, and it has a device in it named JobID_s3adapter. The Amazon S3 interface is registered as an IoT device in your Amazon IoT Greengrass group. This registration is because the S3 interface sends MQTT messages for every Amazon S3 PUT object action for the buckets on the Snowball Edge.

If you have other configuration changes that you want to make for the Amazon IoT Greengrass group associated with a Snowball Edge, you can make them after you unlock the device and connect it to the internet.

Creating Your Job

Create a job in the Amazon Snow Family Management Console and associate the Amazon Resource Name (ARN) for at least one published Lambda function with a bucket. For a walkthrough on creating your first job, see Creating an Amazon Snowball Edge Job.

All the Lambda functions that you choose during job creation are triggered by MQTT messages sent by the IoT device associated with the Amazon S3 interface. These MQTT messages are triggered when an Amazon S3 PUT object action is made against the bucket on the Amazon Snowball Edge device.

Creating a Virtual Network Interface

When the Snowball Edge arrives, unlock the device, and create a virtual network interface to bind to Amazon IoT Greengrass. Each Snowball Edge has three network interfaces (NICs), the physical network interface controllers for the device. These are the RJ45, SFP, and QSFP ports on the back of the device.

Each virtual NIC (VNIC) is based on the physical one, and you can have any number of VNICs associated with each NIC. To create a virtual network interface, use the snowballEdge create-virtual-network-interface command.

Note

--static-ip-address-configuration is only a valid option when using STATIC for --ip-address-assignment.

Usage (configured Snowball Edge client)

snowballEdge create-virtual-network-interface --ip-address-assignment [DHCP or STATIC] --physical-network-interface-id [physical network interface id] --static-ip-address-configuration IpAddress=[IP address],NetMask=[Netmask]

Usage (Snowball Edge client not configured)

snowballEdge create-virtual-network-interface --endpoint https://[ip address] --manifest-file /path/to/manifest --unlock-code [unlock code] --ip-address-assignment [DHCP or STATIC] --physical-network-interface-id [physical network interface id] --static-ip-address-configuration IpAddress=[IP address],NetMask=[Netmask]

Example Creating VNICs (DHCP)

./snowballEdge create-virtual-network-interface --ip-address-assignment dhcp --physical-network-interface-id s.ni-8EXAMPLEaEXAMPLEd { "VirtualNetworkInterface" : { "VirtualNetworkInterfaceArn" : "arn:aws:snowball-device:::interface/s.ni-8EXAMPLE8EXAMPLEf", "PhysicalNetworkInterfaceId" : "s.ni-8EXAMPLEaEXAMPLEd", "IpAddressAssignment" : "DHCP", "IpAddress" : "192.0.2.0", "Netmask" : "255.255.255.0", "DefaultGateway" : "192.0.2.1", "MacAddress" : "EX:AM:PL:E1:23:45" } }

Starting Amazon IoT Greengrass on a Snowball Edge

Before you can use Amazon Lambda powered by Amazon IoT Greengrass, you need to use the Snowball Edge client to start it.

Note

It can take several minutes to start Amazon IoT Greengrass on a Snowball Edge. We recommend using the describe-service Snowball Edge client command after you start the service to determine when it's active. For more information, see Getting Service Status.

To start Amazon Lambda powered by Amazon IoT Greengrass

  1. Run the snowballEdge describe-device command to get the list of network interface IDs. For more information on this command, see Getting Device Status.

  2. Identify the ID for the physical network interface that you want to use, and make a note of it. The following examples show running this command with the two different IP address assignment methods, either DHCP or STATIC.

    snowballEdge create-virtual-network-interface \ --physical-network-interface-id s.ni-abcd1234 \ --ip-address-assignment DHCP                  //OR//         snowballEdge create-virtual-network-interface \ --physical-network-interface-id s.ni-abcd1234 \ --ip-address-assignment STATIC \ --static-ip-address-configuration IpAddress=192.0.2.0,Netmask=255.255.255.0
  3. The command returns a JSON structure that includes the virtual network interface ARN. Make a note of that ARN.

  4. Start the Amazon IoT Greengrass service using the virtual network interface, as in the following example.

    snowballEdge start-service \ --service-id greengrass\ --virtual-network-interface-arns arn:aws:snowball-device:::interface/s.ni-abcd1234abcd1234a

Amazon Lambda powered by Amazon IoT Greengrass has now started. Anytime you need the IP address or virtual network interface ARN for the Amazon IoT Greengrass, you can use the snowballEdge describe-virtual-network-interfaces Snowball Edge client command.

Connecting to the Internet to Update Amazon IoT Greengrass Group Certificates

Every time you start the Amazon IoT Greengrass service, you must log into the Amazon IoT Greengrass console with the account used to create the job in the Amazon Snow Family Management Console and initiate an Amazon IoT Greengrass group deployment to the Amazon IoT Greengrass core. For more information, see https://docs.aws.amazon.com/greengrass/v2/developerguide/import-lambda-function-console.html in the Amazon IoT Greengrass Developer Guide. After that, you can disconnect the device from the internet. The associated Amazon IoT Greengrass group then functions in offline mode.

Important

When the IP address for any device in the local Amazon IoT Greengrass group changes, reconnect the Snowball Edge to the internet so it can get new certificates.

Using Lambda Powered by Amazon IoT Greengrass Functions on a Snowball Edge

Now that the service is started, and you've initiated an Amazon IoT Greengrass group deployment to the Amazon IoT Greengrass core, you can trigger Lambda functions by writing data to the Amazon S3 buckets on the device. Unless programmed otherwise, Lambda functions are triggered by MQTT messages sent by the IoT device associated with the Amazon S3 interface. These MQTT messages are in turn triggered by Amazon S3 PUT object actions. Amazon S3 PUT object actions occur through the NFS interface (with a write operation), the Amazon CLI (using the Amazon S3 interface), or programmatically through one of the SDKs or a REST application of your own design.

You can use your Lambda powered by Amazon IoT Greengrass functions to run Python code against public endpoints among Amazon services in the cloud. For this Python code execution to work, your Amazon Snowball Edge device must be connected to the internet. For more information, see the Amazon Lambda Developer Guide.

Updating Existing Functions

You can update existing Lambda functions in the console. If you do, and if your Amazon Snowball Edge device is connected to the internet, a deployment agent notifies each Lambda function of the updated Amazon IoT Greengrass group configuration. For more information, see Create a Deployment in the Amazon IoT Greengrass Developer Guide.

Adding New Functions

After your Snowball Edge arrives and you unlock it and connect it to the internet, you can add or remove Lambda functions. These new Lambda functions don't have to be triggered by Amazon S3 PUT object actions. Instead, the event that you programmed to trigger the new functions performs function triggering, as with typical Lambda functions running in an Amazon IoT Greengrass group.

Testing Lambda Powered by Amazon IoT Greengrass Functions

You can test your Lambda functions before you create your job, or after you've started Amazon IoT Greengrass on the device. When testing your Python-coded function in the Lambda console, before creating your job, you might encounter errors. If that happens, see Error handling and automatic retries in the Amazon Lambda Developer Guide.

To test your Lambda functions on-premises, use the following procedure.

To test your Lambda functions on-premises

  1. Create a subscription in the Amazon IoT Greengrass console. For more information, see Configure subscriptions in the Amazon IoT Greengrass Developer Guide.

  2. Deploy the Amazon IoT Greengrass group containing that subscription to the Amazon IoT Greengrass core running on the Snowball Edge device. In this subscription, you specify the following:

    • The Source as the device with Snowball Edge Job ID generated when you created the job.

    • The Target as the Amazon IoT service.

  3. After the deployment is successfully completed, log into the Amazon IoT console with the account used to create your job.

  4. Choose Test, and then choose Subscribe to a topic.

  5. For Subscription topic, enter the name of the bucket on the Snowball Edge to copy an object into.

  6. Choose Subscribe to topic. The MQTT client page then shows you the subscription to the bucket that you specified.

  7. Using the Amazon CLI, Amazon S3 interface, or one of the Amazon SDKs, copy an object to the specified bucket.

A JSON object then displays the payloads included in the MQTT message published to the Amazon IoT Greengrass core backing the Amazon IoT Greengrass service running on the Snowball Edge device. This payload includes the name of the object and the name of the bucket the object was PUT into.

You've now successfully tested your Lambda function. The JSON object indicates that the MQTT message published to the Amazon IoT Greengrass core was received successfully, and the associated Lambda function was run. For information about adding Amazon IoT Greengrass subscriptions to your Amazon IoT Greengrass group, see Configure subscriptions in the Amazon IoT Greengrass Developer Guide.

Stopping Amazon IoT Greengrass

When you're done with Lambda powered by Amazon IoT Greengrass, you can stop it with the snowballEdge stop-service Snowball Edge client command. For more information, see Stopping a Service on Your Snowball Edge.

Lambda powered by Amazon IoT Greengrass running on a Snowball Edge device is stateless. As a result, any data (including Amazon IoT Greengrass configuration, certificates, and Lambda functions) running on the device is lost when the Amazon IoT Greengrass service enters the DEACTIVATING state or becomes INACTIVE.