Skip to content

Commit bcd1b8a

Browse files
GitHubber17GitHubber17
authored
Merge pull request #84357 from kgremban/aug5-edgehubuserperms
Add edgehubuser perms to offline doc
2 parents d7229e7 + 4afde70 commit bcd1b8a

File tree

3 files changed

+80
-46
lines changed

3 files changed

+80
-46
lines changed

‎articles/iot-edge/media/offline-capabilities/offline-storage.png

7.12 KB
Loading

‎articles/iot-edge/offline-capabilities.md

Lines changed: 52 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,8 @@
22
title: Operate devices offline - Azure IoT Edge | Microsoft Docs
33
description: Understand how IoT Edge devices and modules can operate without internet connection for extended periods of time, and how IoT Edge can enable regular IoT devices to operate offline too.
44
author: kgremban
5-
manager: philmea
65
ms.author: kgremban
7-
ms.date: 06/04/2019
6+
ms.date: 08/04/2019
87
ms.topic: conceptual
98
ms.service: iot-edge
109
services: iot-edge
@@ -132,43 +131,71 @@ This setting is a desired property of the IoT Edge hub, which is stored in the m
132131
}
133132
```
134133

135-
### Additional offline storage
134+
### Store system module states in the host filesystem
136135

137-
Messages are stored by default in the IoT Edge hub's container filesystem. If that amount of storage isn't sufficient for your offline needs, you can dedicate local storage on the IoT Edge device. Create an environment variable for the IoT Edge hub that points to a storage folder in the container. Then, use the create options to bind that storage folder to a folder on the host machine.
136+
Messages are stored by default in the IoT Edge hub's container filesystem. You can also dedicate local storage on the IoT Edge device. Using the host filesystem for storage is recommended for improved reliability, especially for devices that operate offline.
138137

139-
You can configure environment variables and the create options for the IoT Edge hub module in the Azure portal in the **Configure advanced Edge Runtime settings** section. Or, you can configure it directly in the deployment manifest.
138+
To set up local storage, create environment variables for the IoT Edge hub and IoT Edge agent that point to a storage folder in the container. Then, use the create options to bind that storage folder to a folder on the host machine.
139+
140+
You can configure environment variables and the create options for the IoT Edge hub module in the Azure portal in the **Configure advanced Edge Runtime settings** section.
141+
142+
1. For both IoT Edge hub and IoT Edge agent, add an environment variable called **storageFolder** that points to a directory in the module.
143+
1. For both IoT Edge hub and IoT Edge agent, add binds to connect a local directory on the host machine to a directory in the module. For example:
144+
145+
![Add create options and environment variables for local storage](./media/offline-capabilities/offline-storage.png)
146+
147+
Or, you can configure the local storage directly in the deployment manifest. For example:
140148

141149
```json
142-
"edgeHub": {
143-
"type": "docker",
144-
"settings": {
145-
"image": "mcr.microsoft.com/azureiotedge-hub:1.0",
146-
"createOptions": {
147-
"HostConfig": {
148-
"Binds": ["<HostStoragePath>:<ModuleStoragePath>"],
149-
"PortBindings": {
150-
"8883/tcp": [{"HostPort":"8883"}],
151-
"443/tcp": [{"HostPort":"443"}],
152-
"5671/tcp": [{"HostPort":"5671"}]
150+
"systemModules": {
151+
"edgeAgent": {
152+
"settings": {
153+
"image": "mcr.microsoft.com/azureiotedge-agent:1.0",
154+
"createOptions": {
155+
"HostConfig": {
156+
"Binds":["<HostStoragePath>:<ModuleStoragePath>"]
153157
}
154158
}
159+
},
160+
"type": "docker",
161+
"env": {
162+
"storageFolder": {
163+
"value": "<ModuleStoragePath>"
164+
}
155165
}
156166
},
157-
"env": {
158-
"storageFolder": {
159-
"value": "<ModuleStoragePath>"
160-
}
161-
},
162-
"status": "running",
163-
"restartPolicy": "always"
167+
"edgeHub": {
168+
"settings": {
169+
"image": "mcr.microsoft.com/azureiotedge-hub:1.0",
170+
"createOptions": {
171+
"HostConfig": {
172+
"Binds":["<HostStoragePath>:<ModuleStoragePath"],
173+
"PortBindings":{"5671/tcp":[{"HostPort":"5671"}],"8883/tcp":[{"HostPort":"8883"}],"443/tcp":[{"HostPort":"443"}]}}}
174+
},
175+
"type": "docker",
176+
"env": {
177+
"storageFolder": {
178+
"value": "<ModuleStoragePath>"
179+
}
180+
},
181+
"status": "running",
182+
"restartPolicy": "always"
183+
}
164184
}
165185
```
166186

167-
Replace `<HostStoragePath>` and `<ModuleStoragePath>` with your host and module storage path; both host and module storage path must be an absolute path. In the create options, bind the host and module storage paths together. Then, create an environment variable that points to the module storage path.
187+
Replace `<HostStoragePath>` and `<ModuleStoragePath>` with your host and module storage path; both values must be an absolute path.
168188

169189
For example, `"Binds":["/etc/iotedge/storage/:/iotedge/storage/"]` means the directory **/etc/iotedge/storage** on your host system is mapped to the directory **/iotedge/storage/** on the container. Or another example for Windows systems, `"Binds":["C:\\temp:C:\\contemp"]` means the directory **C:\\temp** on your host system is mapped to the directory **C:\\contemp** on the container.
170190

171-
You can also find more details about create options from [docker docs](https://docs.docker.com/engine/api/v1.32/#operation/ContainerCreate).
191+
On Linux devices, make sure that the IoT Edge hub's user profile, UID 1000, has read, write, and execute permissions to the host system directory. These permissions are necessary so that the IoT Edge hub can store messages in the directory and retrieve them later. (The IoT Edge agent operates as root, so doesn't need additional permissions.) There are several ways to manage directory permissions on Linux systems, including using `chown` to change the directory owner and then `chmod` to change the permissions. For example:
192+
193+
```bash
194+
sudo chown 1000 <HostStoragePath>
195+
sudo chmod 700 <HostStoragePath>
196+
```
197+
198+
You can find more details about create options from [docker docs](https://docs.docker.com/engine/api/v1.32/#operation/ContainerCreate).
172199

173200
## Next steps
174201

‎articles/iot-edge/production-checklist.md

Lines changed: 28 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
---
22
title: Prepare devices and deployments for production - Azure IoT Edge | Microsoft Docs
3-
description: Learn how to take your Azure IoT Edge solution from development to production, including setting your devices up with the appropriate certificates and making a deployment plan for future code updates.
3+
description: Learn how to take your Azure IoT Edge solution from development to production, including setting up your devices with the appropriate certificates and making a deployment plan for future code updates.
44
author: kgremban
55
manager: philmea
66
ms.author: kgremban
7-
ms.date: 11/28/2018
7+
ms.date: 08/09/2019
88
ms.topic: conceptual
99
ms.service: iot-edge
1010
services: iot-edge
@@ -15,11 +15,11 @@ ms.custom: seodec18
1515

1616
When you're ready to take your IoT Edge solution from development into production, make sure that it's configured for ongoing performance.
1717

18-
The information provided in this article is not all equal. To help you prioritize, each section starts with lists that divide the work into two sections: **important** to complete before going to production, or **helpful** for you to know.
18+
The information provided in this article isn't all equal. To help you prioritize, each section starts with lists that divide the work into two sections: **important** to complete before going to production, or **helpful** for you to know.
1919

2020
## Device configuration
2121

22-
IoT Edge devices can be anything from a Raspberry Pi to a laptop to a virtual machine running on a server. You may have access to the device either physically or through a virtual connection, or it may be isolated for extended periods of time. Either way, you want to make sure that it's configured to perform appropriately.
22+
IoT Edge devices can be anything from a Raspberry Pi to a laptop to a virtual machine running on a server. You may have access to the device either physically or through a virtual connection, or it may be isolated for extended periods of time. Either way, you want to make sure that it's configured to work appropriately.
2323

2424
* **Important**
2525
* Install production certificates
@@ -47,15 +47,15 @@ Before you put any device in production you should know how you're going to mana
4747
* IoT Edge daemon
4848
* CA certificates
4949

50-
For steps to update the IoT Edge daemon, see [Update the IoT Edge runtime](how-to-update-iot-edge.md). The current methods for updating the IoT Edge daemon require physical or SSH access to the IoT Edge device. If you have many devices to update, consider adding the update steps to a script or use an automation tool like Ansible to perform updates at scale.
50+
For more information, see [Update the IoT Edge runtime](how-to-update-iot-edge.md). The current methods for updating the IoT Edge daemon require physical or SSH access to the IoT Edge device. If you have many devices to update, consider adding the update steps to a script or use an automation tool like Ansible.
5151

5252
### Use Moby as the container engine
5353

54-
Having a container engine on a device is a prerequisite for any IoT Edge device. Only moby-engine is supported in production. Other container engines, like Docker, do work with IoT Edge and it's ok to use these engines for development. The moby-engine can be redistributed when used with Azure IoT Edge, and Microsoft provides servicing for this engine. Using other container engines on an IoT Edge device is not supported.
54+
A container engine is a prerequisite for any IoT Edge device. Only moby-engine is supported in production. Other container engines, like Docker, do work with IoT Edge and it's ok to use these engines for development. The moby-engine can be redistributed when used with Azure IoT Edge, and Microsoft provides servicing for this engine.
5555

5656
### Choose upstream protocol
5757

58-
The protocol (and therefore the port used) for upstream communication to IoT Hub can be configured for both the Edge agent and the Edge hub. The default protocol is AMQP, but you may want to change that depending on your network setup.
58+
The protocol (and therefore the port used) for upstream communication to IoT Hub can be configured for both the IoT Edge agent and the IoT Edge hub. The default protocol is AMQP, but you may want to change that depending on your network setup.
5959

6060
The two runtime modules both have an **UpstreamProtocol** environment variable. The valid values for the variable are:
6161

@@ -64,40 +64,47 @@ The two runtime modules both have an **UpstreamProtocol** environment variable.
6464
* MQTTWS
6565
* AMQPWS
6666

67-
Configure the UpstreamProtocol variable for the Edge agent in the config.yaml file on the device itself. For example, if your IoT Edge device is behind a proxy server that blocks AMQP ports, you may need to configure the Edge agent to use AMQP over WebSocket (AMQPWS) to establish the initial connection to IoT Hub.
67+
Configure the UpstreamProtocol variable for the IoT Edge agent in the config.yaml file on the device itself. For example, if your IoT Edge device is behind a proxy server that blocks AMQP ports, you may need to configure the IoT Edge agent to use AMQP over WebSocket (AMQPWS) to establish the initial connection to IoT Hub.
6868

6969
Once your IoT Edge device connects, be sure to continue configuring the UpstreamProtocol variable for both runtime modules in future deployments. An example of this process is provided in [Configure an IoT Edge device to communicate through a proxy server](how-to-configure-proxy-support.md).
7070

7171
## Deployment
7272

7373
* **Helpful**
7474
* Be consistent with upstream protocol
75-
* Reduce memory space used by Edge hub
75+
* Store system module statues in the host filesystem
76+
* Reduce memory space used by the IoT Edge hub
7677
* Do not use debug versions of module images
7778

7879
### Be consistent with upstream protocol
7980

80-
If you configured the Edge agent on your IoT Edge device to use a different protocol than the default AMQP, then you should declare the same protocol in all subsequent deployments. For example, if your IoT Edge device is behind a proxy server that blocks AMQP ports, you probably configured the device to connect over AMQP over WebSocket (AMQPWS). When you deploy modules to the device, if you don't configure the same APQPWS protocol for the Edge agent and Edge hub, the default AMQP will override the settings and prevent you from connecting again.
81+
If you configured the IoT Edge agent on your IoT Edge device to use a different protocol than the default AMQP, then you should declare the same protocol in all future deployments. For example, if your IoT Edge device is behind a proxy server that blocks AMQP ports, you probably configured the device to connect over AMQP over WebSocket (AMQPWS). When you deploy modules to the device, configure the same APQPWS protocol for the IoT Edge agent and IoT Edge hub, or else the default AMQP will override the settings and prevent you from connecting again.
8182

82-
You only have to configure the UpstreamProtocol environment variable for the Edge agent and Edge hub modules. Any additional modules adopt whatever protocol is set in the runtime modules.
83+
You only have to configure the UpstreamProtocol environment variable for the IoT Edge agent and IoT Edge hub modules. Any additional modules adopt whatever protocol is set in the runtime modules.
8384

8485
An example of this process is provided in [Configure an IoT Edge device to communicate through a proxy server](how-to-configure-proxy-support.md).
8586

86-
### Reduce memory space used by Edge hub
87+
### Store system module states in the host filesystem
8788

88-
If you're deploying constrained devices with limited memory available, you can configure Edge hub to run in a more streamlined capacity and use less disk space. These configurations do limit the performance of the Edge hub, however, so find the right balance that works for your solution.
89+
The IoT Edge hub and agent modules use local storage to maintain state and enable messaging between modules, devices, and the cloud. For better reliability and performance, configure the system modules to use storage on the host filesystem.
90+
91+
For more information, see [Store system module states in the host filesystem](offline-capabilities.md#store-system-module-states-in-the-host-filesystem).
92+
93+
### Reduce memory space used by IoT Edge hub
94+
95+
If you're deploying constrained devices with limited memory available, you can configure IoT Edge hub to run in a more streamlined capacity and use less disk space. These configurations do limit the performance of the IoT Edge hub, however, so find the right balance that works for your solution.
8996

9097
#### Don't optimize for performance on constrained devices
9198

92-
The Edge hub is optimized for performance by default, so it attempts to allocate large chunks of memory. This configuration can cause stability problems on smaller devices like the Raspberry Pi. If you're deploying devices with constrained resources, you may want to set the **OptimizeForPerformance** environment variable to **false** on the Edge hub.
99+
The IoT Edge hub is optimized for performance by default, so it attempts to allocate large chunks of memory. This configuration can cause stability problems on smaller devices like the Raspberry Pi. If you're deploying devices with constrained resources, you may want to set the **OptimizeForPerformance** environment variable to **false** on the IoT Edge hub.
93100

94101
For more information, see [Stability issues on resource constrained devices](troubleshoot.md#stability-issues-on-resource-constrained-devices).
95102

96103
#### Disable unused protocols
97104

98-
Another way to optimize the performance of the Edge hub and reduce its memory usage is to turn off the protocol heads for any protocols that you're not using in your solution.
105+
Another way to optimize the performance of the IoT Edge hub and reduce its memory usage is to turn off the protocol heads for any protocols that you're not using in your solution.
99106

100-
Protocol heads are configured by setting boolean environment variables for the Edge hub module in your deployment manifests. The three variables are:
107+
Protocol heads are configured by setting boolean environment variables for the IoT Edge hub module in your deployment manifests. The three variables are:
101108

102109
* **amqpSettings__enabled**
103110
* **mqttSettings__enabled**
@@ -107,7 +114,7 @@ All three variables have *two underscores* and can be set to either true or fals
107114

108115
#### Reduce storage time for messages
109116

110-
The Edge hub module stores messages temporarily if they cannot be delivered to IoT Hub for any reason. You can configure how long the Edge hub holds on to undelivered messages before letting them expire. If you have memory concerns on your device, you can lower the **timeToLiveSecs** value in the Edge hub module twin.
117+
The IoT Edge hub module stores messages temporarily if they cannot be delivered to IoT Hub for any reason. You can configure how long the IoT Edge hub holds on to undelivered messages before letting them expire. If you have memory concerns on your device, you can lower the **timeToLiveSecs** value in the IoT Edge hub module twin.
111118

112119
The default value of the timeToLiveSecs parameter is 7200 seconds, which is two hours.
113120

@@ -139,16 +146,16 @@ For an example of a tag convention, see [Update the IoT Edge runtime](how-to-upd
139146

140147
* **Helpful**
141148
* Review outbound/inbound configuration
142-
* Whitelist connections
149+
* Allow connections from IoT Edge devices
143150
* Configure communication through a proxy
144151

145152
### Review outbound/inbound configuration
146153

147154
Communication channels between Azure IoT Hub and IoT Edge are always configured to be outbound. For most IoT Edge scenarios, only three connections are necessary. The container engine needs to connect with the container registry (or registries) that holds the module images. The IoT Edge runtime needs to connect with IoT Hub to retrieve device configuration information, and to send messages and telemetry. And if you use automatic provisioning, the IoT Edge daemon needs to connect to the Device Provisioning Service. For more information, see [Firewall and port configuration rules](troubleshoot.md#firewall-and-port-configuration-rules-for-iot-edge-deployment).
148155

149-
### Whitelist connections
156+
### Allow connections from IoT Edge devices
150157

151-
If your networking setup requires that you explicitly whitelist connections made from IoT Edge devices, review the following list of IoT Edge components:
158+
If your networking setup requires that you explicitly permit connections made from IoT Edge devices, review the following list of IoT Edge components:
152159

153160
* **IoT Edge agent** opens a persistent AMQP/MQTT connection to IoT Hub, possibly over WebSockets.
154161
* **IoT Edge hub** opens a single persistent AMQP connection or multiple MQTT connections to IoT Hub, possibly over WebSockets.
@@ -164,7 +171,7 @@ This checklist is a starting point for firewall rules:
164171
| ----- | ----- | ----- |
165172
| mcr.microsoft.com | 443 | Microsoft container registry |
166173
| global.azure-devices-provisioning.net | 443 | DPS access (optional) |
167-
| \*.azurecr.io | 443 | Personal and 3rd party container registries |
174+
| \*.azurecr.io | 443 | Personal and third-party container registries |
168175
| \*.blob.core.windows.net | 443 | Download of image deltas |
169176
| \*.azure-devices.net | 5671, 8883, 443 | IoT Hub access |
170177
| \*.docker.io | 443 | Docker Hub access (optional) |

0 commit comments

Comments
 (0)