Configuration Reference
How to read the per-target tables — the legend and the cross-target gotchas.
The reference documents the KubeMQ server settings an operator configures, grouped by domain. Every option is rendered in a table with the same seven columns — most pages carry several, one per settings group — so the same field reads identically whether you run KubeMQ with Docker or on Kubernetes via Helm. This page is the legend — read it once, then every table downstream is unambiguous.
Not every field in the server's config struct appears here. Internal, test-only, and derived fields are deliberately out of scope, and a handful of newer knobs are documented on the page that owns their behavior rather than in a settings table. If a variable you found in a log or a struct dump isn't here, that is not proof it does nothing — check the domain page for the feature it belongs to first.
How to read the tables
Every settings table on every domain page uses the same 7 columns:
| Column | What it tells you |
|---|---|
| Setting | The human-readable name of the option. |
| Type | The value type — int, bool, string, size string, enum, etc. |
| Default | The value the server uses when the setting is omitted. |
| Valid values | The accepted range or enum, where one applies. |
| Docker (config.yaml key · env var) | Both Docker forms: the config.yaml key and its environment variable. |
| Helm/CRD path | The KubemqCluster spec.* path. The Helm value is that path with the leading spec. removed (spec.grpc.port → grpc.port). |
| Notes | Name divergences, validation rules, cross-field constraints, and version floors. |
The Docker column always shows two forms of the same setting. The config.yaml key is
viper-lowercased with no per-segment separators (for example store.maxretention); the
environment variable is that key in UPPER_SNAKE (STORE_MAX_RETENTION).
The Helm/CRD column shows the CRD spec.* path. Because the chart renders values.yaml
straight into the CR spec, a Helm value is just that path minus spec. — there is no
separate Helm schema to learn.
The "—" convention
A dash (—) in the Helm/CRD path column means the setting is not available on that
surface — it is a Docker / config.yaml-only knob with no Helm route. It does not
mean "to be filled in later."
Whole domains are Docker-only by design: the message-broker engine (broker.*), runtime
tuning (tuning.*), and standalone clustering (cluster.*) are advanced settings exposed
through config.yaml/env only. On Kubernetes the operator owns those concerns. See the
Advanced page.
The env-var acronym rule
Docker derives each environment variable from the config.yaml key with convertEnvFormat:
snake-case the key, drop the dots, uppercase. The trap is in the connector prefixes —
how CONNECTORS joins the next segment depends on whether that segment is a Title-case word
or an all-caps acronym:
| Connector segment | Form | Env-var prefix |
|---|---|---|
Amqp (0.9.1) | Title-case → keeps the underscore | CONNECTORS_AMQP_* |
Amqp10 (1.0) | Title-case → keeps the underscore | CONNECTORS_AMQP10_* |
Stomp | Title-case → keeps the underscore | CONNECTORS_STOMP_* |
Aws | Title-case → keeps the underscore | CONNECTORS_AWS_* |
Kafka | Title-case → keeps the underscore | CONNECTORS_KAFKA_* |
Gcp | Title-case → keeps the underscore | CONNECTORS_GCP_* |
MCP | all-caps acronym → drops the underscore | CONNECTORSMCP_* |
CE (CloudEvents) | all-caps acronym → drops the underscore | CONNECTORSCE_* |
MQTT | all-caps acronym → drops the underscore | CONNECTORSMQTT_* |
A2A (agents) | splits to A2_A | CONNECTORSA2_A_* |
The wrong twin is silently ignored — except for CloudEvents. CloudEvents is the one
connector that binds both forms: the collapsed CONNECTORSCE_* (primary) and the
underscored CONNECTORS_CE_* (a compensating alias) resolve to the same setting — either
CONNECTORSCE_ENABLE or CONNECTORS_CE_ENABLE works. MCP, A2A, and MQTT have no such
alias. For those, only the collapsed form binds — CONNECTORSMCP_*, CONNECTORSA2_A_*,
and CONNECTORSMQTT_*. The underscored twin (CONNECTORS_MCP_*, CONNECTORS_A2_A_*,
CONNECTORS_MQTT_*) does not bind — the server starts and accepts the variable
without error.
Kafka's OAUTHBEARER block has the same kind of alias as CloudEvents: the generic rule
produces the unguessable CONNECTORS_KAFKAO_AUTH_BEARER_*, so the natural
CONNECTORS_KAFKA_OAUTH_BEARER_* is bound deliberately alongside it. Both work.
The server's "IGNORED" warning is unreliable in both directions — do not use it as proof. It reports variables that sit in a KubeMQ namespace prefix but bind to no config key, and that heuristic has two holes:
- False alarms. The two deliberate aliases above —
CONNECTORS_CE_*andCONNECTORS_KAFKA_OAUTH_BEARER_*— are bound by a path the warner doesn't track, so it reports them as IGNORED while they are being applied. Do not "fix" a working setting because of this warning. - Silence that means nothing. The warner's namespace list contains only prefixes ending
in
_(STORE_,CLUSTER_,API_,CONNECTORS_,BROKER_,QUEUE_,ROUTING_,AUTHORIZATION_,AUTHENTICATION_,LOG_,METRICS_,AUDIT_). Every collapsed-acronym form is structurally outside it, so a typo inCONNECTORSMQTT_*,CONNECTORSMCP_*,CONNECTORSCE_*orCONNECTORSA2_A_*produces no output at all. So are theLICENSE_,NOTIFICATION_,SECURITY_,TELEMETRY_andTUNING_namespaces — a typo inLICENSE_KEY_DATAis silent.
Confirm the effective value in the dashboard rather than trusting the log either way.
enable ↔ disabled inversion
The enable model is not uniform — it splits into two families, and each family's default and CRD field name are different:
- HTTP-family interfaces/connectors (gRPC, REST, API, MCP, A2A, CloudEvents) are
opt-out — on by default. Docker turns one off with
enable: false— for exampleconnectors.ce.enable: false(envCONNECTORSCE_ENABLE=false). Helm/CRD turns one off withspec.<x>.disabled: true; omit the key while the connector stays on. - Wire-protocol connectors (MQTT, AMQP 0.9.1, AMQP 1.0, STOMP, Kafka, AWS, GCP) are
opt-in — off by default. Docker turns one on with
enable: true. Helm/CRD turns one on withspec.<x>.enabled: true; omit the key and the connector stays off.
Docker always uses enable: true | false regardless of family — only the default and
the Helm/CRD field name (disabled vs enabled) differ. Each domain page shows the form
that applies on each target.
Configuration domains
The settings are grouped across these nine domain pages.
Core & Licensing
License key, log level, and host/server identity.
Interfaces
gRPC, REST/WebSocket, the management API, and the shared HTTP server with CORS.
Connectors
MCP, A2A (agents), CloudEvents, MQTT, AMQP 0.9.1, AMQP 1.0, STOMP, Kafka, AWS, and GCP Pub/Sub.
Storage & Queues
Persistent store limits and retention plus queue delivery defaults and ceilings.
Storage Engines
The next and legacy persistence engines — engine selection, ack policy, durability, mode isolation, compaction, and next-engine clustering.
Security
JWT and OIDC authentication, policy-based authorization, and TLS/mTLS.
Observability
OpenTelemetry traces and metrics, audit logging, and notifications.
Deployment & High Availability
Kubernetes packaging — image, volume, resources, health, scheduling, Service exposure — plus replicas and standalone mode.
Advanced
Message-broker engine, runtime tuning, and routing — config.yaml-only advanced knobs.
Was this page helpful?