Skip to main content

Neat CICD Infrastructure reporting

Kerrigan uses an AWS IoT Core profile acquired through activation-code pairing to report its host and fleet state to Neat CICD Infrastructure (Vulcan). Reporting failures are isolated from local fleet operations.

For MQTT topics, report frequency, payload fields, status derivation, and cloud consumer requirements, see the MQTT State Reporting API.

Configure cloud pairing​

From the Admin Console's Vulcan page, select the cloud environment and get an activation code. An authorized backoffice operator claims that code to complete pairing. Kerrigan generates and retains its private key locally; no credential archive is downloaded or uploaded.

See Pair Kerrigan with a Cloud Environment for the Admin Console and CLI procedures, approval flow, and security model.

For externally managed or air-gapped configurations, Fleet Manager can still read a profile and its credential files from a protected filesystem location:

KERRIGAN_VULCAN_PROFILE=/secure/path/kerrigan-iot-profile.yaml ./start.sh

The externally managed profile's cluster_id, thing_name, and client_id must be identical. Certificate paths are resolved relative to the YAML file.

Reports​

One shared mutual-TLS MQTT connection publishes:

  • a complete fleet snapshot, including rolling controller and uplink utilization, to publish_topics.status every 60 seconds and whenever target state changes;
  • a compact liveness message to publish_topics.heartbeats;
  • compact host state to the named AWS IoT Device Shadow host.

Fleet snapshots are limited to 120 KiB. Host shadow updates are limited to 8 KiB. An oversized fleet first omits optional details and sets details_omitted: true, preserving every device and its readiness blockers. Mandatory inventory that still exceeds the limit is rejected as a complete document. Inspect connector reporting_errors for failing stages; individual stages retry after five seconds and repeated error logging is rate-limited. A local MQTT enqueue success does not confirm broker acknowledgment.

Tune intervals with:

KERRIGAN_VULCAN_REPORTING_INTERVAL_SEC=60
KERRIGAN_VULCAN_HEARTBEAT_INTERVAL_SEC=30
KERRIGAN_VULCAN_KEEPALIVE_SEC=60

One-shot staging validation​

After extracting a real profile, publish one state snapshot, heartbeat, and host-shadow update without starting the long-running Fleet Manager:

kerrigan-vulcan-smoke \
  --vulcan-profile /secure/path/kerrigan-iot-profile.yaml \
  --db-path .kerrigan/kerrigan.db

The command waits for the named shadow's accepted or rejected response and returns a non-zero status on failure.

Infrastructure dependency​

The AWS IoT policy managed by Neat CICD Infrastructure permits the application status, heartbeat, event, command, claim, and offer topic namespaces scoped to the connected Thing name. It also grants narrowly scoped publish and response permissions for the named Device Shadow topics under $aws/things/{thing_name}/shadow/name/host/..., so fleet reporting, command events, and host-shadow updates use the same appliance identity.