Configuration Reference
How to read the per-target tables — the legend and the cross-target gotchas.
The reference documents every KubeMQ server setting, grouped by domain. Each domain page renders its options as a single table with the same seven columns, 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.
How to read the tables
Every domain page uses one 7-column table:
| 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, accepts the variable without
error, and silently ignores it.
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
Every server setting lives on one of the nine domain pages below.
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 two persistence engines — legacy and next — 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?