Skip to content

Configuration as code

Every Artek MQTT setting (connection profiles, publisher mappings, subscriptions, Sparkplug edge nodes and host applications, and the Sub module settings) is an Ignition 8.3 config resource on disk. You can keep it in source control, generate it, or edit it by hand, the same way as any other 8.3 config resource.

Where the files are

The resources live under the gateway's data folder:

data/config/resources/core/com.artek.mqtt.common/
data/config/resources/core/com.artek.mqtt.pub/
data/config/resources/core/com.artek.mqtt.sub/

Each resource's settings are in a config.json file.

Applying an edit made on disk

An edit to a config.json on disk does not take effect by itself. Ignition does not watch the filesystem, so after editing, trigger a config scan:

POST /data/api/v1/scan/config
X-Ignition-API-Token: <your gateway API token>

The scan is asynchronous. A few seconds after it returns, the module re-applies the change: it reconnects the edited profile, restarts the edited subscription, and so on.

How the change was made When it applies
Artek MQTT pages or the gateway web interface Immediately.
config.json edited on disk After a config scan (or a gateway restart).
tagProviderName in the Sub module settings Only after a gateway restart.

Unknown keys on disk

A config.json on disk that contains a key the resource does not have still loads, and the gateway log shows a warning naming the key. Check the log after a scan to catch typos.

Secrets on disk

Passwords and TLS client keys are stored encrypted in config.json. See Security.

The web API

The Artek MQTT pages use a web API under /data/artek-mqtt-*/web/... for connection profiles, publisher mappings, edge nodes, subscriptions and host applications. It requires a signed-in gateway session and is protected against cross-site request forgery. It behaves as follows:

  • Unknown fields are refused. A create or modify body with a key the resource does not have, at the top level or nested (for example tls.hostNameVerification or devices[0].tagpath), gets 400 naming the key, the field most likely meant and the accepted fields, and nothing is applied.
  • A listed entry can be posted back as-is. The fields the list returns (name, status, masked secrets) are accepted on create and modify. Delete takes name only.
  • Partial modifies merge. Fields you leave out keep their current values (see Editing a profile).
  • Answers come only after the change is applied. A change that fails while being saved returns 500 and is audited as a failure. A change not applied within 20 seconds is reported as failed (the log and audit record show "outcome unknown").
  • Configure on the master. On a redundant pair, the backup refuses every create, modify and delete with 409 and a message naming the master (see Security).
  • Invalid names are refused. Resource names containing control characters, or that are too long, are refused.

The read-only status routes (/data/artek-mqtt-<module>/status) need no sign-in; see Verify the install.