Channel Mapping
The reference for how a RabbitMQ AMQP 0-9-1 queue maps to a KubeMQ Queue channel — the amqp.{vhost}.{queue} grammar, charset, and property/header mapping.
This is the master reference for how the embedded KubeMQ RabbitMQ (AMQP 0-9-1) connector maps an AMQP queue to a KubeMQ Queue channel. Every AMQP queue — regardless of which exchange or routing key delivered to it — is backed by exactly one KubeMQ Queue channel. Exchanges and bindings are virtual connector-side routing; the queue is the only durable object.
Everything is a Queue. The connector mirrors AMQP routing concepts (direct / fanout / topic / headers exchanges, bindings, RPC) on top of the single KubeMQ Queue primitive. See Architecture for the virtual-routing model.
Grammar
Every AMQP queue maps to exactly one KubeMQ Queue channel:
amqp.{vhost}.{queue}
└┬─┘ └──┬──┘ └──┬──┘
│ │ └─ the AMQP queue name
│ └─ the vhost segment (AMQP "/" → DefaultVhost, literal "default")
└─ fixed connector prefixThe mapping is mappedChannelPrefix + vhost + "." + queue.
| AMQP queue | Vhost | KubeMQ channel |
|---|---|---|
orders | / (default) | amqp.default.orders |
hello | / | amqp.default.hello |
probe.q | / | amqp.default.probe.q |
jobs | workers | amqp.workers.jobs |
Constraints
| Constraint | Rule | Violation |
|---|---|---|
| Length | Max 255 chars (prefix + vhost + queue). | 406 precondition-failed at queue declaration. |
| Charset | Queue/vhost names must NOT contain ;, :, *, >, whitespace, or end with .. | 406 (queue) / 402 (vhost). |
| Reserved vhost | The literal "default" vhost is reserved and cannot be client-created — reach it via /. | 402 invalid-path (connector source); a running broker may surface 403 "no access to this vhost" on a direct connect. |
Reserved default vhost + name charset (gotcha #8). Connect to vhost / (which maps to
the default segment); connecting directly to a vhost literally named default is rejected
(402 invalid-path per the connector source; a running broker may surface
403 "no access to this vhost"). Names containing ;, :, *, >, whitespace, or a
trailing . are rejected. See
Migrating from RabbitMQ for the
rename-before-migration checklist.
Cross-protocol interoperability
Because the backing store is a normal KubeMQ Queue channel, a message published over AMQP to
amqp.default.orders is consumable by a gRPC/REST queue client on the same channel, and
vice-versa. The AMQP queue and the KubeMQ Queue channel are the same object viewed through two
protocols.
Property / header ⇄ tag / metadata mapping
AMQP basic properties → KubeMQ tags
Tag namespace amqp.*. An absent property produces no tag.
| AMQP property | KubeMQ Tag | Notes |
|---|---|---|
| content-type | amqp.content-type | |
| content-encoding | amqp.content-encoding | |
| delivery-mode | amqp.delivery-mode | |
| priority | amqp.priority | carried as a tag; priority ordering itself is inert |
| correlation-id | amqp.correlation-id | |
| reply-to | amqp.reply-to | rewritten for direct-reply-to |
| expiration | amqp.expiration | also → Policy.ExpirationSeconds |
| message-id | amqp.message-id | UUID minted if absent |
| timestamp | amqp.timestamp | Unix seconds |
| type | amqp.type | |
| user-id | amqp.user-id | validated vs ClientID when auth enabled |
| app-id | amqp.app-id | |
| (routing context) | amqp.exchange, amqp.routing-key | always set on delivery |
AMQP headers ⇄ KubeMQ metadata
| Direction | Behavior |
|---|---|
| AMQP → KubeMQ | Headers are wrapped as Metadata = {"amqp_headers":{...}} (metadataEnvelopeKey = "amqp_headers"). Always set, even for nil/empty headers ({"amqp_headers":{}}). E.g. header trace=abc-123 → metadata {"amqp_headers":{"trace":"abc-123"}}. |
| KubeMQ → AMQP | Native (non-enveloped) gRPC metadata surfaces as the AMQP header x-kubemq-metadata (headerKubemqMetadata = "x-kubemq-metadata"). E.g. gRPC metadata="native-metadata" → AMQP delivery header x-kubemq-metadata: native-metadata. |
Special headers:
x-delay→Policy.DelaySeconds(stripped on delivery);x-deathtrail reconstructed for dead-lettering;expirationmoved tox-death[0].original-expirationwhen dead-lettered.
The {"amqp_headers":{...}} envelope is what a gRPC/REST consumer sees; a pure
AMQP→AMQP round-trip surfaces headers natively. Treat the envelope as an interop concern,
not a default-path surprise.
Related
Architecture
The everything-is-a-Queue model and how virtual exchanges and bindings route into channels.
Getting Started
Connect, declare a queue, and watch vhost / → amqp.default.* in a few steps.
Capabilities
Supported methods, forced caps, inert arguments, and the nine gotchas.
Migrating from RabbitMQ
Rename-before-migration items for the reserved default vhost and the name charset.
Was this page helpful?
Capabilities
What the KubeMQ RabbitMQ (AMQP 0-9-1) connector supports, the caps it negotiates, the methods it rejects, the inert arguments it accepts, and the nine gotchas.
Configuration reference
The 12-field CONNECTORS_AMQP_* environment variable table and validation rules for the KubeMQ RabbitMQ (AMQP 0-9-1) connector.