Migrating IoT Edge solutions to GA

This release adds tons of new features for those already using public preview bits. Customers who have never used Azure IoT Edge can start with the Linux or Windows quickstarts. Those who have started projects on preview bits should upgrade to the latest bits and integrate breaking changes.  Details on both of these processes are below.

Upgrade to the latest bits

Uninstall preview bits

Use iotedgectl to uninstall the preview bits from your Edge device by running the following command. You can skip this step if you are installing GA bits on a device or VM that has never run preview bits.

iotedgectl uninstall

Delete preview runtime container images

Use “docker rmi” to remove the container images for preview versions of Edge Agent and Edge Hub from your Edge device. You can skip this step if you are installing GA bits on a device or VM that has never run preview bits.

Remove references to preview container images in deployments

The IoT Edge Security Daemon includes functionality to allow the user to specify which versions of the Edge Agent and Edge Hub are used by an Edge device. This allows you to control when bits on your device get updated. The version of these runtime components are specified in your deployment. Deployments created during preview include references to preview container images. You must change them to reference GA container images, ensuring that the Security Daemon does not downgrade your machine to preview bits. An example deployment snippet is below.

"systemModules": {
     "edgeAgent": {
         "type": "docker",
         "settings": {
             "image": "microsoft/azureiotedge-agent:1.0-previewmcr.microsoft.com/azureiotedge-agent:1.0",
             "createOptions": "{}"
         }
     },
     "edgeHub": {
         "type": "docker",
         "settings": {
             "image": "microsoft/azureiotedge-hub:1.0-previewmcr.microsoft.com/azureiotedge-hub:1.0",
             "createOptions": "{}"
         },
         "status": "running",
         "restartPolicy": "always"
     }
},

Install GA bits

The quickstarts for Linux and Windows walk you through setting up an IoT Edge device with these new infrastructural components. You will notice that the quickstarts start by installing a component introduced with GA called the IoT Edge Security Daemon. This is part of the Edge Security Manager, a set of components that help us secure the edge.

The IoT Edge Security Daemon starts each time an Edge device boots and initiates the IoT Edge Agent. This means that iotedgectl is no longer needed when working with IoT Edge devices.

Hsmlib is another new component which is part of the IoT Edge Security Manager. Different versions of hsmlib integrate with device specific hardware and allow the IoT Edge Security Daemon to perform cryptographic functions. Advanced types of hardware enable IoT Edge to provide innovative security and functionality. For example, devices with a hardware security module (eg. TPM) can be provisioned via the Device Provisioning Service.

A default version of hsmlib is installed along with the IoT Edge Security Daemon. This version of hsmlib supports our standard security promise which uses the Edge device’s file system for storage of secrets as well as our secure enclave promise using TPM at /tpm0.

Integrate breaking changes

The vast majority of feature additions have been done in a backwards compatible manner making it easy to migrate your projects on to GA bits. We’ve learned an incredible amount from having the product in public preview and are making a few small breaking changes based on user feedback. These changes are as small as possible while still delivering usability improvements to the product.

Client SDK split

Change

The DeviceClient object, used to write IoT Edge modules, will split into two objects: DeviceClient and ModuleClient.

Impact

Small code change. You must change the class name for all DeviceClient objects in your module code to ModuleClient. We've also introduced a factory class for creating ModuleClients. This helper class hides the details of correctly integrating with the IoT Edge Security Daemon.

Before

DeviceClient deviceClient = DeviceClient.CreateFromConnectionString(connStr, transportSettings);

After

ModuleClient moduleClient =
ModuleClient.CreateFromEnvironment(transportSettings);

Additionally, the API surface of the ModuleClient will be reduced to only the functionality that is currently supported for modules. This should not affect any existing module code as those APIs do not work.

Reason for change

The functionality available to devices and modules is slightly different. For example:

◈ Modules can read/write from inputs/outputs while devices can only write to IoT Hub.
◈ Devices can receive C2D messages while modules cannot.
◈ Devices can perform FileUpload while modules cannot.
◈ Separating the clients cleanly delineates the functionality available to devices and modules.

Direct method invocation

Change

The ServiceClient class will no longer allow module identities to invoke direct methods. This functionality has been moved to the ModuleClient class as part of the Client SDK split detailed above.

Impact

You must use the ModuleClient class to invoke methods for module identities instead of the ServiceClient.

Before

// assumes the use of a module connection
ServiceClient serviceClient = ServiceClient.CreateFromConnectionString(connStr, transportSettings);
string.serviceClient.InvokeDeviceMethodAsync("DeviceId", "ModuleId", new CloudToDeviceMethod("MethodName"));

After

ModuleClient moduleClient = ModuleClient.CreateFromEnvironment(transportSettings);
moduleClient.InvokeMethodAsync("DeviceId", "ModuleId", new DirectMethodRequest("MethodName")) ;

Reason for change

Invoking a method is an action users expect to be able to do with the ModuleClient, instead of instantiating a second object. Adding method invocation to ModuleClient reduces the size of module code as developers no longer need to include the ServiceClient in their code.

Configure port on which Edge Hub listens

Change

Edge Hub used to listen for connections from downstream devices on ports 8883 and 443. Now we require developers to specify on which host ports it uses for these connections.

Impact

You must set port forwarding info on Edge Hub when manually creating a deployment's JSON. The below JSON configures Edge Hub to work as before (listen on ports 8883 and 443).

"{\"HostConfig\":{\"PortBindings\":{\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"

You do not need to make any changes if you're creating a deployment through the Azure portal or with the VS Code extension. These tools will automatically set up port forwarding options to make Edge Hub listen for connections on 8883 and 443.

Reason for change

Some customers may want an Edge device to listen for downsteam device connections on a port other than 443 or 8883 as those ports could be used for a different purpose. For example, customers may want to run a HTTPS server on 443.