andreicscs-HoneyWire/Docs/architecture/hub/backend/provisioning.md

HoneyWire Hub Deployment Architecture

Overview

HoneyWire uses a centralized Hub to manage node provisioning, sensor configuration, deployment generation, and configuration reconciliation.

Each managed infrastructure node receives:

• a unique Node ID
• a generated Node API Key
• a dynamic deployment bundle generated by the Hub

The Hub acts as the single source of truth for all deployed sensors and runtime configuration state.

---

Configuration State

Pending Configuration

Whenever sensors are:

• added
• removed
• edited

the Hub sets:

nodes.pendingConfig = true

This indicates the deployed infrastructure configuration no longer matches the desired configuration stored in the Hub.

---

Configuration Revisions

Every generated deployment bundle receives a unique configuration revision:

HW_CONFIG_REV=rev_xxxxxxxx

rev_xxxxxxxx is a deterministic 12-char string for tracking config state.

This revision is embedded into all deployed sensors.

Purpose

Configuration revisions allow the Hub to:

• detect deployment drift
• verify successful synchronization
• reconcile desired vs active state

---

Active Revision

Once the last deployed sensor begins reporting heartbeats with the expected revision:

nodes.activeRevision = desiredRevision
nodes.pendingConfig = false

The node is considered synchronized.

---

Authentication Model

Node Authentication

HoneyWire uses API-key-based node authentication.

Nodes authenticate using:

Authorization: Bearer <NODE_API_KEY>

The Hub derives node identity internally from the API key.

Sensors never provide or control their own Node ID.

---

Sensor Runtime Variables

Sensors only require the following runtime variables:

HW_HUB_ENDPOINT
HW_HUB_KEY
HW_SENSOR_ID
HW_CONFIG_REV
HW_TEST_MODE

Node identity is resolved server-side by the Hub.

---

Manual Deployment Workflow

Typical Operator Flow

1. Create Node

The operator creates a node through the Fleet UI.

2. Configure Sensors

Sensors are selected from the Sensor Catalog and assigned to the node.

3. Generate Deployment

The node retrieves its deployment bundle from the deployment generation API endpoint.

4. Deploy Compose Stack

The generated compose file is deployed to the target infrastructure host.

5. Reconciliation

Sensors begin sending authenticated heartbeats containing:

HW_CONFIG_REV

The Hub validates the revision and marks the node as synchronized.

---

Preview vs Deployment

The Hub distinguishes between preview generation and production deployment:

• Preview Generator is used by the UI to show operators the compose preview. It is authenticated via the UI session and does not inject state tracking revisions.
• Node Deployment is used by the nodes to fetch their production configuration. It is authenticated via the Node API Key, tracks state, and injects revisions into the environment for synchronization.

---

Architecture Summary

HoneyWire follows a centralized reconciliation architecture:

• the Hub stores desired infrastructure state
• nodes authenticate using API keys
• deployments are generated dynamically
• sensors report active runtime revisions
• synchronization is verified through telemetry

This ensures:

• deterministic deployments
• drift detection
• centralized configuration management
• secure node authentication
• reproducible infrastructure state