Skip to content
GitHub

Install the Edge Relay with Helm or Quadlet

Two supported ways, both containers, both starting on boot and restarting when they die: the Helm chart on a cluster, and a Podman Quadlet unit on a box that isn’t in one. A bare podman run from an SSH session is not one of them. That’s how an edge box quietly stops forwarding the first time somebody logs out and the container goes with them, and nobody notices until the historian has a hole in it. There’s no Docker path either.

Whichever way you go, the relay needs two things: a broker to publish to, and a Sparkplug group id. The image pulls with no login.

Both ways read the same document: the devices to poll and the tags to read on them.

{
"devices": [
{
"id": "press-01",
"name": "Press 1",
"protocol": "opcua",
"address": "opc.tcp://press-01.local:4840",
"enabled": true,
"pollIntervalMs": 1000
}
],
"tags": [
{
"deviceId": "press-01",
"name": "Zone1_Temp",
"address": "ns=2;s=Zone1.Temp",
"dataType": "float",
"enabled": true
}
]
}

These are the same device and tag shapes the Gateway’s API takes, checked with the same rules: a device needs a protocol HotLoop knows, and a tag needs a device that exists. On top of that the relay refuses a device id declared twice and a tag pointing at a device that was never declared, the two mistakes a hand-edited file makes that a database would have caught for you.

The local file is read at start, and again when a push is cleared. Change it, restart the relay. It isn’t watched, on purpose. A device file pushed from a Gateway is the one that applies live, and it wins over this one for as long as it exists.

The file can also carry a discovery list of MQTT brokers the relay listens to for devices that announce themselves, read-only. The reference has the format.

A device’s config block can hold credentials, like an OPC UA username and password. They sit in that file in the clear, and the relay has no API to hide them behind, so where the file lives matters. Both paths below cover it.

Terminal window
helm repo add hotloop https://hotloop.io/hotloop
helm repo update
helm install press-line-3 hotloop/hotloop-edge-relay \
--version 4.23.2 --namespace hotloop --create-namespace \
--set edgePublish.broker=tcp://gateway.plant.local:1883 \
--set edgePublish.group=Plant1 \
--set edgePublish.node=press-line-3 \
-f devices.yaml

edgePublish.broker and edgePublish.group are required, and the chart refuses to render without them. Set edgePublish.node too. Left empty, it’s the pod’s hostname, and a Deployment’s pod gets a new name every time it’s replaced. After the next node drain, the Gateway’s fleet and every Sparkplug host upstream see a brand new edge node, and the one you registered shows offline.

Broker password: put it in edgePublish.password, or name a Secret with a password key in edgePublish.existingSecret. Turn on edgePublish.tls if the broker speaks TLS.

devices.yaml carries the same two lists as the device file, under devices: and tags::

devices:
- id: press-01
name: Press 1
protocol: opcua
address: "opc.tcp://press-01.local:4840"
enabled: true
pollIntervalMs: 1000
tags:
- deviceId: press-01
name: Zone1_Temp
address: "ns=2;s=Zone1.Temp"
dataType: float
enabled: true

Those end up in a ConfigMap and in the Helm release record, and anybody who can read ConfigMaps in the namespace can read them. If a device carries a password, put the whole device file in a Secret under the key devices.json and name it instead. The Secret is mounted in place of the ConfigMap, and devices and tags are ignored:

Terminal window
kubectl -n hotloop create secret generic press-devices --from-file=devices.json
helm upgrade press-line-3 hotloop/hotloop-edge-relay --version 4.23.2 \
--reset-then-reuse-values --set devicesSecret=press-devices

--reset-then-reuse-values, not --reuse-values. The plain one replays the values the release already has and skips any default a newer chart added. Run it on a relay installed at 4.16.0 and it drops pushedDevicesFile, so a push goes right back to dying on the read-only mount, and nothing fails to tell you.

The install notes will then warn that no devices are configured. They’re counting the chart’s devices list, which you left empty on purpose. Check /status instead:

Terminal window
kubectl -n hotloop logs deploy/press-line-3
kubectl -n hotloop port-forward svc/press-line-3 8081:8081
curl localhost:8081/status

The forward queue lives on its own PVC, 256Mi by default (persistence.size), so buffered readings survive the pod moving. The same volume holds the OPC UA client certificate and its trust store at /data/opcua-client-pki, so a secured server trusts the relay once, not after every restart.

edgePublish.queueMaxBytes is 64 MiB by default (67108864), where it used to be 0, unbounded. Past the cap the oldest readings are dropped and counted. That is about 248,000 readings, about two minutes at 2,000 readings a second, so size it from your own rate, about 240 bytes a reading with short tag names (measured on the same queue in Edge 4.21.1), and keep it comfortably under persistence.size. Set it to 0 and it is unbounded again: a long enough broker outage then fills the volume instead of dropping old readings, a full volume is a second outage stacked on the first, and the install notes say so. A relay upgraded with --reuse-values keeps whatever it had.

persistence.enabled=false boots since 4.17.0 (on 4.16.0 it killed the relay at boot), with an emptyDir at /data capped at persistence.size. Know what that costs before you pick it: every time the pod is replaced (a node drain, an eviction, a kubectl delete pod, a helm upgrade that rolls it) it loses the forward queue and every reading buffered in it, any pushed device file (the relay quietly goes back to the chart’s devices), and the OPC UA client certificate, so every secured server has to trust the relay again. The install notes print that warning. Fine for a trial. For a relay whose readings matter, keep the PVC.

A pushed device file lives on that same volume, at /data/pushed-devices.json (pushedDevicesFile in the chart’s values), and wins over the chart’s devices for as long as it exists, through restarts, reschedules, and a helm upgrade that changes devices. The relay logs which file it booted from. To go back to the chart’s list, clear the push with DELETE /api/fleet/{id}/config on the Gateway while the relay is connected, and it switches to the chart’s list on the spot. A push applies live as well, with no restart.

For a Pi or an industrial PC outside any cluster. Quadlet turns the container into a real systemd service: it starts on boot with nobody logged in, restarts when it dies, and logs to the journal. This unit was run on Podman 4.9.3, and its keys were checked against the quadlet binary of Podman 5.8.6. Raspberry Pi OS Bookworm ships 4.3, which has no Quadlet at all, so use Trixie or newer.

The unit and its data volume are in deploy/quadlet/ in the HotLoop repository, next to devices.example.json. Make the directories first:

Terminal window
sudo mkdir -p /etc/containers/systemd /etc/edge-relay

Save this as /etc/containers/systemd/edge-relay.container, and change the broker, group, and node for this box:

[Unit]
Description=HotLoop Edge Relay
Documentation=https://docs.hotloop.io/edge-relay/reference/
After=network-online.target
Wants=network-online.target
[Container]
# Every box tracks :stable, so this line never needs editing.
Image=ghcr.io/hotloop-io/hotloop-edge-relay:stable
AutoUpdate=registry
ContainerName=edge-relay
# The image has no shell or curl, so the binary asks itself. A JSON array,
# not a string, because a string runs through /bin/sh -c and there isn't one.
HealthCmd=["/edge-relay", "--healthcheck"]
HealthInterval=10s
HealthRetries=3
HealthStartPeriod=20s
Notify=healthy
# Podman 4.9 reads Notify=healthy as plain true. Without this line a broken
# release is not rolled back there.
PodmanArgs=--sdnotify=healthy
# The image digest, written by the ExecStartPre below, for the Gateway's fleet list.
EnvironmentFile=/run/edge-relay/relay.env
Environment=HOTLOOP_EDGE_PUBLISH_BROKER=tcp://gateway.example.local:1883
Environment=HOTLOOP_EDGE_PUBLISH_GROUP=Plant1
Environment=HOTLOOP_EDGE_PUBLISH_NODE=press-line-3
# The outage queue's limit, 64 MiB.
Environment=HOTLOOP_EDGE_PUBLISH_QUEUE_MAX_BYTES=67108864
Environment=HOTLOOP_EDGE_RELAY_DEVICES_FILE=/etc/edge-relay/devices.json
# Where a pushed device file lands, instead of failing on the read-only
# mount below. It wins over the file above for as long as it exists.
Environment=HOTLOOP_EDGE_RELAY_PUSHED_FILE=/data/pushed-devices.json
Environment=HOTLOOP_LOG_LEVEL=info
# Delete this line if the broker takes anonymous connections.
Secret=edge-relay-broker-password,type=env,target=HOTLOOP_EDGE_PUBLISH_PASSWORD
Volume=/etc/edge-relay/devices.json:/etc/edge-relay/devices.json:ro,Z
Volume=edge-relay-data.volume:/data
# Only reachable from this host. /status has no auth, on purpose.
PublishPort=127.0.0.1:8081:8081
User=65532:65532
ReadOnly=true
Tmpfs=/tmp
NoNewPrivileges=true
DropCapability=all
[Service]
Restart=always
RestartSec=5
# Exit status 75 is a relay stopping because an operator approved an update.
SuccessExitStatus=75
RuntimeDirectory=edge-relay
ExecStartPre=/bin/sh -c '/usr/bin/podman image exists ghcr.io/hotloop-io/hotloop-edge-relay:stable || /usr/bin/podman pull ghcr.io/hotloop-io/hotloop-edge-relay:stable'
ExecStartPre=/bin/sh -c 'echo HOTLOOP_IMAGE_DIGEST=$$(/usr/bin/podman image inspect --format "{{.Digest}}" ghcr.io/hotloop-io/hotloop-edge-relay:stable) > /run/edge-relay/relay.env'
# A bad image fails three healthchecks in about a minute, and then it is rolled back.
TimeoutStartSec=120
[Install]
WantedBy=multi-user.target

And this as /etc/containers/systemd/edge-relay-data.volume. It holds the forward queue and any pushed device file. It’s a named volume so it survives a podman system prune, and so its ownership matches the container’s non-root user without a chown:

[Volume]

Put the device file at /etc/edge-relay/devices.json, then:

Terminal window
printf '%s' 'your-broker-password' | \
sudo podman secret create edge-relay-broker-password -
sudo systemctl daemon-reload
sudo systemctl start edge-relay.service
sudo systemctl status edge-relay.service
curl localhost:8081/status

Broker takes anonymous connections? Skip the secret and delete the Secret= line. On an isolated OT network that’s a real setup, not a mistake to work around. The :Z on the device file mount is for SELinux, and harmless on a distro without it.

To change devices from the box: edit the file, then sudo systemctl restart edge-relay.service. A device file pushed from the Gateway needs none of that, because it applies live. While a push is in place it is what the relay runs and boots from, so your edits to the local file do nothing until you clear the push with DELETE /api/fleet/{id}/config on the Gateway. When something looks wrong, sudo journalctl -u edge-relay.service before anything else. The relay says which file it is on, and why it rejected a device file or a push, and reading that takes less time than second-guessing your JSON.

The unit follows :stable, and Podman moves it once its timer is on:

Terminal window
sudo systemctl enable --now podman-auto-update.timer

When the timer fires, Podman pulls :stable, and if the digest changed it restarts the unit on the new image. The unit isn’t up until the relay’s own healthcheck passes, so if the new image never does, Podman puts the previous one back and starts that. A release that can’t start costs a few minutes on one box, and not a relay that stays down. The forward queue and a pushed device file live on the data volume, which a new image doesn’t touch. The Gateway’s fleet list shows each relay’s version and image digest and logs a line when one changes.

Podman updates every labeled container on the machine when it runs, not just this one. A site that wants a person to say when has two opt-ins, both in deploy/quadlet/. edge-relay-hold.conf holds updates until an admin on the Gateway approves them with POST /api/fleet/{id}/update, and it needs the timer off for the whole machine. update-window.conf lets the timer fire only in a window, like Sunday at 03:00. The Gateway can’t tell you an update is waiting, only what each relay runs now. The hold was run with a real update held for 30 seconds, then taken on approval, and the reference page, Updating a relay, has everything it does and can’t do.

Fleet management is off in the Gateway until you turn it on, because a Gateway with no relays has no broker to point it at. Set HOTLOOP_FLEET_ENABLED to true and point HOTLOOP_FLEET_BROKER at the same broker the relays publish to, with HOTLOOP_FLEET_USER, HOTLOOP_FLEET_PASSWORD, and HOTLOOP_FLEET_TLS if it needs them. The Gateway chart has no fleet values of its own, so they go in its extraEnv:

extraEnv:
- name: HOTLOOP_FLEET_ENABLED
value: "true"
- name: HOTLOOP_FLEET_BROKER
value: tcp://gateway.plant.local:1883

Then register each relay by its group and node. Registering is on purpose: a relay that just shows up on the broker isn’t a fleet member until somebody says it is. POST this to /api/fleet as a user with fleet.write:

{
"id": "press-line-3",
"name": "Press line 3",
"group": "Plant1",
"nodeId": "press-line-3",
"statusUrl": "http://press-line-3.hotloop.svc:8081"
}

statusUrl is optional. Without it the Gateway knows online and offline from births and deaths. With it, the Gateway also polls the relay’s /status for queue depth and device counts, and a relay it can’t reach shows as unreachable, never as a healthy zero. The Quadlet unit above only publishes 8081 on 127.0.0.1, so a Gateway on another box can’t reach /status until you change PublishPort=, and then it’s reachable by anyone on that network too.

From then on the Gateway tracks the relay and can send it POST /api/fleet/{id}/rebirth, POST /api/fleet/{id}/restart, POST /api/fleet/{id}/update or POST /api/fleet/{id}/config. That last one is the push, which lands from 4.17.0 and never did on 4.16.0, and applies live from 4.18.10. DELETE /api/fleet/{id}/config clears a push, and the relay goes back to its local file on the spot. All of this is API only: there’s no Fleet screen in the Gateway’s UI. Before you rely on any of that, lock the broker’s ACL down so only the Gateway can publish commands and device files. The overview says why.