Channel Mapping
How an AWS SQS queue maps to a KubeMQ Queue channel — the sqs.{name} grammar, FIFO message-group encoding, the virtual SNS registry, and the tag codec.
This is the master reference for how the embedded KubeMQ AWS connector maps SQS queues and SNS topics onto KubeMQ. An SQS queue is backed by exactly one KubeMQ Queue channel; an SNS topic is virtual — a registry entry whose publish fans out to subscribed queues and webhooks.
SQS queue grammar
Every SQS queue maps to exactly one KubeMQ Queue channel:
sqs.{name}
└┬─┘ └──┬──┘
│ └─ the SQS queue name (the same name you pass to CreateQueue)
└─ fixed connector prefix| SQS queue | KubeMQ channel |
|---|---|
orders | sqs.orders |
events | sqs.events |
work-dlq | sqs.work-dlq |
FIFO group grammar
A FIFO queue {name}.fifo fans each message group onto its own per-group channel:
sqs.{name}.fifo.g.{enc(group)}
└─────┬────────┘ └┬┘ └───┬────┘
│ │ └─ the MessageGroupId, percent-encoded
│ └─ fixed ".g." group separator
└─ the FIFO queue channel (the name includes the ".fifo" suffix)enc percent-encodes any byte outside [a-zA-Z0-9_-].
| FIFO queue | MessageGroupId | KubeMQ channel |
|---|---|---|
tasks.fifo | g1 | sqs.tasks.fifo.g.g1 |
tasks.fifo | order/42 | sqs.tasks.fifo.g.order%2F42 |
SNS topics are virtual
SNS topics have no native channel. A topic is a registry entry, synced/replicated across
cluster nodes; its authorization pseudo-resource is sns.{topic}. Fan-out resolves to the
target SQS channels (one batched send) plus HTTP/HTTPS webhooks at publish time. See
Fan-out.
ARNs & queue URLs
| Form | Value |
|---|---|
| SQS ARN | arn:aws:sqs:{Region}:{AccountId}:{name} |
| SNS ARN | arn:aws:sns:{Region}:{AccountId}:{name} |
| Queue URL | {scheme}://{host}/{AccountId}/{name} (path-style; host from AdvertisedUrl or the request Host) |
Region defaults to kubemq (not enforced); AccountId defaults to 000000000000. Resolution
parses the path only, so a stale host in a saved URL still works.
The registry is authoritative
Only resources created through the AWS API are visible. Operating on a native sqs.foo channel
that was never CreateQueued returns NonExistentQueue.
Cross-protocol interoperability
Because the backing store is a normal KubeMQ Queue channel, an SQS SendMessage to sqs.orders
is consumable by a gRPC/REST queue client on the same channel, and vice-versa.
Native-interop caveat (gotcha #7). A message produced by a native KubeMQ client on
sqs.* lacks the sqs_* tags, so its MessageId falls back to the broker MessageID, it has no
SenderId, and no policy stamping is applied. See
Cross-protocol interop.
Message attribute ⇄ tag mapping
SQS message attributes round-trip losslessly through the KubeMQ Tags codec.
| AWS field | KubeMQ Tag | Notes |
|---|---|---|
Message attribute {Name} | sqs_attr_{Name} | value is {DataType}|{value}; Binary is base64; ≤ 10 attributes, name ≤ 256 chars, no AWS./Amazon. prefix; DataType String / Number / Binary (+ subtypes String.x) |
System attribute AWSTraceHeader | sqs_trace_header | the only accepted system attribute; anything else → InvalidParameterValue |
(connector-stamped) MessageId | sqs_message_id | generated UUID |
(connector-stamped) SenderId | sqs_sender_id | the authenticated ClientID |
FIFO MessageGroupId | sqs_group_id | |
FIFO MessageDeduplicationId | sqs_dedup_id |
Receive-side decoded system attributes
SentTimestamp, ApproximateReceiveCount, ApproximateFirstReceiveTimestamp (node-local
approx), SenderId, DeadLetterQueueSourceArn (redriven messages), and FIFO MessageGroupId /
SequenceNumber / MessageDeduplicationId. Attribute-name filtering on receive supports All,
exact names, and prefix.*.
SNS raw / enveloped tags
| Context | Mapping |
|---|---|
| SQS enveloped delivery | the SNS Notification JSON carries MessageAttributes as {Type, Value} per attribute (Binary base64) |
| SQS raw delivery | bare body + the attribute tag codec + sns_topic_arn / sns_subject tags |
| HTTP raw delivery | bare payload with attributes mapped to x-amz-sns-attr-{name} headers |
Raw-HTTP attribute-drop deviation. AWS drops message attributes for raw HTTP delivery; this
connector instead surfaces them as x-amz-sns-attr-{name} headers.
MD5
| Field | Algorithm |
|---|---|
MD5OfMessageBody | MD5 of the body bytes |
MD5OfMessageAttributes | AWS length-prefixed message-attribute MD5 |
MD5OfMessageSystemAttributes | present only when AWSTraceHeader is set |
FIFO SequenceNumber deviation
The 20-digit zero-padded SequenceNumber is the broker send-timestamp (UnixNano) on SEND and
the true broker sequence on RECEIVE. It is still strictly increasing per group for serialized
sends. See Reliability.
Related
Architecture
The SQS→Queue and virtual-SNS service model and how fan-out resolves at publish time.
SQS queues & consumers
Attributes, FIFO groups, DLQ redrive, and receipt-handle semantics.
Capabilities
The 18 SQS / 17 SNS supported actions and the eight gotchas.
Error Codes
The AWS error codes the channel/attribute mapping can raise.
Was this page helpful?
Capabilities
What the KubeMQ AWS (SQS & SNS) connector supports — the 18 SQS and 17 SNS actions, the queue and topic attributes, and the out-of-scope operations it rejects.
Configuration
Reference table of the ten CONNECTORS_AWS_* environment variables for the KubeMQ AWS connector, with TOML, Env, and Docker equivalents.