Connectivity and security
How AWS SDK clients reach the connector — the port 4566 endpoint override, the CONNECTORS_AWS_ENABLE flag, path-style URLs, SigV4, and the region/account model.
This guide covers how SQS and SNS clients reach the connector: the endpoint override, the opt-in
enable, path-style queue URLs, the SigV4-over-HTTP transport, HTTPS via the server's shared
Security block, the sticky-load-balancer caveat for clusters, and the region/account model.
The connector is opt-in
The AWS connector is disabled by default. Set CONNECTORS_AWS_ENABLE=true to turn it on.
Enabling it opens a new HTTP listener on port 4566 that is not bound until enabled, and that
port must differ from the gRPC / REST / HTTP server ports. Unlike the other wire-protocol
connectors — all six wire-protocol connectors are opt-in, ports not bound until enabled. See
Configuration.
Endpoint override
The connector is a single TCP HTTP listener (default port 4566, the LocalStack convention). Clients reach it by overriding only the endpoint URL — no code changes:
- set
AWS_ENDPOINT_URL_SQSandAWS_ENDPOINT_URL_SNS, or - set the SDK's
BaseEndpoint/endpointOverride/ServiceURL/endpoint/.endpoint_url().
The examples expose a single convenience variable, KUBEMQ_AWS_URL (default
http://localhost:4566), and map it to both endpoint variables:
export KUBEMQ_AWS_URL="http://localhost:4566"
export AWS_ENDPOINT_URL_SQS="$KUBEMQ_AWS_URL"
export AWS_ENDPOINT_URL_SNS="$KUBEMQ_AWS_URL"Both POST / and GET / dispatch (the GET only for Action=ConfirmSubscription); there is no
per-route REST path. See Getting started and
Configuration.
Path-style queue URLs
Queue URLs are path-style: {scheme}://{host}/{AccountId}/{name}. The host comes from the
configured AdvertisedUrl when set, otherwise the request Host. URL resolution parses the
path only, so a stale host in a saved queue URL still works — the connector addresses by
/{account}/{queue}.
SigV4 over HTTP
Every request is verified with hand-rolled SigV4 (see Authentication). In the default accept-any posture the signature shape is required but not cryptographically checked; with static credentials it is fully verified.
SigV4 over plain HTTP transmits the request unencrypted. Accept-any mode is for local development. For production, terminate over HTTPS (below).
HTTPS / TLS
There is no AWS-specific TLS option. The connector reuses the shared httpserver
infrastructure, so HTTPS/mTLS is available via the server-global Security block — the same
one that secures gRPC and REST — passed in when the listener is created. There is no
CONNECTORS_AWS_TLS_* field.
When the server-global Security block is configured, the connector listens over HTTPS; point the
SDK at https://host:4566 (or whatever the deployment exposes) and keep the same code. TLS is
therefore a connectivity / production callout, not a built example variant. For the shared TLS/mTLS
model across connectors, see Auth & security.
Sticky-LB caveat (cluster)
Node-local state needs a sticky load balancer. Three pieces of connector state are node-local:
- SQS receipt handles — a handle minted on one node yields
ReceiptHandleIsInvalidon another; - SQS in-flight tracking — per-queue / per-node maps plus the sweeper;
- SNS HTTP delivery state — pending retries live on the publishing node and are lost on its restart.
Cluster deployments must put a sticky load balancer (session affinity) in front of the connector so each client sticks to one node for the lifetime of its in-flight messages and subscriptions. Single-node deployments are unaffected. See Reliability.
The registry itself is BoltDB, synced across cluster nodes, so queue / topic / subscription existence is cluster-wide; only the in-flight / receipt / delivery state is node-local.
Region and account
- Region is not enforced. Any
AWS_REGIONsigns successfully; the connector's default ARN region segment iskubemq. Use any familiar region (the examples useus-east-1). - AccountId is a single configurable 12-digit value (default
000000000000). There is no cross-account support —QueueOwnerAWSAccountIdis accepted and ignored.
Traffic gate
While the message broker is not yet ready, the connector returns an AWS-shaped 503 (rather than a raw error), so SDKs surface it as a retryable service error. See Connections endpoint.
Related
Authentication
SigV4, accept-any vs static credentials, the ConfirmSubscription exemption, and Casbin authorization.
Reliability
The node-local delivery-state caveat in depth — FIFO ordering, DLQ/redrive, and at-least-once delivery.
Migration from AWS
The endpoint swap, deviations from real AWS, and the sticky-LB step before migration.
Was this page helpful?
Authentication
How the AWS connector authenticates SQS and SNS requests — SigV4 verification, the accept-any local-dev default, static credentials, and Casbin authorization.
Fan-Out (SNS → SQS)
One SNS publish, many consumers over KubeMQ — fan out a single message to subscribed SQS queues and HTTP/HTTPS webhooks, with MessageAttributes filtering.