Skip to content

Commit c3171da

Browse files
tiburdtiburd
authored
Merge pull request #91494 from v-stadam/module_access_storage_1008
Access host device storage from a module
2 parents 76c0d92 + 4f83f7f commit c3171da

File tree

4 files changed

+80
-63
lines changed

4 files changed

+80
-63
lines changed

‎articles/iot-edge/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -177,6 +177,8 @@
177177
href: how-to-configure-proxy-support.md
178178
- name: Store data at the edge
179179
items:
180+
- name: Give modules access to a device's local storage
181+
href: how-to-access-host-storage-from-module.md
180182
- name: Azure Blob Storage on IoT Edge
181183
href: how-to-store-data-blob.md
182184
- name: Deploy blob storage modules

‎articles/iot-edge/how-to-access-host-storage-from-module.md

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
title: Use IoT Edge device local storage from a module - Azure IoT Edge | Microsoft Docs
3+
description: Use environment variables and create options to enable module access to IoT Edge device local storage.
4+
author: kgremban
5+
manager: philmea
6+
ms.author: kgremban
7+
ms.date: 10/12/2019
8+
ms.topic: conceptual
9+
ms.service: iot-edge
10+
services: iot-edge
11+
---
12+
13+
# Give modules access to a device's local storage
14+
15+
In addition to storing data using Azure storage services or in your device's container storage, you can also dedicate storage on the host IoT Edge device itself for improved reliability, especially when operating offline.
16+
17+
To set up storage on the host system, create an environment variable for your module 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.
18+
19+
For example, if you wanted to enable the IoT Edge hub to store messages in your device's local storage and retrieve them later, you can configure the environment variables and the create options in the Azure portal in the **Configure advanced Edge Runtime settings** section.
20+
21+
1. For both IoT Edge hub and IoT Edge agent, add an environment variable called **storageFolder** that points to a directory in the module.
22+
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:
23+
24+
![Add create options and environment variables for local storage](./media/how-to-access-host-storage-from-module/offline-storage.png)
25+
26+
Or, you can configure the local storage directly in the deployment manifest. For example:
27+
28+
```json
29+
"systemModules": {
30+
"edgeAgent": {
31+
"settings": {
32+
"image": "mcr.microsoft.com/azureiotedge-agent:1.0",
33+
"createOptions": {
34+
"HostConfig": {
35+
"Binds":["<HostStoragePath>:<ModuleStoragePath>"]
36+
}
37+
}
38+
},
39+
"type": "docker",
40+
"env": {
41+
"storageFolder": {
42+
"value": "<ModuleStoragePath>"
43+
}
44+
}
45+
},
46+
"edgeHub": {
47+
"settings": {
48+
"image": "mcr.microsoft.com/azureiotedge-hub:1.0",
49+
"createOptions": {
50+
"HostConfig": {
51+
"Binds":["<HostStoragePath>:<ModuleStoragePath>"],
52+
"PortBindings":{"5671/tcp":[{"HostPort":"5671"}],"8883/tcp":[{"HostPort":"8883"}],"443/tcp":[{"HostPort":"443"}]}}}
53+
},
54+
"type": "docker",
55+
"env": {
56+
"storageFolder": {
57+
"value": "<ModuleStoragePath>"
58+
}
59+
},
60+
"status": "running",
61+
"restartPolicy": "always"
62+
}
63+
}
64+
```
65+
66+
Replace `<HostStoragePath>` and `<ModuleStoragePath>` with your host and module storage path; both values must be an absolute path.
67+
68+
For example, on a Linux system, `"Binds":["/etc/iotedge/storage/:/iotedge/storage/"]` means the directory **/etc/iotedge/storage** on your host system is mapped to the directory **/iotedge/storage/** in the container. On a Windows system, as another example, `"Binds":["C:\\temp:C:\\contemp"]` means the directory **C:\\temp** on your host system is mapped to the directory **C:\\contemp** in the container.
69+
70+
Additionally, on Linux devices, make sure that the user profile for your module has the required read, write, and execute permissions to the host system directory. Returning to the earlier example of enabling IoT Edge hub to store messages in your device's local storage, you need to grant permissions to its user profile, UID 1000. (The IoT Edge agent operates as root, so it 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, such as:
71+
72+
```bash
73+
sudo chown 1000 <HostStoragePath>
74+
sudo chmod 700 <HostStoragePath>
75+
```
76+
77+
You can find more details about create options from [docker docs](https://docs.docker.com/engine/api/v1.32/#operation/ContainerCreate).

‎articles/iot-edge/media/offline-capabilities/offline-storage.png renamed to ‎articles/iot-edge/media/how-to-access-host-storage-from-module/offline-storage.png

File renamed without changes.

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

Lines changed: 1 addition & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -133,69 +133,7 @@ This setting is a desired property of the IoT Edge hub, which is stored in the m
133133

134134
### Host storage for system modules
135135

136-
Messages and module state information are stored in the IoT Edge hub's local container filesystem by default. For improved reliability, especially when operating offline, you can also dedicate storage on the host IoT Edge device.
137-
138-
To set up storage on the host system, 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:
148-
149-
```json
150-
"systemModules": {
151-
"edgeAgent": {
152-
"settings": {
153-
"image": "mcr.microsoft.com/azureiotedge-agent:1.0",
154-
"createOptions": {
155-
"HostConfig": {
156-
"Binds":["<HostStoragePath>:<ModuleStoragePath>"]
157-
}
158-
}
159-
},
160-
"type": "docker",
161-
"env": {
162-
"storageFolder": {
163-
"value": "<ModuleStoragePath>"
164-
}
165-
}
166-
},
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-
}
184-
}
185-
```
186-
187-
Replace `<HostStoragePath>` and `<ModuleStoragePath>` with your host and module storage path; both values must be an absolute path.
188-
189-
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.
190-
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).
136+
Messages and module state information are stored in the IoT Edge hub's local container filesystem by default. For improved reliability, especially when operating offline, you can also dedicate storage on the host IoT Edge device. For more information, see [Give modules access to a device's local storage](how-to-access-host-storage-from-module.md)
199137

200138
## Next steps
201139

0 commit comments

Comments
 (0)