Install and provision Azure IoT Edge for Linux on a Windows device

Applies to: yes icon IoT Edge 1.1

The Azure IoT Edge runtime is what turns a device into an IoT Edge device. The runtime can be deployed on devices from PC class to industrial servers. Once a device is configured with the IoT Edge runtime, you can start deploying business logic to it from the cloud. To learn more, see Understand the Azure IoT Edge runtime and its architecture.

Azure IoT Edge for Linux on Windows allows you to install IoT Edge on Linux virtual machines that run on Windows devices. The Linux version of Azure IoT Edge and any Linux modules deployed with it run on the virtual machine. From there, Windows applications and code and the IoT Edge runtime and modules can freely interact with each other.

This article lists the steps to set up IoT Edge on a Windows device. These steps deploy a Linux virtual machine that contains the IoT Edge runtime to run on your Windows device, then provision the device with its IoT Hub device identity.

Note

IoT Edge for Linux on Windows is the recommended experience for using Azure IoT Edge in a Windows environment. However, Windows containers are still available. If you prefer to use Windows containers, see Install and manage Azure IoT Edge with Windows containers.

Prerequisites

  • An Azure account with a valid subscription. If you don't have an Azure subscription, create a free account before you begin.

  • A free or standard tier IoT Hub in Azure.

  • A Windows device with the following minimum system requirements:

    • Windows 10 Version 1809 or later; build 17763 or later
    • Professional, Enterprise, or Server editions
    • Minimum Free Memory: 1 GB
    • Minimum Free Disk Space: 10 GB
    • Virtualization support
    • Networking support
      • Windows Server does not come with a default switch. Before you can deploy EFLOW to a Windows Server device, you need to create a virtual switch. For more information, see Create virtual switch for Linux on Windows.
      • Windows Desktop versions come with a default switch that can be used for EFLOW installation. If needed, you can create your own custom virtual switch.
  • If you want to install and manage IoT Edge device using Windows Admin Center, make sure you have access to Windows Admin Center and have the Azure IoT Edge extension installed:

    1. Download and run the Windows Admin Center installer. Follow the install wizard prompts to install Windows Admin Center.

    2. Once installed, use a supported browser to open Windows Admin Center. Supported browsers include Microsoft Edge (Windows 10, version 1709 or later), Google Chrome, and Microsoft Edge Insider.

    3. On the first use of Windows Admin Center, you will be prompted to select a certificate to use. Select Windows Admin Center Client as your certificate.

    4. Install the Azure IoT Edge extension. Select the gear icon in the top right of the Windows Admin Center dashboard.

      Select the gear icon in the top right of the dashboard to access the settings.

    5. On the Settings menu, under Gateway, select Extensions.

    6. On the Available extensions tab, find Azure IoT Edge in the list of extensions. Choose it, and select the Install prompt above the list of extensions.

    7. After the installation completes, you should see Azure IoT Edge in the list of installed extensions on the Installed extensions tab.

  • If you want to use GPU-accelerated Linux modules in your Azure IoT Edge for Linux on Windows deployment, there are several configuration options to consider. You will need to install the correct drivers depending on your GPU architecture, and you may need access to a Windows Insider Program build. To determine your configuration needs and satisfy these prerequisites, see GPU acceleration for Azure IoT Edge for Linux on Windows.

Choose your provisioning method

Azure IoT Edge for Linux on Windows supports the following provisioning methods:

Create a new deployment

Deploy Azure IoT Edge for Linux on Windows on your target device.

Install IoT Edge for Linux on Windows onto your target device if you have not already.

Note

The following PowerShell process outlines how to deploy IoT Edge for Linux on Windows onto the local device. To deploy to a remote target device using PowerShell, you can use Remote PowerShell to establish a connection to a remote device and run these commands remotely on that device.

  1. In an elevated PowerShell session, run each of the following commands to download IoT Edge for Linux on Windows.

    $msiPath = $([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))
    $ProgressPreference = 'SilentlyContinue'
    Invoke-WebRequest "https://aka.ms/AzEflowMSI" -OutFile $msiPath
    
  2. Install IoT Edge for Linux on Windows on your device.

    Start-Process -Wait msiexec -ArgumentList "/i","$([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))","/qn"
    

    You can specify custom IoT Edge for Linux on Windows installation and VHDX directories by adding INSTALLDIR="<FULLY_QUALIFIED_PATH>" and VHDXDIR="<FULLY_QUALIFIED_PATH>" parameters to the install command.

  3. Set the execution policy on the target device to AllSigned if it is not already. You can check the current execution policy in an elevated PowerShell prompt using:

    Get-ExecutionPolicy -List
    

    If the execution policy of local machine is not AllSigned, you can set the execution policy using:

    Set-ExecutionPolicy -ExecutionPolicy AllSigned -Force
    
  4. Create the IoT Edge for Linux on Windows deployment.

    Deploy-Eflow
    

    Tip

    By default, the Deploy-Eflow command creates your Linux virtual machine with 1 GB of RAM, 1 vCPU core, and 16 GB of disk space. However, the resources your VM needs are highly dependent on the workloads you deploy. If your VM does not have sufficient memory to support your workloads, it will fail to start.

    You can customize the virtual machine's available resources using the Deploy-Eflow command's optional parameters.

    For example, the command below creates a virtual machine with 4 vCPU cores, 4 GB of RAM, and 20 GB of disk space:

    Deploy-Eflow -cpuCount 4 -memoryInMB 4096 -vmDiskSize 20
    

    For information about all the optional parameters available, see PowerShell functions for IoT Edge for Linux on Windows.

    You can assign a GPU to your deployment to enable GPU-accelerated Linux modules. To gain access to these features, you will need to install the prerequisites detailed in GPU acceleration for Azure IoT Edge for Linux on Windows.

    To use a GPU passthrough, you will need add the gpuName, gpuPassthroughType, and gpuCount parameters to your Deploy-Eflow command. For information about all the optional parameters available, see PowerShell functions for IoT Edge for Linux on Windows.

    Warning

    Enabling hardware device passthrough may increase security risks. Microsoft recommends a device mitigation driver from your GPU's vendor, when applicable. For more information, see Deploy graphics devices using discrete device assignment.

  5. Enter 'Y' to accept the license terms.

  6. Enter 'O' or 'R' to toggle Optional diagnostic data on or off, depending on your preference.

  7. Once the deployment is complete, the PowerShell window reports Deployment successful.

    A successful deployment will say 'Deployment successful' at the end of the messages

Once your deployment is complete, you are ready to provision your device.

Provision your device

Choose a method for provisioning your device and follow the instructions in the appropriate section. This article provides the steps for manually provisioning your device with either symmetric keys or X.509 certificates. If you are using automatic provisioning with DPS, follow the appropriate links to complete provisioning.

You can use the Windows Admin Center or an elevated PowerShell session to provision your devices.

Manual provisioning using the connection string

This section covers provisioning your device manually using your IoT Edge device's connection string.

If you haven't already, follow the steps in Register an IoT Edge device in IoT Hub to register your device and retrieve its connection string.

Run the following command in an elevated PowerShell session on your target device. Replace the placeholder text with your own values.

Provision-EflowVm -provisioningType ManualConnectionString -devConnString "<CONNECTION_STRING_HERE>"‚Äč

For more information about the Provision-EflowVM command, see PowerShell functions for IoT Edge for Linux on Windows.

Manual provisioning using X.509 certificates

This section covers provisioning your device manually using X.509 certificates on your IoT Edge device.

If you haven't already, follow the steps in Register an IoT Edge device in IoT Hub to prepare the necessary certificates and register your device.

Have the device identity certificate and its matching private key ready on your target device. Know the absolute path to both files.

Run the following command in an elevated PowerShell session on your target device. Replace the placeholder text with your own values.

Provision-EflowVm -provisioningType ManualX509 -iotHubHostname "<HUB HOSTNAME>" -deviceId "<DEVICE ID>" -identityCertPath "<ABSOLUTE PATH TO IDENTITY CERT>" -identityPrivKeyPath "<ABSOLUTE PATH TO PRIVATE KEY>"

For more information about the Provision-EflowVM command, see PowerShell functions for IoT Edge for Linux on Windows.

Verify successful configuration

Verify that IoT Edge for Linux on Windows was successfully installed and configured on your IoT Edge device.

Important

If you're using IoT Edge for Linux on Windows PowerShell public functions, be sure to set the execution policy on the target device to AllSigned. Ensure that all prerequisites for PowerShell functions for IoT Edge for Linux on Windows are met.

  1. Log in to your IoT Edge for Linux on Windows virtual machine using the following command in your PowerShell session:

    Connect-EflowVm
    

    Note

    The only account allowed to SSH to the virtual machine is the user that created it.

  2. Once you are logged in, you can check the list of running IoT Edge modules using the following Linux command:

    sudo iotedge list
    
  3. If you need to troubleshoot the IoT Edge service, use the following Linux commands.

    1. If you need to troubleshoot the service, retrieve the service logs.

      sudo journalctl -u iotedge
      
    2. Use the check tool to verify configuration and connection status of the device.

      sudo iotedge check
      

When you create a new IoT Edge device, it will display the status code 417 -- The device's deployment configuration is not set in the Azure portal. This status is normal, and means that the device is ready to receive a module deployment.

Next steps