QoS and sessions
QoS 0/1/2 on the KubeMQ MQTT connector — the QoS each pattern requires, ack-on-PUBACK for Queues, node-local sessions, and why retain is silently dropped.
The KubeMQ MQTT connector supports QoS 0, 1, and 2. The effective QoS interacts with KubeMQ
pattern semantics in non-obvious ways — Queue consumption requires QoS ≥ 1 and uses PUBACK as its
acknowledgement signal. Sessions are in-memory and node-local: a clean_session=false
reconnect to the same broker node restores subscriptions.
Retain is silently dropped, and there are no durable subscriptions. A runtime PUBLISH with the
retain flag returns a success PUBACK (0x00) but the retain is ignored — no retained message is
stored. A CONNECT that sets a Will with retain is refused with CONNACK 0x9A
(retain-not-supported). Do not design around retained messages or durable (cross-restart)
subscriptions on this connector; use the Events-Store pattern when you need persistence.
QoS levels
| QoS | Wire semantics | KubeMQ pattern constraints |
|---|---|---|
| 0 — at-most-once | Fire-and-forget; no PUBACK | Events / Events-Store publish and subscribe: allowed |
| 1 — at-least-once | Publish: PUBACK required; subscribe: PUBACK on each delivery | Required for Queue consume ($share); recommended for RPC |
| 2 — exactly-once | Full PUBREC / PUBREL / PUBCOMP handshake | Supported at the MQTT layer; routed identically to QoS 1 |
The broker advertises MaxQos = 2 (configurable via CONNECTORSMQTT_CAPABILITIES_MAX_QOS).
If a subscriber requests a higher QoS than the publisher used, delivery QoS is
min(subscribe QoS, publish QoS) per standard MQTT semantics — a pure MQTT-layer operation that
does not affect KubeMQ routing.
QoS per pattern
Events and Events-Store
Any QoS is permitted. QoS 0 is common for high-throughput telemetry where occasional loss is
acceptable; QoS 1 is recommended for reliable delivery. Events-Store always stores messages durably
on the KubeMQ side regardless of MQTT QoS — but over MQTT, Events-Store subscriptions are always
StartNewOnly: there is no historical replay, regardless of QoS or session state.
Queues
| Operation | Required QoS | Notes |
|---|---|---|
Produce (publish to queues/<ch>) | Any | QoS 0 produce is accepted; no MQTT-layer acknowledgement guarantee |
Consume ($share/<g>/queues/<ch>) | ≥ 1 | A QoS 0 shared-queue subscribe is rejected with SUBACK 0x83 |
Ack-on-PUBACK model. A Queue message is acknowledged to KubeMQ when the broker receives the PUBACK from the consuming client. Until the PUBACK arrives, the message stays in-flight. See Queues for the full consume model.
Commands and Queries (RPC)
RPC is MQTT 5.0 only. QoS 1 is required on both the $reply/<clientID>/... subscribe and the
commands/ or queries/ publish. See Commands and
Queries.
Queue ack timeout and redelivery
The connector tracks one in-flight Queue message per MQTT client. If no PUBACK arrives within
QueueAckTimeoutSeconds (default 30 s, via CONNECTORSMQTT_QUEUE_ACK_TIMEOUT_SECONDS), it
negatively acknowledges the message to KubeMQ and the message is redelivered to the next available
consumer.
| Event | KubeMQ action |
|---|---|
| PUBACK received within timeout | Acknowledge — message removed from the queue |
No PUBACK within QueueAckTimeoutSeconds | Negative-ack → redeliver to another consumer |
| Client disconnects with a pending delivery | Immediate negative-ack → requeue (no message loss) |
The disconnect-with-pending behaviour means a clean shutdown without PUBACK causes immediate requeue — the correct durability guarantee.
Graceful shutdown
When the KubeMQ server shuts down, the connector sends DISCONNECT reason code 0x8B
(server-shutting-down) to all connected clients, and any in-flight Queue messages are immediately
negatively acknowledged and requeued.
Sessions
In-memory and node-local
Sessions are stored in memory only, on the node that holds the connection. There is no cross-node session replication.
| Property | Value |
|---|---|
| Storage | In-memory |
| Scope | Node-local |
| Max session expiry | 3600 s (CONNECTORSMQTT_CAPABILITIES_MAX_SESSION_EXPIRY_SECONDS) |
| Max message expiry | 86400 s (CONNECTORSMQTT_CAPABILITIES_MAX_MESSAGE_EXPIRY_SECONDS) |
clean_session=false (3.1.1) / CleanStart=false (5.0)
When a client reconnects with clean_session=false to the same node, the broker restores its
active subscriptions and any pending (undelivered) messages for those subscriptions.
Reconnecting to a different node in a multi-node cluster does not restore the session — sessions are node-local. Clients that need durable sessions in a clustered environment should pin to the same node or use the Events-Store pattern for replay.
clean_session=true / CleanStart=true
The broker discards the previous session on connect — all subscriptions and pending deliveries are cleared. This is the recommended setting for stateless consumers and is what the examples use.
Session takeover
If a client reconnects with the same ClientID while the previous connection is still active,
the broker performs a takeover: the old connection is closed and the new one inherits the session
state (when clean_session=false).
ReceiveMaximum and inflight limits
| Setting | Default | Env var |
|---|---|---|
ReceiveMaximum | 1024 | CONNECTORSMQTT_CAPABILITIES_RECEIVE_MAXIMUM |
MaxInflight | 8192 | CONNECTORSMQTT_CAPABILITIES_MAX_INFLIGHT |
These caps apply per broker, not per client. When ReceiveMaximum is reached on a connection,
the broker stops delivering new messages until outstanding PUBACKs are received.
Related
Protocol versions
The 3.1.1 vs 5.0 feature matrix — including which capabilities require QoS ≥ 1 and MQTT 5.0.
Topic mapping
$share Queue consume, the $reply RPC namespace, and the prefix grammar QoS rules attach to.
Reason codes
The reason-code reference — including 0x83 (QoS 0 queue), 0x8B (shutdown), and 0x9A (Will-retain).
Was this page helpful?
Protocol versions
MQTT 3.1.1 vs MQTT 5.0 on the KubeMQ connector — the feature matrix, what is 5.0-only (RPC, $share Queue consume, User Properties), and why 3.1 is rejected.
Topic mapping
How the KubeMQ MQTT connector maps topics to patterns and channels — the prefix grammar, slash-to-dot, wildcards, $share consume, and $reply RPC replies.