How to configure container create options for IoT Edge modules

Applies to: IoT Edge 1.5

The createOptions parameter in the deployment manifest lets you configure the module containers at runtime. This parameter expands your control over the modules and lets you perform tasks like restricting the module's access to the host device's resources or configuring networking.

IoT Edge modules run as Docker-compatible containers on your IoT Edge device. Docker offers many options for creating containers, and those options also apply to IoT Edge modules. For more information, see Docker container create options.

Format create options

The IoT Edge deployment manifest accepts create options formatted as JSON. For example, take the create options that are automatically included for every edgeHub module:

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

This edgeHub example uses the HostConfig.PortBindings parameter to map exposed ports on the container to a port on the host device.

If you use the Azure IoT Edge extension for Visual Studio or Visual Studio Code, write the create options in JSON format in the deployment.template.json file. Then, when you use the extension to build the IoT Edge solution or generate the deployment manifest, it stringifies the JSON in the format that the IoT Edge runtime expects. For example:

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

Use the docker inspect command to write create options. Run the module locally using docker run <container name> as part of your development process. Once you have the module working the way you want it, run docker inspect <container name>. This command outputs the module details in JSON format. Find the parameters you configured and copy the JSON. For example:

Common scenarios

Container create options support various scenarios. Here are the most common ones for building IoT Edge solutions:

• Give modules access to host storage
• Map host port to module port
• Restrict module memory and CPU usage
• GPU-optimize an IoT Edge module

Map host port to module port

If your module needs to communicate with a service outside of the IoT Edge solution, and isn't using message routing to do so, then you need to map a host port to a module port.

First, ensure that a port inside the module is exposed to listen for connections. You can do this using an EXPOSE instruction in the dockerfile. For example, EXPOSE 8080. The expose instruction defaults to TCP protocol if not specified, or you can specify UDP.

Then, use the PortBindings setting in the HostConfig group of the Docker container create options to map the exposed port in the module to a port on the host device. For example, if you exposed port 8080 inside the module and want to map that to port 80 of the host device, the create options in the template.json file would look like the following example:

"createOptions": {
  "HostConfig": {
    "PortBindings": {
      "8080/tcp": [
        {
          "HostPort": "80"
        }
      ]
    }
  }
}

When stringified for the deployment manifest, the configuration looks like this:

"createOptions": "{\"HostConfig\":{\"PortBindings\":{\"8080/tcp\":[{\"HostPort\":\"80\"}]}}}"

Restrict module memory and CPU usage

Declare how much of the host resources a module can use. This control ensures that one module doesn't consume too much memory or CPU, preventing other processes from running on the device. You can manage these settings with Docker container create options in the HostConfig group, including:

• Memory: Memory limit in bytes. For example, 268435456 bytes = 256 MB.
• MemorySwap: Total memory limit (memory + swap). For example, 536870912 bytes = 512 MB.
• NanoCpus: CPU quota in units of 10^-9 (1 billionth) CPUs. For example, 250000000 nanocpus = 0.25 CPU.

In the template.json format, these values would look like the following example:

"createOptions": {
  "HostConfig": {
    "Memory": 268435456,
    "MemorySwap": 536870912,
    "NanoCpus": 250000000
  }
}

Once stringified for the final deployment manifest, these values would look like the following example:

"createOptions":"{\"HostConfig\":{\"Memory\":268435456,\"MemorySwap\":536870912,\"CpuPeriod\":25000}}"

GPU-optimize an IoT Edge module

If you're running your IoT Edge module on a GPU-optimized virtual machine, you can enable an IoT Edge module to connect to your GPU as well. To do this with an existing module, add some specifications to your createOptions:

{"HostConfig": {"DeviceRequests": [{"Count": -1,"Capabilities": [["gpu"]]}]}}

Confirm these settings by using the Docker inspect command to view the new setting in a JSON printout.

sudo docker inspect <YOUR-MODULE-NAME>

To learn more about how your device and virtual machine connect to a GPU, see Configure, connect, and verify an IoT Edge module for a GPU.

Next steps

For more examples of create options in action, see these IoT Edge samples:

• Custom Vision and Azure IoT Edge on a Raspberry Pi 3
• Azure IoT Edge blob storage sample