Edgelet node YAML Specification
Edgelet nodes run on edge hosts and connect to the Controller so microservices can deploy locally. In YAML the resource kind stays Agent (remote SSH deploy) or LocalAgent (local container). Prose and UI labels use Edgelet node.
Deploy with iofogctl deploy -f agent.yaml. Update a running node with the AgentConfig kind (configuration updates) or Edgelet configuration on the device.
v3.8 requires Edgelet v1.0.0+ on every node. The Java ioFog Agent and v3.7 field agents are not supported. See Migrating to v3.8.0 and Legacy Agent (v3.7) for the v3.7.3 snapshot.
v3.8 field renames
| Legacy (v3.7) | v3.8 |
|---|---|
agentType | arch |
fogType / fogTypeId | arch / archId |
dockerUrl | containerEngineUrl |
dockerPruningFrequency | pruningFrequency |
| - | containerEngine: edgelet, docker, or podman |
Architectures: auto, amd64, arm64, riscv64, and arm (32-bit). Catalog and offline images use archId with the same four architecture names.
Default Edgelet image tag for the v3.8 release train: ghcr.io/eclipse-iofog/edgelet:1.0.0. Override under spec.package.container.image or spec.package.version for native binary installs.
Remote Edgelet node (Agent)
The Agent kind installs Edgelet on a remote host over SSH. Omit package for a native install with the default Edgelet package, or set package.container.image to run Edgelet as a container.
---
apiVersion: iofog.org/v3
kind: Agent
metadata:
name: meerkat
namespace: default
spec:
host: 30.40.50.6
ssh:
user: foo
keyFile: ~/.ssh/id_rsa
port: 22
config:
description: edgelet running on device
host: 30.40.50.6
latitude: 46.204391
longitude: 6.143158
arch: amd64
deploymentType: native
containerEngine: edgelet
containerEngineUrl: unix:///run/edgelet/containerd.sock
diskLimit: 50
diskDirectory: /var/lib/edgelet/
memoryLimit: 4096
cpuLimit: 80
logLimit: 10
logDirectory: /var/log/edgelet/
logFileCount: 10
statusFrequency: 10
changeFrequency: 10
deviceScanFrequency: 60
bluetoothEnabled: true
watchdogEnabled: false
gpsMode: auto
gpsScanFrequency: 60
gpsDevice: ''
edgeGuardFrequency: 0
abstractedHardwareEnabled: false
upstreamRouters: ['default-router']
routerConfig:
routerMode: edge
messagingPort: 5671
edgeRouterPort: 45671
interRouterPort: 55671
upstreamNatsServers:
- default-nats-hub
natsConfig:
natsMode: leaf
natsServerPort: 4222
natsLeafPort: 7422
natsMqttPort: 8883
natsHttpPort: 8222
jsStorageSize: 10g
jsMemoryStoreSize: 1g
pruningFrequency: 0
logLevel: info
availableDiskThreshold: 90
| Field | Description |
|---|---|
host | Hostname or IP that iofogctl SSHs into to install Edgelet. |
ssh | SSH user, private key path, and port (default 22). |
airgap | Set true for air-gapped installs. Pair with package and optional scripts. |
package | Edgelet package version or container image override. |
config | Runtime settings pushed to the Controller and Edgelet. See Configuration fields. |
scripts | Optional custom install scripts instead of default iofogctl procedures. |
Local Edgelet node (LocalAgent)
The LocalAgent kind deploys an additional Edgelet container on the local machine. LocalControlPlane already deploys a system Edgelet via spec.systemAgent (Quick Start (local)). Use LocalAgent when you need a second local node.
---
apiVersion: iofog.org/v3
kind: LocalAgent
metadata:
name: local
spec:
package:
version: 1.0.0
container:
image: ghcr.io/eclipse-iofog/edgelet:1.0.0
config:
description: edgelet running on device
host: 30.40.50.6
latitude: 46.204391
longitude: 6.143158
arch: amd64
deploymentType: native
containerEngine: edgelet
containerEngineUrl: unix:///run/edgelet/containerd.sock
diskLimit: 50
diskDirectory: /var/lib/edgelet/
memoryLimit: 4096
cpuLimit: 80
logLimit: 10
logDirectory: /var/log/edgelet/
logFileCount: 10
statusFrequency: 10
changeFrequency: 10
deviceScanFrequency: 60
bluetoothEnabled: true
watchdogEnabled: false
gpsMode: auto
gpsScanFrequency: 60
gpsDevice: ''
edgeGuardFrequency: 0
abstractedHardwareEnabled: false
upstreamRouters: ['default-router']
routerConfig:
routerMode: edge
messagingPort: 5671
edgeRouterPort: 45671
interRouterPort: 55671
upstreamNatsServers:
- default-nats-hub
natsConfig:
natsMode: leaf
natsServerPort: 4222
natsLeafPort: 7422
natsMqttPort: 8883
natsHttpPort: 8222
jsStorageSize: 10g
jsMemoryStoreSize: 1g
pruningFrequency: 0
logLevel: info
availableDiskThreshold: 90
Air-gapped deploy with registry credentials
For air-gapped remote hosts, set airgap: true, pin the Edgelet image, and optionally supply registry credentials and custom install scripts.
---
apiVersion: iofog.org/v3
kind: Agent
metadata:
name: meerkat
spec:
host: 30.40.50.6
ssh:
user: foo
keyFile: ~/.ssh/id_rsa
port: 22
airgap: true
package:
version: 1.0.0
container:
image: ghcr.io/eclipse-iofog/edgelet:1.0.0
registry: ghcr.io
username: foo
password: bar
scripts:
dir: /tmp/my-scripts
deps:
entrypoint: install_deps.sh
install:
entrypoint: install.sh
args:
- "--version=1.0.0"
- "--skip-config"
- "--skip-start"
uninstall:
entrypoint: uninstall.sh
config:
arch: amd64
deploymentType: native
containerEngine: edgelet
Package fields
| Field | Description |
|---|---|
package.version | Edgelet binary release tag for native installs (for example 1.0.0). Ignored when scripts.install.entrypoint is set; pass --version= in scripts.install.args instead. |
package.container.image | Edgelet container image (default train: ghcr.io/eclipse-iofog/edgelet:1.0.0). |
package.container.registry | Registry host for image pull during air-gapped install. |
package.container.username | Registry username when credentials are required. |
package.container.password | Registry password when credentials are required. |
package.wasm | Optional Wasm shim bundles for Edgelet Wasm runtime. See Wasm runtime. |
Installation script fields
Custom scripts override parts of the embedded Edgelet bootstrap. Files in scripts.dir are read on the operator machine and staged to /tmp/edgelet-scripts on the target host. See Setup Edgelet nodes for merge behavior, examples, and troubleshooting.
| Field | Description |
|---|---|
scripts.dir | Required when the scripts block is present. Directory on the operator machine containing install scripts. |
scripts.deps.entrypoint | Optional. Overrides dependency install (docker/podman). Empty means embedded install_deps.sh. |
scripts.deps.args | Optional arguments appended to the deps entrypoint. |
scripts.install.entrypoint | Optional. Overrides Edgelet binary or container install. Empty means embedded install.sh or install_container.sh. When set, iofogctl does not inject package.version or package.container.image; pass flags in scripts.install.args. |
scripts.install.args | Optional arguments appended to the install entrypoint (for example --version=1.0.0, --skip-config, --skip-start). |
scripts.uninstall.entrypoint | Optional. Overrides teardown on Agent delete. Empty means embedded uninstall.sh. |
scripts.uninstall.args | Optional arguments appended to the uninstall entrypoint (for example --remove-data). |
Only deps, install, and uninstall entrypoints are YAML-overridable. Prerequisites (check_prereqs.sh) and post-install layers always use embedded script names. When scripts.install.entrypoint is set, scripts.dir must also contain post-install scripts the bootstrap still runs.
Configuration fields
Specify runtime behavior under spec.config on Agent or LocalAgent. The same fields apply to AgentConfig (see below). Values can be changed after deploy with AgentConfig or on-device edgelet config.
| Field | Description |
|---|---|
description | Short description of the Edgelet node. |
latitude / longitude | Geo coordinates. Edgelet can auto-detect when online. |
arch | Node architecture: auto, amd64, arm64, riscv64, or arm. |
archId | Controller architecture ID (usually set by the API from arch). |
deploymentType | Install mode: native (default) or container. |
containerEngine | Runtime backend: edgelet (default on Linux), docker, or podman. |
containerEngineUrl | Engine socket URL. Default for edgelet: unix:///run/edgelet/containerd.sock. |
networkInterface | Network interface for agent traffic (dynamic or interface name). |
host | Hostname for router messaging and advertised ports. Defaults to deploy-time host. |
diskLimit | Disk quota in GiB for Edgelet data. |
diskDirectory | Data directory (default /var/lib/edgelet/). |
memoryLimit | Memory quota in MiB for message buffers. |
cpuLimit | CPU time limit as a percentage. |
logLimit | Log disk quota in GiB. |
logDirectory | Log directory (default /var/log/edgelet/). |
logFileCount | Number of rotated log files. |
statusFrequency | Status heartbeat interval in seconds. |
changeFrequency | Controller change poll interval in seconds. |
deviceScanFrequency | Device scan interval in seconds. |
bluetoothEnabled | Enable Bluetooth device scanning. |
watchdogEnabled | Kill orphan containers not started by Edgelet. |
gpsMode | GPS mode: auto, manual, dynamic, or off. |
gpsScanFrequency | GPS scan interval in seconds. |
gpsDevice | GPS device path when gpsMode is dynamic (for example /dev/ttyUSB2). |
edgeGuardFrequency | EdgeGuard hardware scan interval in seconds (0 disables). |
abstractedHardwareEnabled | Enable abstracted hardware services when supported. |
upstreamRouters | Upstream Skupper routers (Agent names or default-router). |
networkRouter | Network router Agent name or default-router. |
routerConfig.routerMode | Router mode: edge, interior, or none. |
routerConfig.messagingPort | Router messaging port (default 5671). |
routerConfig.edgeRouterPort | Edge router port when mode is interior (default 45671). |
routerConfig.interRouterPort | Interior router port when mode is interior (default 55671). |
upstreamNatsServers | Upstream NATS hubs when natsConfig.natsMode is leaf. |
natsConfig.natsMode | NATS mode: none, leaf, or server. |
natsConfig.natsServerPort | NATS client port (default 4222). |
natsConfig.natsLeafPort | NATS leaf node port (default 7422). |
natsConfig.natsClusterPort | NATS cluster port when mode is server. |
natsConfig.natsMqttPort | NATS MQTT port. |
natsConfig.natsHttpPort | NATS HTTP monitor port. |
natsConfig.jsStorageSize | JetStream file storage size (for example 10g). |
natsConfig.jsMemoryStoreSize | JetStream memory store size (for example 1g). |
pruningFrequency | Image prune interval in hours (replaces dockerPruningFrequency). |
logLevel | Log level (for example info or INFO). |
availableDiskThreshold | Disk usage threshold percentage before warnings. |
AgentConfig
The AgentConfig kind updates an Edgelet node that is already registered with the Controller. All spec fields are optional; only listed fields change.
Retrieve current config with iofogctl describe agent-config <NAME>. Apply with iofogctl deploy -f agent-config.yaml.
---
apiVersion: iofog.org/v3
kind: AgentConfig
metadata:
name: meerkat
spec:
description: agent running on VM
latitude: 46.204391
longitude: 6.143158
arch: riscv64
containerEngine: edgelet
containerEngineUrl: unix:///run/edgelet/containerd.sock
diskLimit: 50
diskDirectory: /var/lib/edgelet/
memoryLimit: 4096
cpuLimit: 80
logLimit: 10
logDirectory: /var/log/edgelet/
logFileCount: 10
statusFrequency: 10
changeFrequency: 10
deviceScanFrequency: 60
bluetoothEnabled: true
watchdogEnabled: false
gpsMode: auto
gpsScanFrequency: 60
gpsDevice: ''
edgeGuardFrequency: 0
abstractedHardwareEnabled: false
upstreamRouters: ['default-router']
routerConfig:
routerMode: edge
messagingPort: 5671
edgeRouterPort: 45671
interRouterPort: 55671
upstreamNatsServers:
- default-nats-hub
natsConfig:
natsMode: leaf
natsServerPort: 4222
natsLeafPort: 7422
natsMqttPort: 8883
natsHttpPort: 8222
jsStorageSize: 10g
jsMemoryStoreSize: 1g
pruningFrequency: 0
logLevel: INFO
availableDiskThreshold: 90
metadata.name must match the Edgelet node name on the Controller. Describe output may include a status block (daemon health, disk and CPU usage, available runtimes, and upgrade readiness).
EdgeGuard
EdgeGuard collects hardware details and builds a stable hardware signature for the device. When the signature changes, EdgeGuard deprovisions the Edgelet node from the ECN and removes running microservices. This helps detect tampering on nodes outside traditional datacenters.
Set edgeGuardFrequency to a positive interval in seconds to enable periodic scans. Use 0 to disable.