Deployment groups & releases

Target devices and roll out firmware safely with deployment groups — conditions, concurrency, failure limits, and releases.

Written By Josh Kalderimis

Last updated About 2 months ago

A deployment group targets a set of devices and tells them which firmware to run, with controls for how fast and how safely the rollout happens. Each firmware version published to a group is a release.

Naming: the web UI says deployment group / release. The nh CLI still calls the object a deployment.

How it works

  1. Targeting conditions decide which devices the group applies to (version + tags).

  2. The current release is the firmware those devices should run.

  3. When the group is active and its release is newer than a matching device, NervesHub offers the update. A distributed orchestrator runs the rollout within your limits.

A group is pinned to one platform and architecture (set from its first release), so every future release stays compatible. See Deployment orchestration for the model.

Create a group

Web UI → Deployment Groups → New:

  1. Pick the firmware for the first release (fixes platform + architecture).

  2. Set targeting conditions.

  3. Set rollout options.

  4. Save, then mark it active.

Targeting conditions

Condition

Meaning

Version

Optional version requirement a device must satisfy.

Tags

Device tags to match.

Tag operator

and = require all tags · or = match any tag.

If a device matches multiple groups, NervesHub prefers the most specific tag match.

Rollout options

Option

Default

What it controls

Concurrent updates

10

Max devices updating at once.

Queue management

FIFO

Update order — FIFO or LIFO.

Delta updatable

on

Send firmware deltas instead of full images.

Failure threshold

50%

Fleet failure rate that marks the group unhealthy.

Device failure threshold

3

Failures allowed per device.

Device failure rate

5 / 180s

Failures per window before a device is penalized.

Penalty timeout

1440 min

How long a penalized device waits before retrying.

Release network interfaces

any

Restrict updates to wifi / ethernet / cellular.

Release tags

—

Extra tags applied with the release.

Connecting code

—

Code run on a device as it connects.

Priority queue (optional)

A faster lane for devices far behind:

Option

Default

What it controls

Priority queue enabled

off

Turn the fast lane on.

Priority concurrent updates

5

Concurrency for the fast lane.

Firmware version threshold

—

Devices below this version use the fast lane.

Publish a new release

  1. Publish new firmware to the product (nh firmware publish or web UI).

  2. In the group, select it as the new release.

  3. The current release updates and the orchestrator offers it under your rollout rules.

Only firmware matching the group's platform + architecture can be selected.

Roll back

Set an earlier release (or known-good firmware) as the current release. Matching devices are offered it on their next check-in, using the same rollout rules.

From the CLI

nh deployment list

nh deployment create

nh deployment update <deployment> <key> <value>

See the CLI reference.

Related