cb-gcp-iot-provision v0.1.1

Google Cloud Function for ClearBlade IoT Device Provisioning

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

Device Environment Variables

Once the Cloud function has provisioned the device with ClearBlade IoT on GCP, it sets balena device environment variables as described below, which allow the device to connect to ClearBlade IoT Core. Some aspects of the variable values are common across devices, and are collected from the Cloud Function deployment.

Setup and Testing

ClearBlade and GCP setup

The Cloud Function interacts with ClearBlade IoT Core on Google Cloud via ClearBlade SDK code operating with GCP and ClearBlade credentials. ClearBlade IoT Core is a separate service built on top of Google Cloud.

First you create a GCP project and service account as the foundation for ClearBlade IoT to work with GCP. Then you create a ClearBlade IoT Core project, device registry, and service account. These resources are required to register devices and send messages to ClearBlade IoT Core. ClearBlade then forwards device messages on to Google Cloud's Pub/Sub service.

The links below provide instructions to setup these resources.

Workspace setup

Clone this repo

$ git clone https://github.com/balena-io-examples/cb-gcp-iot-provision

The sections below show how to test the Cloud Function on a local test server and deploy to Cloud Functions. In either case you must provide the environment variables in the table below as instructed for the test/deployment.

HTTP API

The HTTP endpoint expects a request containing a JSON body with the attributes below. Use POST to add a device to the cloud registry, DELETE to remove.

Test locally

The Google Functions Framework is a convenient tool for local testing. First, start a local HTTP server (docs reference) using a script like below in the directory containing the clone of the cb-gcp-iot-provision project.

export BALENA_API_KEY=<...>
... <other environment variables from table above>
export CB_SERVICE_ACCOUNT=<...>

npx @google-cloud/functions-framework --target=provision

Next, use curl to send an HTTP request to the local server to provision a device. See the HTTP API section above for body contents.

curl -X POST http://localhost:8080 -H "Content-Type:application/json" \
   -d '{ "uuid": "<device-uuid>", "balena_service": "<service-name>" }'

After a successful POST, you should see the device appear in your IoT Core registry and GCP_CLIENT_PATH, GCP_DATA_TOPIC_ROOT, GCP_PRIVATE_KEY, and GCP_PROJECT_ID variables appear in balenaCloud for the device. After a successful DELETE, those variables disappear.

Deploy

To deploy to Cloud Functions, use the command below. See the command documentation for the format of yaml-file, which contains the variables from the table in the Workspace setup section above.

gcloud functions deploy provision --runtime=nodejs16 --trigger-http \
   --env-vars-file=<yaml-file> --allow-unauthenticated \
   --service-account=<name>@<xxxx>.iam.gserviceaccount.com

The result is a Cloud Function like below. Notice the TRIGGER tab, which provides the URL for the function.

Test the Cloud Function

To test the function, use a command like below, where the URL is from the TRIGGER tab in the console. See the HTTP API section above for body contents.

curl -X POST https://<region>-<projectID>.cloudfunctions.net/provision \
   -H "Content-Type:application/json" \
   -d '{ "uuid": "<device-uuid>", "balena_service": "<service-name>" }'

After a successful POST, you should see the device appear in your IoT Core registry and GCP_CLIENT_PATH, GCP_DATA_TOPIC_ROOT, GCP_PRIVATE_KEY, and GCP_PROJECT_ID variables appear in balenaCloud for the device. After a successful DELETE, those variables disappear.