KubeMQ
ConnectorsRabbitMQ (AMQP 0-9-1)Concepts

Configuration

How the KubeMQ RabbitMQ (AMQP 0-9-1) connector is configured — enable/disable, TLS, and the availability-first startup model.

The RabbitMQ (AMQP 0-9-1) connector is configured server-side under the Connectors.Amqp block of the KubeMQ server config, exposed as CONNECTORS_AMQP_* environment variables (every field but the Credentials user list has one). The connector is on by default — a stock server binds port 5672 without any env var. It ships with sensible production defaults, so no other env var is required.

The only thing clients configure is the broker endpoint via the KUBEMQ_AMQP_URL environment variable (default amqp://guest:guest@localhost:5672/); the URL scheme selects the transport (amqp:// plain, amqps:// TLS). Everything below is broker-side server configuration.

Enable / disable

The connector is on out of the box, so a plain run already publishes port 5672:

docker run -d \  --pull always \  --platform linux/amd64 \  --name kubemq \  --hostname kubemq \  -p 127.0.0.1:5672:5672 \  -p 127.0.0.1:5671:5671 \  -p 127.0.0.1:50000:50000 \  -e STORE_ENGINE=next \  -e STORE_NEXT_ACK_POLICY=strict \  -e STORE_STORE_PATH=/kubemq/store \  -e API_BIND_ADDRESS=0.0.0.0 \  -v kubemq-data:/kubemq/store \  europe-docker.pkg.dev/kubemq/images/kubemq-next:latest

To turn it off:

docker run -d --pull always --platform linux/amd64 --name kubemq --hostname kubemq -p 127.0.0.1:50000:50000 -e STORE_ENGINE=next -e STORE_NEXT_ACK_POLICY=strict -e STORE_STORE_PATH=/kubemq/store -e API_BIND_ADDRESS=0.0.0.0 -e CONNECTORS_AMQP_ENABLE=false -v kubemq-data:/kubemq/store europe-docker.pkg.dev/kubemq/images/kubemq-next:latest

The enable variable is CONNECTORS_AMQP_ENABLE — spell it verbatim. This is the AMQP 0-9-1 (RabbitMQ) connector; it is distinct from the AMQP 1.0 connector, whose flag is CONNECTORS_AMQP10_ENABLE. The two share ports 5672/5671 through the internal amqpmux, but each has its own enable flag — and the defaults differ. AMQP 0-9-1 is on by default, so port 5672 is open on a stock server; AMQP 1.0 dispatch on that same port is still opt-in. An AMQP 1.0 client against a stock server therefore connects at the TCP level and then fails protocol negotiation until you set CONNECTORS_AMQP10_ENABLE=true. Conversely, disabling AMQP 0-9-1 leaves an enabled AMQP 1.0 reachable on the same ports. Alternatively, disable just one listener with CONNECTORS_AMQP_PORT=0 (plain) or CONNECTORS_AMQP_TLS_PORT=0 (TLS); setting both to 0 also disables the connector. When Enable is false, no AMQP listener binds and the rest of this config is skipped.

Default-on tolerance. Because the connector is on only by default, it never stops the server booting. If the configuration cannot run it (for example the batch or receive limits are above the Queue limits), the server prints one stderr warning and continues without it: WARNING: the AMQP 0-9-1 (RabbitMQ) connector is on by default but cannot run with this configuration, so it is DISABLED for this run: ... — set Connectors.Amqp.Enable=false to silence this, or =true to make it a startup error. Setting CONNECTORS_AMQP_ENABLE=true explicitly keeps those configuration errors fatal, as before.

Security. With authentication off (the default), port 5672 accepts any username/password — the same trust model as unauthenticated gRPC and REST. If the server is reachable from untrusted networks, enable authentication, firewall 5672/5671, or turn the connector off. See Auth & security.

Field notes

  • Port / TlsPort — when Enable=true, at least one of Port or TlsPort must be non-zero, otherwise the server reports bad AMQP configuration: Enable=true requires Port or TlsPort. The plain listener is amqp://host:5672/; the TLS listener is amqps://host:5671/.
  • MaxConnections — 0 means unlimited; over-limit connections are accepted then closed with code 320.
  • DefaultVhost — the segment AMQP vhost / maps to. The default literal is "default" (a reserved vhost), not /. The channel mapping is amqp.{vhost}.{queue}. Reach the default vhost by connecting to /; connecting directly to a vhost literally named default is rejected. See the reserved-vhost callout in the configuration reference.
  • GetBatchSize — bounds per-basic.get pulls (default 32).
  • DeadLetterMaxHops — the dead-letter cycle cap per (queue, reason); default 16.
  • MaxReceiveCount — the poison-message receive cap; 0 inherits the broker default.
  • SslCertLogin / SslCertLoginFrom — certificate login over SASL EXTERNAL; off by default and deliberately not inferred from the TLS settings. See Authentication.
  • Credentials — connector-local RabbitMQ-style users with per-vhost permissions and tags; file or structured configuration only, no environment variable. See Users and permissions.
  • Management.Enable / Management.Port — the RabbitMQ-compatible management HTTP API on a second listener (off by default, port 15672). See Management HTTP API.

TLS

TLS has no AMQP-specific configuration. TLS/AMQPS on port 5671 is managed by the server-global Security block, shared with gRPC and REST. The TLS listener is active only when that block is configured (Mode ≠ None); TLS 1.2+ is enforced and mTLS is supported. Connecting over TLS is purely a transport swap (KUBEMQ_AMQP_URL=amqps://host:5671/); the AMQP frames on top are identical. See TLS and mTLS and Auth & security.

Configuring the connector

The same settings can be supplied through a TOML config file, environment variables, or docker run flags. Each environment variable uses the CONNECTORS_AMQP_ prefix.

config.toml
[Connectors.Amqp]
  Enable = true          # the default; set false to turn the connector off
  Port = 5672
  TlsPort = 5671
  HeartbeatSeconds = 60
  FrameMax = 131072
  ChannelMax = 2047
  MaxConnections = 1000
  MaxBodySize = 104857600
  DefaultVhost = "default"
  GetBatchSize = 32
  DeadLetterMaxHops = 16
  MaxReceiveCount = 0
  SslCertLogin = false
  SslCertLoginFrom = "distinguished_name"
  [Connectors.Amqp.Management]
    Enable = false
    Port = 15672
  # [[Connectors.Amqp.Credentials]]      # optional users; no env-var form
  #   Username = "orders-producer"
  #   Password = "changeme"
rabbitmq.env
CONNECTORS_AMQP_ENABLE=true   # the default; set false to turn the connector off
CONNECTORS_AMQP_PORT=5672
CONNECTORS_AMQP_TLS_PORT=5671
CONNECTORS_AMQP_HEARTBEAT_SECONDS=60
CONNECTORS_AMQP_FRAME_MAX=131072
CONNECTORS_AMQP_CHANNEL_MAX=2047
CONNECTORS_AMQP_MAX_CONNECTIONS=1000
CONNECTORS_AMQP_MAX_BODY_SIZE=104857600
CONNECTORS_AMQP_DEFAULT_VHOST=default
CONNECTORS_AMQP_GET_BATCH_SIZE=32
CONNECTORS_AMQP_DEAD_LETTER_MAX_HOPS=16
CONNECTORS_AMQP_MAX_RECEIVE_COUNT=0
CONNECTORS_AMQP_SSL_CERT_LOGIN=false
CONNECTORS_AMQP_SSL_CERT_LOGIN_FROM=distinguished_name
CONNECTORS_AMQP_MANAGEMENT_ENABLE=false
CONNECTORS_AMQP_MANAGEMENT_PORT=15672
# Connectors.Amqp.Credentials has no environment variable
docker run -d \  --pull always \  --platform linux/amd64 \  --name kubemq \  --hostname kubemq \  -p 127.0.0.1:5672:5672 \  -p 127.0.0.1:5671:5671 \  -p 127.0.0.1:50000:50000 \  -e STORE_ENGINE=next \  -e STORE_NEXT_ACK_POLICY=strict \  -e STORE_STORE_PATH=/kubemq/store \  -e API_BIND_ADDRESS=0.0.0.0 \  -e CONNECTORS_AMQP_MAX_CONNECTIONS=5000 \  -e CONNECTORS_AMQP_FRAME_MAX=262144 \  -v kubemq-data:/kubemq/store \  europe-docker.pkg.dev/kubemq/images/kubemq-next:latest

The Docker example sets no enable variable — the connector is on by default and port 5672 is bound without it. Set CONNECTORS_AMQP_ENABLE=false when you want to turn the connector off, or CONNECTORS_AMQP_PORT=0 to drop the plain listener and serve AMQPS only.

Availability-first startup. Unlike gRPC, the AMQP connector starts non-fatally: if the listener cannot bind (for example port 5672 is already taken by a real RabbitMQ on the same host) or the topology store is corrupt, the server logs error loading amqp connector, continuing without AMQP and keeps running — and the dashboard still lists the connector as enabled. After an upgrade or config change, verify the connector came up — look for the AMQP connector started log line or check the dashboard AMQP page / GET /api/amqp/connections. See Connections endpoint.

Getting Started

Connect, declare, publish, and consume end-to-end through the RabbitMQ connector in minutes.

Architecture

The everything-is-a-Queue model, virtual exchanges, and cross-protocol interop.

TLS and mTLS

Enable the AMQPS listener on 5671, the JWT-in-password rule, and mutual TLS.

Configuration reference

Every Connectors.Amqp.* field, the CONNECTORS_AMQP_* environment variables, and the validation rules.

Channel mapping

The amqp.{vhost}.{queue} grammar, name constraints, and the reserved default vhost.

Was this page helpful?

Architecture

Inside the RabbitMQ (AMQP 0-9-1) connector — the everything-is-a-Queue model, virtual exchange routing, the channel mapping, and cross-protocol interop.

Exchanges and Routing

How RabbitMQ exchange types (direct, fanout, topic, headers) work as virtual connector-side routing, resolved at publish time into KubeMQ Queue channels.

On this page

Enable / disableField notesTLSConfiguring the connectorRelated