|
| 1 | +--- |
| 2 | +title: Write createOptions for modules - Azure IoT Edge | Microsoft Docs |
| 3 | +description: How to use createOptions in the deployment manifest to configure modules at runtime |
| 4 | +keywords: |
| 5 | +author: kgremban |
| 6 | +manager: philmea |
| 7 | +ms.author: kgremban |
| 8 | +ms.date: 04/01/2020 |
| 9 | +ms.topic: conceptual |
| 10 | +ms.service: iot-edge |
| 11 | +services: iot-edge |
| 12 | +--- |
| 13 | + |
| 14 | +# How to configure container create options for IoT Edge modules |
| 15 | + |
| 16 | +The **createOptions** parameter in the deployment manifest enables you to configure the module containers at runtime. This parameter expands your control over the modules and allows for tasks like allowing or restricting the module's access to the host device's resources, or configuring networking. |
| 17 | + |
| 18 | +IoT Edge modules are implemented as Docker-compatible containers on your IoT Edge device. Docker offers many options for creating containers, and those options apply to IoT Edge modules, too. For more information, see [Docker container create options](https://docs.docker.com/engine/api/v1.32/#operation/ContainerCreate). |
| 19 | + |
| 20 | +## Format create options |
| 21 | + |
| 22 | +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: |
| 23 | + |
| 24 | +```json |
| 25 | +"createOptions": { |
| 26 | + "HostConfig": { |
| 27 | + "PortBindings": { |
| 28 | + "5671/tcp": [ |
| 29 | + { |
| 30 | + "HostPort": "5671" |
| 31 | + } |
| 32 | + ], |
| 33 | + "8883/tcp": [ |
| 34 | + { |
| 35 | + "HostPort": "8883" |
| 36 | + } |
| 37 | + ], |
| 38 | + "443/tcp": [ |
| 39 | + { |
| 40 | + "HostPort": "443" |
| 41 | + } |
| 42 | + ] |
| 43 | + } |
| 44 | + } |
| 45 | +} |
| 46 | +``` |
| 47 | + |
| 48 | +This edgeHub example uses the **HostConfig.PortBindings** parameter to map exposed ports on the container to a port on the host device. |
| 49 | + |
| 50 | +If you use the Azure IoT Tools extensions for Visual Studio or Visual Studio Code, you can 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 will stringify the JSON for you in the format that the IoT Edge runtime expects. For example: |
| 51 | + |
| 52 | +```json |
| 53 | +"createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}" |
| 54 | +``` |
| 55 | + |
| 56 | +One tip for writing create options is to use the `docker inspect` command. As part of your development process, run the module locally using `docker run <container name>`. 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 that you configured, and copy the JSON. For example: |
| 57 | + |
| 58 | +[  ](./media/how-to-use-create-options/docker-inspect-edgehub-inline-and-expanded.png#lightbox) |
| 59 | + |
| 60 | +## Common scenarios |
| 61 | + |
| 62 | +Container create options enable many scenarios, but here are some that come up most often when building IoT Edge solutions: |
| 63 | + |
| 64 | +* [Give modules access to host storage](how-to-access-host-storage-from-module.md) |
| 65 | +* [Map host port to module port](#map-host-port-to-module-port) |
| 66 | +* [Restrict module memory and CPU usage](#restrict-module-memory-and-cpu-usage) |
| 67 | + |
| 68 | +### Map host port to module port |
| 69 | + |
| 70 | +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. |
| 71 | + |
| 72 | +>[!TIP] |
| 73 | +>This port mapping is not required for module-to-module communication on the same device. If module A needs to query an API hosted on module B, it can do so without any port mapping. Module B needs to expose a port in its dockerfile, for example: `EXPOSE 8080`. Then module A can query the API using module B's name, for example: `http://ModuleB:8080/api`. |
| 74 | +
|
| 75 | +First, make sure that a port inside the module is exposed to listen for connections. You can do this using an [EXPOSE](https://docs.docker.com/engine/reference/builder/#expose) instruction in the dockerfile. For example, `EXPOSE 8080`. The expose instruction defaults to TCP protocol if not specified, or you can specify UDP. |
| 76 | + |
| 77 | +Then, use the **PortBindings** setting in the **HostConfig** group of the [Docker container create options](https://docs.docker.com/engine/api/v1.32/#operation/ContainerCreate) 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: |
| 78 | + |
| 79 | +```json |
| 80 | +"createOptions": { |
| 81 | + "HostConfig": { |
| 82 | + "PortBindings": { |
| 83 | + "8080/tcp": [ |
| 84 | + { |
| 85 | + "HostPort": "80" |
| 86 | + } |
| 87 | + ] |
| 88 | + } |
| 89 | + } |
| 90 | +} |
| 91 | +``` |
| 92 | + |
| 93 | +Once stringified for the deployment manifest, the same configuration would look like the following example: |
| 94 | + |
| 95 | +```json |
| 96 | +"createOptions": "{\"HostConfig\":{\"PortBindings\":{\"8080/tcp\":[{\"HostPort\":\"80\"}]}}}" |
| 97 | +``` |
| 98 | + |
| 99 | +### Restrict module memory and CPU usage |
| 100 | + |
| 101 | +You can declare how much of the host resources a module can use. This control is helpful to ensure that one module can't consume too much memory or CPU usage and prevent other processes from running on the device. You can manage these settings with [Docker container create options](https://docs.docker.com/engine/api/v1.32/#operation/ContainerCreate) in the **HostConfig** group, including: |
| 102 | + |
| 103 | +* **Memory**: Memory limit in bytes. For example, 268435456 bytes = 256 MB. |
| 104 | +* **MemorySwap**: Total memory limit (memory + swap). For example, 536870912 bytes = 512 MB |
| 105 | +* **CpuPeriod**: The length of a CPU period in microseconds. The default value is 100000 so, for example, a value of 25000 limits a container to 25% of the CPU resources. |
| 106 | + |
| 107 | +In the template.json format, these values would look like the following example: |
| 108 | + |
| 109 | +```json |
| 110 | +"createOptions": { |
| 111 | + "HostConfig": { |
| 112 | + "Memory": 268435456, |
| 113 | + "MemorySwap": 536870912, |
| 114 | + "CpuPeriod": 25000 |
| 115 | + } |
| 116 | +} |
| 117 | +``` |
| 118 | + |
| 119 | +Once stringified for the final deployment manifest, these values would look like the following example: |
| 120 | + |
| 121 | +```json |
| 122 | +"createOptions":"{\"HostConfig\":{\"Memory\":268435456,\"MemorySwap\":536870912,\"CpuPeriod\":25000}}" |
| 123 | +``` |
| 124 | + |
| 125 | +## Next steps |
| 126 | + |
| 127 | +For more examples of create options in action, see the following IoT Edge samples: |
| 128 | + |
| 129 | +* [Custom Vision and Azure IoT Edge on a Raspberry Pi 3](https://github.com/Azure-Samples/Custom-vision-service-iot-edge-raspberry-pi) |
| 130 | +* [Azure IoT Edge blob storage sample](https://github.com/Azure-Samples/azure-iotedge-blobstorage-sample) |
0 commit comments