# Configuration Reference (/configure/reference)



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.

<Callout type="info">
  **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.
</Callout>

## How to read the tables [#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 [#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."

<Callout type="info">
  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](/configure/reference/advanced) page.
</Callout>

## The env-var acronym rule [#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_*`    |

<Callout type="warn">
  **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. &#x2A;*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.
</Callout>

<Callout type="warn">
  **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_*` and
    `CONNECTORS_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 in `CONNECTORSMQTT_*`, `CONNECTORSMCP_*`,
    `CONNECTORSCE_*` or `CONNECTORSA2_A_*` produces **no output at all**. So are the
    `LICENSE_`, `NOTIFICATION_`, `SECURITY_`, `TELEMETRY_` and `TUNING_` namespaces — a typo
    in `LICENSE_KEY_DATA` is silent.

  Confirm the **effective** value in the dashboard rather than trusting the log either way.
</Callout>

## `enable` ↔ `disabled` inversion [#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
  example `connectors.ce.enable: false` (env `CONNECTORSCE_ENABLE=false`). Helm/CRD turns
  one off with `spec.<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 with `spec.<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 [#configuration-domains]

The settings are grouped across these nine domain pages.

<Cards>
  <Card title="Core & Licensing" href="/configure/reference/core" description="License key, log level, and host/server identity." />

  <Card title="Interfaces" href="/configure/reference/interfaces" description="gRPC, REST/WebSocket, the management API, and the shared HTTP server with CORS." />

  <Card title="Connectors" href="/configure/reference/connectors" description="MCP, A2A (agents), CloudEvents, MQTT, AMQP 0.9.1, AMQP 1.0, STOMP, Kafka, AWS, and GCP Pub/Sub." />

  <Card title="Storage & Queues" href="/configure/reference/storage-queues" description="Persistent store limits and retention plus queue delivery defaults and ceilings." />

  <Card title="Storage Engines" href="/configure/reference/storage-engines" description="The next and legacy persistence engines — engine selection, ack policy, durability, mode isolation, compaction, and next-engine clustering." />

  <Card title="Security" href="/configure/reference/security" description="JWT and OIDC authentication, policy-based authorization, and TLS/mTLS." />

  <Card title="Observability" href="/configure/reference/observability" description="OpenTelemetry traces and metrics, audit logging, and notifications." />

  <Card title="Deployment & High Availability" href="/configure/reference/deployment" description="Kubernetes packaging — image, volume, resources, health, scheduling, Service exposure — plus replicas and standalone mode." />

  <Card title="Advanced" href="/configure/reference/advanced" description="Message-broker engine, runtime tuning, and routing — config.yaml-only advanced knobs." />
</Cards>