AWS Lambda for IoT Device Provisioning

This Lambda function allows you to provision and synchronize a balena device with AWS IoT Core in a secure and automated way via an HTTP endpoint. The endpoint may be called by a balena device, as seen in the cloud-relay example.

Method	Actions
POST	Provisions a balena device with IoT Core. First the function verifies the device UUID with balenaCloud. Then it creates a public key certificate, attaches a security policy, and registers an AWS Thing for the device. Finally the function sets balena device environment variables for these entities.
DELETE	Removes the AWS Thing and certificate for the balena device and removes the balena device environment variables. Essentially reverses the actions from provisioning with POST.

These instructions describe how to setup your AWS infrastructure for device provisioning, including tools to deploy and test the Lambda function and HTTP endpoint.

Device Environment Variables

Once the Lambda function has provisioned the device with AWS, it sets balena device environment variables as described below, which allow the device to connect to IoT Core.

Variable	Value
AWS_CERT	Public key certificate in PEM format, base64 encoded to eliminate line wrapping
AWS_PRIVATE_KEY	Private key in PEM format, base64 encoded to eliminate line wrapping

Setup and Testing

AWS setup

We assume you are somewhat familiar with AWS IoT. If not, AWS provides some focused, easy to follow documentation to help you get started. See the page, Set up your AWS account.

The setup items below all are related to AWS IAM -- Identity and Access Management. Each item allows some principal (device/role/user) to perform an action on a resource. The diagram below shows the actions and AWS resources involved.

IoT Core (for Send data)

You must define an AWS IAM policy that allows your device to connect to IoT Core and publish MQTT messages. At runtime, provisioning attaches the public key certificate created for a device to this policy.

See the documentation, Create AWS IoT resources for steps to follow. The result must allow the actions shown for the AWS_IOT_POLICY entry in the table below, like this screenshot. Your AWS account region and ID for the policy resource ARN are available in the dropdowns at the top right of the web page.

Lambda role (for Provision)

You also must define an AWS IAM Role for the HTTP gateway endpoint to execute the Lambda function. See the documentation, AWS Lambda execution role. When creating the role, use the "Lambda" use case, which allows the HTTP endpoint to assume the role for a Lambda function. Also use the specific permissons policies shown for the AWS_ROLE_ARN entry in the table below. See example screenshots of the Permissions and Trust relationships tabs.

IAM User (for Test / Deploy)

In the Workspace setup section below, we use the node-lambda package to test provisioning directly from your workstation and to deploy to AWS. It is best to assign an IAM User with limited privileges for these actions. See the documentation, Creating IAM users. The user requires Programmatic access. Attach existing policies as shown for AWS_ACCESS_KEY_ID in the table below. After you select to create the user, be sure to save the Secret access key, as shown in the screenshot.

Workspace setup

We provide command line tools to deploy and test the Lambda function and HTTP endpoint. These tools must be configured to identify your account, policies and so on. Follow the steps below to create a workspace and define these values.

The setup depends on a Mac/Linux/WSL command line and NodeJS, which is easy to install with the nvm utility.

# get the Lambda code and tools
git clone https://github.com/balena-io-examples/aws-iot-provision.git source

# create workspace
cp source/tools/template.env tools.env
cp source/tools/setup-tools.sh .

Edit tools.env to provide your values from the table below, and finally setup the tools to use these values with this command:

./setup-tools.sh

Variable	Value
AWS_ACCESS_KEY_ID	For IAM User to run/deploy the Lambda. This user must include the AWSLambda_FullAccess and AWSIoTConfigAccess policies. See AWS IAM console Users -> Security Credentials to create an access key.
AWS_SECRET_ACCESS_KEY	For access key
AWS_REGION	AWS region for registry, like us-east-1
AWS_IOT_POLICY	Name of IAM policy with iot:Connect and iot:Publish permissions for device messaging to IoT Core
AWS_ROLE_ARN	For IAM Role to execute the Lambda. This role must include the AWSIoTLogging and AWSIoTConfigAccess permissions policies.
BALENA_API_KEY	for use of balena API; found in balenaCloud dashboard at: account -> Preferences -> Access tokens

Test locally

To test the Lambda function without deploying it, run this command in the workspace you created:

# <UUID> must be for a valid device or 'test-provision'
# <method> is POST or DELETE

./test-local.sh -u <UUID> <method>

After a successful POST, you should see the device appear as a Thing in your IoT Core registry like the screenshot below, as well as its public key certificate. If using a valid UUID, the corresponding AWS_CERT and AWS_PRIVATE_KEY variables appear in balenaCloud for the device. After a successful DELETE, those variables disappear.

Deploy

To deploy to AWS Lambda, run this command in the workspace you created:

./deploy-func.sh

After deployment, visit the AWS Lambda console, and you should see an entry in the list of functions.

Create HTTP endpoint

On the console page for your function, you must create an API Gateway trigger (HTTP endpoint) from the Add trigger link in the Function overview section. See the screenshot for the settings.

The result should be a Lambda and API Gateway like below.

Test the Lambda

To test the Lambda installed on AWS, run this command in the workspace you created:

# <UUID> must be for a valid device or 'test-provision'
# <method> is POST or DELETE
# <provision_url> is for the API Gateway HTTP endpoint

./test-remote.sh -u <UUID> <method> <provision_url>

After a successful POST, you should see the device appear in your IoT Core registry. If using a valid UUID, AWS_CERT and AWS_PRIVATE_KEY variables appear in balenaCloud for the device. After a successful DELETE, those variables disappear.