Connect an IoT Edge device to IoT Hub on Azure Stack Hub
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.
Complete the following prerequisites before continuing:
Work with your administrator to install the IoT Hub on Azure Stack Hub resource provider. The installation steps also cover the creation of an offer that includes the IoT Hub service.
Once an offer is available, your administrator can create or update your Azure Stack Hub subscription to include IoT Hub. Alternatively, you can subscribe to the new offer and create your own subscription.
It's helpful to have a basic understanding of Public Key Encryption (PKI). Specifically, how a Certificate Authority (CA) and X509 certificates are used to build a chain of trust. This trust allows network nodes to securely authenticate and communicate with each other, such as your IoT Hub service and IoT Edge device.
Here's a summary of the steps you'll complete, to connect an IoT Edge device to your IoT Hub on Azure Stack Hub:
- Create IoT Hub and Linux VM resources on your Azure Stack Hub instance. The Linux VM will serve as a virtual IoT Edge device.
- 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.
- Configure the software and services required for the IoT Edge device.
- 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:
||The name you give the IoT Edge device CA certificate.|
||Your IoT Hub host name.|
||The filename you give to the exported IoT Hub root CA (if using a private CA).|
||The full path to the data directory you create on the Linux VM.|
||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
Sign in to the Azure Stack Hub user portal from a computer that has access to your Azure Stack Hub instance.
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.
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:
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.
You only need to complete the first 5 sections, up through Connect to the VM, as you won't need the NGINX web server.
After you've created and connected to the VM using PuTTY, create a data subdirectory off of your user account home directory, for example:
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:
Return to the Bash command prompt in your PuTTY session.
Navigate to the data directory where you placed the certificate generation scripts in the previous section.
Run the following command:
The device root CA certificate is stored in the following file:
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:
Return to the Bash command prompt in your PuTTY session.
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>
The following certificate and key pair files are referenced later in the config.yaml file:
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
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/
Install the container runtime:
sudo apt-get update sudo apt-get install moby-engine moby-cli
Install the Azure IoT Edge security daemon:
sudo apt-get update sudo apt-get install iotedge
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
Return to the Azure Stack Hub user portal, and navigate to the IoT Hub service.
Select your IoT Hub resource, then select the IoT Edge page, then Add an IoT Edge device.
On the Create a device page, enter the Device ID, for example "edged1".
When finished, select Save.
When the portal returns to the IoT Edge page, select your new device from the devices list.
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.
Configure the virtual IoT Edge device on the VM
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
provisioningproperty 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:
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>"
Locate and uncomment the
certificatesproperty 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"
When completed, the
certificatesproperties should look similar to the following responses:
Save and close the file using CTRL + X, then Y, then Enter.
After you return to Bash, restart the daemon:
sudo systemctl restart iotedge
Verify a successful installation
Check the status of the IoT Edge daemon:
systemctl status iotedge
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.
If the 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.yamlfile is detected:
sudo iotedge check
$edgeHubsystem module is optional, and isn't deployed to the device until you deploy your first IoT Edge module. As such,
iotedge checkmay return an error indicating that
$edgeHubcannot bind to ports during a host connectivity check. This error can be ignored if
$edgeHubis not required in your deployment.
If you find that you have a malformed .YML file as in the example above, simply:
Once you determine that the IoT Edge service started successfully, list the running modules. You should see the service
edgeAgentwith a status of
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.
The following are supplemental resources: