Install the Azure IoT Edge runtime on Windows

The Azure IoT Edge runtime is what turns a device into an IoT Edge device. The runtime can be deployed on devices as small as a Raspberry Pi or as large as an industrial server. Once a device is configured with the IoT Edge runtime, you can start deploying business logic to it from the cloud.

To learn more about the IoT Edge runtime, see Understand the Azure IoT Edge runtime and its architecture.

This article lists the steps to install the Azure IoT Edge runtime on your Windows x64 (AMD/Intel) system using Windows containers.

Note

A known Windows operating system issue prevents transition to sleep and hibernate power states when IoT Edge modules (process-isolated Windows Nano Server containers) are running. This issue impacts battery life on the device.

As a workaround, use the command Stop-Service iotedge to stop any running IoT Edge modules before using these power states.

Using Linux containers on Windows systems is not a recommended or supported production configuration for Azure IoT Edge. However, it can be used for development and testing purposes. To learn more, see Use IoT Edge on Windows to run Linux containers.

For information about what's included in the latest version of IoT Edge, see Azure IoT Edge releases.

Prerequisites

Use this section to review whether your Windows device can support IoT Edge, and to prepare it for a container engine before installation.

Supported Windows versions

For development and test scenarios, Azure IoT Edge with Windows containers can be installed on any version of Windows 10 or Windows Server 2019 (build 17763) that supports the containers feature. For information about which operating systems are currently supported for production scenarios, see Azure IoT Edge supported systems.

Prepare for a container engine

Azure IoT Edge relies on a OCI-compatible container engine. For production scenarios, use the Moby engine included in the installation script to run Windows containers on your Windows device.

Install IoT Edge on a new device

Note

Azure IoT Edge software packages are subject to the license terms located in the packages (in the LICENSE directory). Please read the license terms prior to using the package. Your installation and use of the package constitutes your acceptance of these terms. If you do not agree with the license terms, do not use the package.

A PowerShell script downloads and installs the Azure IoT Edge security daemon. The security daemon then starts the first of two runtime modules, the IoT Edge agent, which enables remote deployments of other modules.

When you install the IoT Edge runtime for the first time on a device, you need to provision the device with an identity from an IoT hub. A single IoT Edge device can be provisioned manually using a device connection string provided by IoT Hub. Or, you can use the Device Provisioning Service (DPS) to automatically provision devices, which is helpful when you have many devices to set up. Depending on your provisioning choice, choose the appropriate installation script.

The following sections describe the common use cases and parameters for the IoT Edge installation script on a new device.

Option 1: Install and manually provision

In this first option, you provide a device connection string generated by IoT Hub to provision the device.

This example demonstrates a manual installation with Windows containers:

  1. If you haven't already, register a new IoT Edge device and retrieve the device connection string. Copy the connection string to use later in this section. You can complete this step using the following tools:

  2. Run PowerShell as an administrator.

    Note

    Use an AMD64 session of PowerShell to install IoT Edge, not PowerShell (x86). If you're not sure which session type you're using, run the following command:

    (Get-Process -Id $PID).StartInfo.EnvironmentVariables["PROCESSOR_ARCHITECTURE"]
    
  3. The Deploy-IoTEdge command checks that your Windows machine is on a supported version, turns on the containers feature, and then downloads the moby runtime and the IoT Edge runtime. The command defaults to using Windows containers.

    . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
    Deploy-IoTEdge
    
  4. At this point, IoT Core devices may restart automatically. Other Windows 10 or Windows Server devices may prompt you to restart. If so, restart your device now. Once your device is ready, run PowerShell as an administrator again.

  5. The Initialize-IoTEdge command configures the IoT Edge runtime on your machine. The command defaults to manual provisioning with Windows containers.

    . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
    Initialize-IoTEdge
    
  6. When prompted, provide the device connection string that you retrieved in step 1. The device connection string associates the physical device with a device ID in IoT Hub.

    The device connection string takes the following format, and should not include quotation marks: HostName={IoT hub name}.azure-devices.net;DeviceId={device name};SharedAccessKey={key}

  7. Use the steps in Verify successful installation to check the status of IoT Edge on your device.

When you install and provision a device manually, you can use additional parameters to modify the installation including:

  • Direct traffic to go through a proxy server
  • Point the installer to an offline directory
  • Declare a specific agent container image, and provide credentials if it's in a private registry

For more information about these installation options, skip ahead to learn about all installation parameters.

Option 2: Install and automatically provision

In this second option, you provision the device using the IoT Hub Device Provisioning Service. Provide the Scope ID from a Device Provisioning Service instance, and the Registration ID from your device. Additional values might be required according to your attestation mechanism when provisioning with DPS, such as when using symmetric keys.

The following example demonstrates an automatic installation with Windows containers and TPM attestation:

  1. Follow the steps in Create and provision a simulated TPM IoT Edge device on Windows to set up the Device Provisioning Service and retrieve its Scope ID, simulate a TPM device and retrieve its Registration ID, then create an individual enrollment. Once your device is registered in your IoT hub, continue with these installation steps.

    Tip

    Keep the window that's running the TPM simulator open during your installation and testing.

  2. Run PowerShell as an administrator.

    Note

    Use an AMD64 session of PowerShell to install IoT Edge, not PowerShell (x86). If you're not sure which session type you're using, run the following command:

    (Get-Process -Id $PID).StartInfo.EnvironmentVariables["PROCESSOR_ARCHITECTURE"]
    
  3. The Deploy-IoTEdge command checks that your Windows machine is on a supported version, turns on the containers feature, and then downloads the moby runtime and the IoT Edge runtime. The command defaults to using Windows containers.

    . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
    Deploy-IoTEdge
    
  4. At this point, IoT Core devices may restart automatically. Other Windows 10 or Windows Server devices may prompt you to restart. If so, restart your device now. Once your device is ready, run PowerShell as an administrator again.

  5. The Initialize-IoTEdge command configures the IoT Edge runtime on your machine. The command defaults to manual provisioning with Windows containers. Use the -Dps flag to use the Device Provisioning Service instead of manual provisioning.

    Using the Initialize-IoTEdge command to use DPS with TPM attestation:

    . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
    Initialize-IoTEdge -Dps
    

    Using the Initialize-IoTEdge command to use DPS with symmetric key attestation. Replace {symmetric key} with a device key.

    . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
    Initialize-IoTEdge -Dps -SymmetricKey {symmetric key}
    
  6. When prompted, provide the scope ID from your Device Provisioning Service and the registration ID from your device, both of which you should have retrieved in step 1.

  7. Use the steps in Verify successful installation to check the status of IoT Edge on your device.

When you install and provision a device manually, you can use additional parameters to modify the installation including:

  • Direct traffic to go through a proxy server
  • Point the installer to an offline directory
  • Declare a specific agent container image, and provide credentials if it's in a private registry

For more information about these installation options, continue reading this article or skip to learn about All installation parameters.

Offline installation

During installation two files are downloaded:

  • Microsoft Azure IoT Edge cab, which contains the IoT Edge security daemon (iotedged), Moby container engine, and Moby CLI.
  • Visual C++ redistributable package (VC runtime) msi

You can download one or both of these files ahead of time to the device, then point the installation script at the directory that contains the files. The installer checks the directory first, and then only downloads components that aren't found. If all the files are available offline, you can install with no internet connection. You can also use this feature to install a specific version of the components.

For the latest IoT Edge installation files along with previous versions, see Azure IoT Edge releases.

To install with offline components, use the -OfflineInstallationPath parameter as part of the Deploy-IoTEdge command and provide the absolute path to the file directory. For example,

. {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
Deploy-IoTEdge -OfflineInstallationPath C:\Downloads\iotedgeoffline

You can also use the offline installation path parameter with the Update-IoTEdge command, introduced later in this article.

Verify successful installation

Check the status of the IoT Edge service. It should be listed as running.

Get-Service iotedge

Examine service logs from the last 5 minutes. If you just finished installing the IoT Edge runtime, you may see a list of errors from the time between running Deploy-IoTEdge and Initialize-IoTEdge. These errors are expected, as the service is trying to start before being configured.

. {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLog

List running modules. After a new installation, the only module you should see running is edgeAgent. After you deploy IoT Edge modules, you will see others.

iotedge list

Manage module containers

The IoT Edge service requires a container engine running on your device. When you deploy a module to a device, the IoT Edge runtime uses the container engine to pull the container image from a registry in the cloud. The IoT Edge service enables you to interact with your modules and retrieve logs, but sometimes you may want to use the container engine to interact with the container itself.

For more information about module concepts, see Understand Azure IoT Edge modules.

If you're running Windows containers on your Windows IoT Edge device, then the IoT Edge installation included the Moby container engine. The Moby engine was based on the same standards as Docker, and was designed to run in parallel on the same machine as Docker Desktop. For that reason, if you want to target containers managed by the Moby engine, you have to specifically target that engine instead of Docker.

For example, to list all Docker images, use the following command:

docker images

To list all Moby images, modify the same command with a pointer to the Moby engine:

docker -H npipe:////./pipe/iotedge_moby_engine images

The engine URI is listed in the output of the installation script, or you can find it in the container runtime settings section for the config.yaml file.

moby_runtime uri in config.yaml

For more information about commands you can use to interact with containers and images running on your device, see Docker command-line interfaces.

Update an existing installation

If you've already installed the IoT Edge runtime on a device before and provisioned it with an identity from IoT Hub, then you can update the runtime without having to reenter your device information.

For more information, see Update the IoT Edge security daemon and runtime.

This example shows an installation that points to an existing configuration file, and uses Windows containers:

. {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
Update-IoTEdge

When you update IoT Edge, you can use additional parameters to modify the update, including:

  • Direct traffic to go through a proxy server, or
  • Point the installer to an offline directory
  • Restarting without a prompt if necessary

You can't declare an IoT Edge agent container image with script parameters because that information is already set in the configuration file from the previous installation. If you want to modify the agent container image, do so in the config.yaml file.

For more information about these update options, use the command Get-Help Update-IoTEdge -full or refer to all installation parameters.

Uninstall IoT Edge

If you want to remove the IoT Edge installation from your Windows device, use the following command from an administrative PowerShell window. This command removes the IoT Edge runtime, along with your existing configuration and the Moby engine data.

Uninstall-IoTEdge

The Uninstall-IoTEdge command does not work on Windows IoT Core. To remove IoT Edge from Windows IoT Core devices, you need to redeploy your Windows IoT Core image.

For more information about uninstallation options, use the command Get-Help Uninstall-IoTEdge -full.

All installation parameters

The previous sections introduced common installation scenarios with examples of how to use parameters to modify the installation script. This section provides reference tables of the common parameters used to install, update, or uninstall IoT Edge.

Deploy-IoTEdge

The Deploy-IoTEdge command downloads and deploys the IoT Edge Security Daemon and its dependencies. The deployment command accepts these common parameters, among others. For the full list, use the command Get-Help Deploy-IoTEdge -full.

Parameter Accepted values Comments
ContainerOs Windows or Linux If no container operating system is specified, Windows is the default value.

For Windows containers, IoT Edge uses the moby container engine included in the installation. For Linux containers, you need to install a container engine before starting the installation.
Proxy Proxy URL Include this parameter if your device needs to go through a proxy server to reach the internet. For more information, see Configure an IoT Edge device to communicate through a proxy server.
OfflineInstallationPath Directory path If this parameter is included, the installer will check the listed directory for the IoT Edge cab and VC Runtime MSI files required for installation. Any files not found in the directory are downloaded. If both files are in the directory, you can install IoT Edge without an internet connection. You can also use this parameter to use a specific version.
InvokeWebRequestParameters Hashtable of parameters and values During installation, several web requests are made. Use this field to set parameters for those web requests. This parameter is useful to configure credentials for proxy servers. For more information, see Configure an IoT Edge device to communicate through a proxy server.
RestartIfNeeded none This flag allows the deployment script to restart the machine without prompting, if necessary.

Initialize-IoTEdge

The Initialize-IoTEdge command configures IoT Edge with your device connection string and operational details. Much of the information generated by this command is then stored in the iotedge\config.yaml file. The initialization command accepts these common parameters, among others. For the full list, use the command Get-Help Initialize-IoTEdge -full.

Parameter Accepted values Comments
Manual None Switch parameter. If no provisioning type is specified, manual is the default value.

Declares that you will provide a device connection string to provision the device manually
Dps None Switch parameter. If no provisioning type is specified, manual is the default value.

Declares that you will provide a Device Provisioning Service (DPS) scope ID and your device's Registration ID to provision through DPS.
DeviceConnectionString A connection string from an IoT Edge device registered in an IoT Hub, in single quotes Required for manual installation. If you don't provide a connection string in the script parameters, you will be prompted for one during installation.
ScopeId A scope ID from an instance of Device Provisioning Service associated with your IoT Hub. Required for DPS installation. If you don't provide a scope ID in the script parameters, you will be prompted for one during installation.
RegistrationId A registration ID generated by your device Required for DPS installation. If you don't provide a registration ID in the script parameters, you will be prompted for one during installation.
SymmetricKey The symmetric key used to provision the IoT Edge device identity when using DPS Required for DPS installation if using symmetric key attestation.
ContainerOs Windows or Linux If no container operating system is specified, Windows is the default value.

For Windows containers, IoT Edge uses the moby container engine included in the installation. For Linux containers, you need to install a container engine before starting the installation.
InvokeWebRequestParameters Hashtable of parameters and values During installation, several web requests are made. Use this field to set parameters for those web requests. This parameter is useful to configure credentials for proxy servers. For more information, see Configure an IoT Edge device to communicate through a proxy server.
AgentImage IoT Edge agent image URI By default, a new IoT Edge installation uses the latest rolling tag for the IoT Edge agent image. Use this parameter to set a specific tag for the image version, or to provide your own agent image. For more information, see Understand IoT Edge tags.
Username Container registry username Use this parameter only if you set the -AgentImage parameter to a container in a private registry. Provide a username with access to the registry.
Password Secure password string Use this parameter only if you set the -AgentImage parameter to a container in a private registry. Provide the password to access the registry.

Update-IoTEdge

Parameter Accepted values Comments
ContainerOs Windows or Linux If no container OS is specified, Windows is the default value. For Windows containers, a container engine will be included in the installation. For Linux containers, you need to install a container engine before starting the installation.
Proxy Proxy URL Include this parameter if your device needs to go through a proxy server to reach the internet. For more information, see Configure an IoT Edge device to communicate through a proxy server.
InvokeWebRequestParameters Hashtable of parameters and values During installation, several web requests are made. Use this field to set parameters for those web requests. This parameter is useful to configure credentials for proxy servers. For more information, see Configure an IoT Edge device to communicate through a proxy server.
OfflineInstallationPath Directory path If this parameter is included, the installer will check the listed directory for the IoT Edge cab and VC Runtime MSI files required for installation. Any files not found in the directory are downloaded. If both files are in the directory, you can install IoT Edge without an internet connection. You can also use this parameter to use a specific version.
RestartIfNeeded none This flag allows the deployment script to restart the machine without prompting, if necessary.

Uninstall-IoTEdge

Parameter Accepted values Comments
Force none This flag forces the uninstallation in case the previous attempt to uninstall was unsuccessful.
RestartIfNeeded none This flag allows the uninstall script to restart the machine without prompting, if necessary.

Next steps

Now that you have an IoT Edge device provisioned with the runtime installed, you can deploy IoT Edge modules.

If you are having problems installing IoT Edge properly, check out the troubleshooting page.

To update an existing installation to the newest version of IoT Edge, see Update the IoT Edge security daemon and runtime.