Connect an IoT Edge device to IoT Hub on Azure Stack Hub

Important

IoT Hub on Azure Stack Hub is currently in preview, and is provided free during the preview period.

This article shows you how to connect a virtual IoT Edge device to IoT Hub running on Azure Stack Hub. You can use the same general process to connect a physical device to your IoT Hub.

Prerequisites

Complete the following prerequisites before continuing:

Overview

Here's a summary of the steps you'll complete, to connect an IoT Edge device to your IoT Hub on Azure Stack Hub:

  1. Create IoT Hub and Linux VM resources on your Azure Stack Hub instance. The Linux VM will serve as a virtual IoT Edge device.
  2. Configure the certificates required for the IoT Edge device. The number of steps required will depend on the type of CA that issued your IoT Hub root CA certificate.
  3. Configure the software and services required for the IoT Edge device.
  4. Test the IoT Edge device to make sure it's working properly and communicating with your IoT Hub.

Before running the script in each section, be sure to update the script placeholders to match your environment's configuration. Make note of the values you use, as you'll need them in later sections:

Placeholder Example Description
<DEVICE-CA-CERT-NAME> edged1cert The name you give the IoT Edge device CA certificate.
<IOT-HUB-HOSTNAME> test-hub-1.mgmtiothub.region.mydomain.com Your IoT Hub host name.
<IOT-HUB-ROOT-CA> root.cer The filename you give to the exported IoT Hub root CA (if using a private CA).
<DATA-DIR> /home/edgeadmin/edged1 The full path to the data directory you create on the Linux VM.
<USER-ACCOUNT> edgeadmin The account you use to sign in to the Linux VM.

Create Azure Stack Hub resources

First you create the necessary Azure Stack Hub resources, including an IoT Hub and a Linux VM. You'll use the Azure Stack Hub user portal to create these resources.

Create an IoT Hub resource

  1. Sign in to the Azure Stack Hub user portal from a computer that has access to your Azure Stack Hub instance.

  2. If you haven't created one already, follow the instructions in the Create an IoT Hub section of Create an IoT hub using the Azure portal, to create an IoT Hub resource.

    Important

    Be sure to use the Azure Stack Hub user portal when following the steps in the article, and NOT the Azure portal. Also note that some screenshots and instructions may be slightly different, as not all Azure features are available on Azure Stack Hub.

Deploy and configure a Linux VM

In this section, you deploy a new Linux VM, which will serve as the virtual IoT Edge device:

  1. Using the Create a Linux server VM by using the Azure Stack Hub portal quick start, install a Linux VM on your Azure Stack Hub instance. Be sure to enable port SSH (22) on the Select public inbound ports property, when you get to the Settings page.

    Note

    You only need to complete the first 5 sections, up through Connect to the VM, as you won't need the NGINX web server.

  2. After you've created and connected to the VM using PuTTY, create a data subdirectory off of your user account home directory, for example:

    mkdir edged1
    
  3. Set up the certificate generation tool using one of the following methods. Either will download files from the IoT Edge GitHub repository, required later for generating device certificates:

    Use cURL script:

    # Navigate to the edge device data directory
    cd <DATA-DIR>
    
    # Download certGen.sh script file, and openssl_root_ca.cnf config file
    curl -Lo certGen.sh https://raw.githubusercontent.com/Azure/iotedge/master/tools/CACertificates/certGen.sh
    curl -Lo openssl_root_ca.cnf https://raw.githubusercontent.com/Azure/iotedge/master/tools/CACertificates/openssl_root_ca.cnf
    

    Use Git to clone the repository:

    # Navigate to the home directory
    cd /home/<USER-ACCOUNT>
    
    # Clone the iotedge repo, which contains the certGen.sh script file and openssl_root_ca.cnf config file
    git clone https://github.com/Azure/iotedge.git
    
    # Navigate to the edge device data directory
    cd <DATA-DIR>
    
    # Copy certGen.sh and openssl_root_ca.cnf into your working directory
    cp /home/<USER-ACCOUNT>/iotedge/tools/CACertificates/*.cnf .
    cp /home/<USER-ACCOUNT>/iotedge/tools/CACertificates/certGen.sh .
    

Configure IoT Edge device certificates

In this section, you'll complete the VM certificate configuration required by the virtual IoT Edge device.

Your IoT Hub service and the IoT Edge device are secured with X509 certificates. Both must use a root CA certificate issued by the same CA. Select the appropriate tab below to complete certificate configuration, based on the root CA type being used by your IoT Hub.

Create a device root CA certificate

Create the device root CA certificate and key files required for your device:

  1. Return to the Bash command prompt in your PuTTY session.

  2. Navigate to the data directory where you placed the certificate generation scripts in the previous section.

  3. Run the following command:

    ./certGen.sh create_root_and_intermediate
    
  4. The device root CA certificate is stored in the following file: <DATA-DIR>/certs/azure-iot-test-only.root.ca.cert.pem.

Create the IoT Edge device CA certificate

Production IoT Edge devices need a device CA certificate, referenced from the config.yaml file. The device CA certificate is responsible for creating certificates for the modules running on the device. It's also necessary for gateway scenarios, as the device CA certificate is use by the IoT Edge device to verify its identity to downstream devices.

To create the IoT Edge device CA certificate files:

  1. Return to the Bash command prompt in your PuTTY session.

  2. Run the following script, which creates several device CA certificate and key files:

    # Navigate to data directory
    cd <DATA-DIR>
    
    # Generate IoT Edge device CA certificate 
    ./certGen.sh create_edge_device_ca_certificate <DEVICE-CA-CERT-NAME>
    
  3. The following certificate and key pair files are referenced later in the config.yaml file:

    <DATA-DIR>/certs/iot-edge-device-ca-<DEVICE-CA-CERT-NAME>-full-chain.cert.pem
    <DATA-DIR>/private/iot-edge-device-ca-<DEVICE-CA-CERT-NAME>.key.pem

Configure IoT Edge device software and services

In this section, you'll complete the IoT Hub and VM configuration required by the virtual IoT Edge device.

Install IoT Edge and container runtimes on the VM

  1. Return to the VM PuTTY session and run the following script to register the Microsoft key and software repository feed:

    # Navigate to the home directory
    cd /home/<USER-ACCOUNT>
    
    # Install the repository configuration. 
    curl https://packages.microsoft.com/config/ubuntu/16.04/multiarch/prod.list > ./microsoft-prod.list
    
    # Copy the generated list.
    sudo cp ./microsoft-prod.list /etc/apt/sources.list.d/
    
    # Install Microsoft GPG public key.
    curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
    sudo cp ./microsoft.gpg /etc/apt/trusted.gpg.d/
    
  2. Install the container runtime:

    sudo apt-get update
    sudo apt-get install moby-engine moby-cli
    
  3. Install the Azure IoT Edge security daemon:

    sudo apt-get update
    sudo apt-get install iotedge
    

Note

You can ignore the IMPORTANT: Please update the configuration file notice for now, as you'll update it in a later section.

Create an IoT Edge device in IoT Hub

  1. Return to the Azure Stack Hub user portal, and navigate to the IoT Hub service.

  2. Select your IoT Hub resource, then select the IoT Edge page, then Add an IoT Edge device.

    IoT Hub resource

  3. On the Create a device page, enter the Device ID, for example "edged1".

  4. When finished, select Save.

    IoT Edge - create a device

  5. When the portal returns to the IoT Edge page, select your new device from the devices list.

    IoT Edge - view devices

  6. On the device details page, use the Copy button at the right of Primary Connection String to copy the string to the clipboard. You'll use the connection string in the next section.

    IoT Edge - device details

Configure the virtual IoT Edge device on the VM

  1. Return to the VM PuTTY session. Using Bash, open the configuration file in Nano on the virtual IoT Edge device:

    sudo nano /etc/iotedge/config.yaml
    
  2. Locate the provisioning property under comment # Manual provisioning configuration using a connection string, in the Provisioning mode and settings section. Update the IoT Edge device connection string, by replacing the <ADD DEVICE CONNECTION STRING HERE> placeholder with the connection string you copied to the clipboard in the previous section:

    Note

    To paste clipboard contents into Nano, press and hold the Shift key and click the right mouse button. Or, press the Shift and Insert keys simultaneously. If the paste operation shifts your cursor to the rightmost end of the connection string, hit the Home key to return to the leftmost end.

    # Manual provisioning configuration using a connection string
    provisioning:
      source: "manual"
      device_connection_string: "<ADD DEVICE CONNECTION STRING HERE>"
    
  3. Locate and uncomment the certificates property in the Certificate settings section. Uncomment and replace the file URIs with the paths to the three certificates you created earlier, for example:

    certificates:
      device_ca_cert: "<DATA-DIR>/certs/iot-edge-device-ca-<DEVICE-CA-CERT-NAME>-full-chain.cert.pem"
      device_ca_pk: "<DATA-DIR>/private/iot-edge-device-ca-<DEVICE-CA-CERT-NAME>.key.pem"
      trusted_ca_certs: "<DATA-DIR>/certs/azure-iot-test-only.root.ca.cert.pem"
    
  4. When completed, the provisioning and certificates properties should look similar to the following responses:

    Nano editor - provisioning property

    Nano editor - certificates property

  5. Save and close the file using CTRL + X, then Y, then Enter.

  6. After you return to Bash, restart the daemon:

    sudo systemctl restart iotedge
    

Verify a successful installation

  1. Check the status of the IoT Edge daemon:

    systemctl status iotedge
    
  2. You should see that the IoT Edge service is running and "active", with a response similar to the following. If so, you can jump ahead to step #4.

    IoT Edge service running successfully

  3. If the IoT Edge service failed:

    • You'll see a response similar showing "failed", similar to the following example: IoT Edge service failed

    • To troubleshoot, you can:

      • Examine the daemon logs:

        journalctl -u iotedge --no-pager --no-full
        
      • Run the troubleshooting tool to check for the most common configuration and networking errors. In this example, a malformed /etc/iotedge/config.yaml file is detected:

        sudo iotedge check
        

        IoT Edge service check

        Note

        The $edgeHub system module is optional, and isn't deployed to the device until you deploy your first IoT Edge module. As such, iotedge check may return an error indicating that $edgeHub cannot bind to ports during a host connectivity check. This error can be ignored if $edgeHub is not required in your deployment.

    • If you find that you have a malformed .YML file as in the example above, simply:

  4. Once you determine that the IoT Edge service started successfully, list the running modules. You should see the service edgeAgent with a status of running:

    sudo iotedge list
    

Clean up resources

If you'll no longer be using them, return to the Azure Stack Hub user portal and delete the VM and IoT Hub resources you created earlier.

Next steps

The following are supplemental resources: