Initial commit
This commit is contained in:
Zhongwei Li
238
skills/iot-edge-module/references/deployment-manifests.md
Normal file
238
skills/iot-edge-module/references/deployment-manifests.md
Normal file
@@ -0,0 +1,238 @@
|
||||
# IoT Edge Deployment Manifests Reference
|
||||
|
||||
This document provides reference information for the deployment manifest structure used in this project.
|
||||
|
||||
## Manifest Types
|
||||
|
||||
Projects typically use one or more deployment manifests to organize modules:
|
||||
|
||||
### Example: Base Deployment Manifest
|
||||
|
||||
**Naming pattern**: `*.deployment.manifest.json` (e.g., `base.deployment.manifest.json`)
|
||||
|
||||
**Purpose**: Contains modules that should be deployed to all or specific edge devices.
|
||||
|
||||
**Example modules**:
|
||||
- Metric collector modules - Collects operational metrics
|
||||
- Telemetry transformation modules - Enriches raw telemetry
|
||||
- Custom business logic modules
|
||||
|
||||
**Routing**:
|
||||
- Modules typically route to `$upstream` (IoT Hub) or to other modules via BrokeredEndpoint
|
||||
|
||||
## Deployment Manifest Structure
|
||||
|
||||
### Top-Level Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"modulesContent": {
|
||||
"$edgeAgent": { ... },
|
||||
"$edgeHub": { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Module Definition ($edgeAgent)
|
||||
|
||||
Each module is defined under `$edgeAgent` with the following structure:
|
||||
|
||||
```json
|
||||
"properties.desired.modules.<modulename>": {
|
||||
"version": "1.0",
|
||||
"type": "docker",
|
||||
"status": "running",
|
||||
"restartPolicy": "always",
|
||||
"startupOrder": <number>,
|
||||
"settings": {
|
||||
"image": "${MODULES.<modulename>}",
|
||||
"createOptions": {
|
||||
"HostConfig": {
|
||||
"LogConfig": {
|
||||
"Type": "json-file",
|
||||
"Config": {
|
||||
"max-size": "10m",
|
||||
"max-file": "10"
|
||||
}
|
||||
},
|
||||
"Binds": [
|
||||
// Optional host volume binds
|
||||
],
|
||||
"Mounts": [
|
||||
// Optional volume mounts
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"env": {
|
||||
// Optional environment variables
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key fields**:
|
||||
- `version`: Module version (typically "1.0")
|
||||
- `type`: Always "docker"
|
||||
- `status`: Desired status ("running")
|
||||
- `restartPolicy`: Restart behavior ("always")
|
||||
- `startupOrder`: Module startup sequence (lower starts first, system modules use 0)
|
||||
- `image`: Container image (use variable substitution: `${MODULES.<modulename>}`)
|
||||
- `createOptions`: Docker container creation options
|
||||
- `LogConfig`: Log rotation settings (10m max size, 10 files)
|
||||
- `Binds`: Host path bindings for persistent storage
|
||||
- `Mounts`: Named volume mounts
|
||||
- `env`: Environment variables (use variable substitution for secrets)
|
||||
|
||||
### Routing Configuration ($edgeHub)
|
||||
|
||||
Each route is defined under `$edgeHub`:
|
||||
|
||||
```json
|
||||
"properties.desired.routes.<routename>": {
|
||||
"route": "<route expression>",
|
||||
"priority": 0,
|
||||
"timeToLiveSecs": 86400
|
||||
}
|
||||
```
|
||||
|
||||
**Common route patterns**:
|
||||
|
||||
1. **Module to IoT Hub (upstream)**:
|
||||
```json
|
||||
"route": "FROM /messages/modules/<modulename>/outputs/* INTO $upstream"
|
||||
```
|
||||
|
||||
2. **Module to module (BrokeredEndpoint)**:
|
||||
```json
|
||||
"route": "FROM /messages/modules/<sourcemodule>/* INTO BrokeredEndpoint(\"/modules/<targetmodule>/inputs/<inputname>\")"
|
||||
```
|
||||
|
||||
**Key fields**:
|
||||
- `route`: Route expression using IoT Edge routing syntax
|
||||
- `priority`: Route priority (0 = normal)
|
||||
- `timeToLiveSecs`: Message TTL (86400 = 24 hours)
|
||||
|
||||
### Variable Substitution
|
||||
|
||||
Manifests use variable substitution for dynamic values:
|
||||
|
||||
- `${MODULES.<modulename>}` - Module container image URI
|
||||
- `${ContainerRegistryUserName}` - Registry username
|
||||
- `${ContainerRegistryPassword}` - Registry password
|
||||
- `${ContainerRegistryLoginServer}` - Registry server URL
|
||||
- `${LogAnalyticsWorkspaceId}` - Log Analytics workspace ID
|
||||
- `${LogAnalyticsWorkspaceSharedKey}` - Log Analytics shared key
|
||||
- `${IotHubResourceId}` - IoT Hub resource ID
|
||||
|
||||
## Module-Specific Patterns
|
||||
|
||||
### Modules with Volume Mounts
|
||||
|
||||
Use named volumes for module-specific storage:
|
||||
|
||||
```json
|
||||
"Mounts": [
|
||||
{
|
||||
"Type": "volume",
|
||||
"Target": "/app/data/",
|
||||
"Source": "<modulename>"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Modules with Host Binds
|
||||
|
||||
Use host binds for shared storage or device access:
|
||||
|
||||
```json
|
||||
"Binds": [
|
||||
"/srv/aziotedge/opc/opcpublisher/:/app/opc/opcpublisher/",
|
||||
"/dev/tpm0:/dev/tpm0"
|
||||
]
|
||||
```
|
||||
|
||||
### Modules with Privileged Access
|
||||
|
||||
For modules requiring device access (e.g., TPM):
|
||||
|
||||
```json
|
||||
"Privileged": true
|
||||
```
|
||||
|
||||
### Modules with Environment Variables
|
||||
|
||||
Configure modules via environment variables:
|
||||
|
||||
```json
|
||||
"env": {
|
||||
"OptionsClass__PropertyName": {
|
||||
"value": "value or ${VariableSubstitution}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Adding a New Module to a Manifest
|
||||
|
||||
To add a new module to a deployment manifest:
|
||||
|
||||
1. **Add module definition to `$edgeAgent`**:
|
||||
- Use `properties.desired.modules.<modulename>` as the key
|
||||
- Set appropriate `startupOrder` (consider dependencies)
|
||||
- Set `image` to `${MODULES.<modulename>}`
|
||||
- Configure `createOptions` (log rotation, binds, mounts)
|
||||
- Add environment variables if needed
|
||||
|
||||
2. **Add routing to `$edgeHub`**:
|
||||
- Use descriptive route name: `properties.desired.routes.<modulename>ToIoTHub`
|
||||
- Set route expression based on message flow
|
||||
- Use standard priority (0) and TTL (86400)
|
||||
|
||||
3. **Update system properties** (only if needed):
|
||||
- System modules (`edgeAgent`, `edgeHub`) are defined once
|
||||
- Runtime registry credentials are shared across manifests
|
||||
|
||||
## Example: Adding a New Module
|
||||
|
||||
```json
|
||||
{
|
||||
"modulesContent": {
|
||||
"$edgeAgent": {
|
||||
"properties.desired.modules.mynewmodule": {
|
||||
"version": "1.0",
|
||||
"type": "docker",
|
||||
"status": "running",
|
||||
"restartPolicy": "always",
|
||||
"startupOrder": 5,
|
||||
"settings": {
|
||||
"image": "${MODULES.mynewmodule}",
|
||||
"createOptions": {
|
||||
"HostConfig": {
|
||||
"LogConfig": {
|
||||
"Type": "json-file",
|
||||
"Config": {
|
||||
"max-size": "10m",
|
||||
"max-file": "10"
|
||||
}
|
||||
},
|
||||
"Mounts": [
|
||||
{
|
||||
"Type": "volume",
|
||||
"Target": "/app/data/",
|
||||
"Source": "mynewmodule"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"$edgeHub": {
|
||||
"properties.desired.routes.mynewmoduleToIoTHub": {
|
||||
"route": "FROM /messages/modules/mynewmodule/outputs/* INTO $upstream",
|
||||
"priority": 0,
|
||||
"timeToLiveSecs": 86400
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user