Push Retained MQTT Configuration for Late-Joining Devices

A retained MQTT message is the broker's memory: the broker keeps the last retained message per topic and replays it to every new subscriber the moment they connect. This blueprint uses that mechanism for fleet configuration. io.kestra.plugin.mqtt.Publish with retain: true publishes a JSON config document to config/<environment>, so a device that boots three hours after the push still receives the current settings on subscribe, no polling and no config server required. Because the push is a Kestra flow, every config change arrives through a reviewed, versioned, auditable path instead of whoever had broker credentials.

How it works

1. Typed inputs define the change: environment is a SELECT that picks the target topic, and log_level plus telemetry_interval_seconds are the settings being rolled out, constrained to valid values by their input types.
2. push_config (io.kestra.plugin.mqtt.Publish) connects to the broker from the MQTT_SERVER secret and publishes the config as a JSON map to config/{{ inputs.environment }} with retain: true and qos: 1. The broker replaces the previously retained message on that topic and delivers the new one to current and future subscribers.
3. The document carries schema_version for forward compatibility and execution_id plus pushed_at for provenance, so any device or engineer can trace the active config to the exact execution that produced it.
4. confirm posts the environment, settings, and publish count to Discord.
5. The errors block posts a distinct Discord alert on failure, stating explicitly that devices still hold the previous retained config, which is the operationally important fact.

What you get

• Last-known-good configuration delivered automatically to late-joining and rebooting devices.
• Per-environment isolation: dev, staging, and production each retain their own document on their own topic.
• Config provenance embedded in the payload, linking what devices run to a Kestra execution.
• A change feed in Discord, so nobody discovers a config change by observing device behavior.

Who it's for

• IoT platform teams distributing device settings without standing up a dedicated config service.
• Operations teams that need environment-scoped rollouts with an audit trail.
• Anyone governing who may change fleet configuration and proving what changed when.

Why orchestrate this with Kestra

Retained messages are powerful and dangerous for the same reason: whatever was published last is what every new device gets, forever. Routing pushes through a Kestra flow means the payload shape is fixed in reviewed YAML, values are constrained by typed inputs, credentials live in secrets, and the execution history is the config changelog. Store the flow in Git with Kestra's version control integration and config changes get pull-request review before they can reach a single device.

Prerequisites

• An MQTT broker reachable from Kestra. Public test brokers accept anonymous connections; for authenticated brokers, add the username and password properties to the task from secrets.
• Devices subscribing to config/<environment> on boot, applying the retained document they receive.
• A Discord incoming webhook for confirmations and failure alerts.

Secrets

• MQTT_SERVER: broker URI, e.g. tcp://broker.example.com:1883.
• DISCORD_WEBHOOK_URL: Discord incoming webhook URL.

Quick start

1. Add the MQTT_SERVER and DISCORD_WEBHOOK_URL secrets to your Kestra namespace.
2. Execute the flow with the default inputs.
3. Connect a fresh subscriber afterwards, e.g. mosquitto_sub -t config/dev, and confirm it immediately receives the retained document even though it subscribed after the push.
4. Adjust the config fields in the from map to your device schema, bumping schema_version when the shape changes.

How to extend

• Add device-group topics such as config/{{ inputs.environment }}/sensors for finer-grained rollouts.
• Gate production pushes with a Kestra approval step before the publish task.
• Clear a retained config by publishing an empty retained payload to the same topic from a companion flow.
• Pair with the command dispatch blueprint: retained messages for state, plain QoS 1 messages for actions.

Links

• MQTT plugin documentation
• MQTT retained messages explained