Advanced (config.yaml-only)
Message-broker engine internals, Go runtime tuning, standalone clustering, and routing.
These are advanced, low-level knobs. The message-broker engine (broker.*), runtime
tuning (tuning.*), and standalone clustering (cluster.*) have no Helm/CRD path
— they are Docker / config.yaml-only, so their Helm/CRD column is — (per the
reference legend). On Kubernetes the operator owns those
concerns. Routing is the exception: three of its fields (data, url, autoReload)
map to spec.routing.* on the CRD.
Message-broker engine
The embedded message-broker engine's internal limits and buffers, configured through the
broker.* block. These are Docker / config.yaml-only; there is no Helm/CRD path (the
operator owns the engine on Kubernetes). Most fields bind to a BROKER_* env var — but the
two auto-assigned ports (port, monitoringPort) have no env var and are file-only.
| Setting | Type | Default | Valid values | Docker (config.yaml key · env var) | Helm/CRD path | Notes |
|---|---|---|---|---|---|---|
| Port | int | auto (free port) | port number | broker.port · (no env var) | — | Ephemeral — a free port is picked at every startup (getFreePort()). Not meant to be pinned; no BROKER_PORT env var exists. Not validated. |
| Max payload | int (bytes) | 1048576000 (~1000 MiB) | ≥ 0 | broker.maxpayload · BROKER_MAX_PAYLOAD | — | Max message payload in bytes. Cast to int32 when applied, so the effective ceiling is 2,147,483,647 bytes (~2 GiB); larger values overflow. |
| Write deadline | int (ms) | 2000 | ≥ 0 | broker.writedeadline · BROKER_WRITE_DEADLINE | — | Per-write deadline in milliseconds. |
| Max connections | int | 0 (unlimited) | ≥ 0 | broker.maxconn · BROKER_MAX_CONN | — | 0 = unlimited. |
| Monitoring port | int | auto (free port) | 1–65535 | broker.monitoringport · (no env var) | — | Ephemeral — picked at every startup. No BROKER_MONITORING_PORT env var exists. This is the only broker field validated as a port. |
| Write buffer size | int (MB) | 2 (→ 2 MB) | ≥ 0 | broker.writebuffersize · BROKER_WRITE_BUFFER_SIZE | — | Value is in megabytes — the config value is multiplied by 1024×1024 (broker.go:52). 2 means 2 MB, not 2 bytes. |
| Read buffer size | int (MB) | 10 (→ 10 MB) | ≥ 0 | broker.readbuffersize · BROKER_READ_BUFFER_SIZE | — | Value is in megabytes (×1024×1024, broker.go:53). Read-ahead buffer. 10 = 10 MB. |
| Disk sync (s) | int | 5 | ≥ 0 | broker.disksyncseconds · BROKER_DISK_SYNC_SECONDS | — | Disk flush interval in seconds. Lowered from 60 s → 5 s to shrink the data-loss window. |
| Slice max messages | int | 0 (unlimited) | ≥ 0 | broker.slicemaxmessages · BROKER_SLICE_MAX_MESSAGES | — | 0 = no message-count limit per file slice. |
| Slice max bytes | int64 (MB) | 64 (→ 64 MB) | ≥ 0 | broker.slicemaxbytes · BROKER_SLICE_MAX_BYTES | — | Per-slice ceiling in megabytes (×1024×1024, broker.go:56). 64 = 64 MB. |
| Slice max age (s) | int | 0 (no rollover) | ≥ 0 | broker.slicemaxageseconds · BROKER_SLICE_MAX_AGE_SECONDS | — | 0 = no age-based slice rollover. Value in seconds. |
| Parallel recovery | int | 4 | ≥ 1 | broker.parallelrecovery · BROKER_PARALLEL_RECOVERY | — | Recovery worker count. Must be ≥ 1 (0 or negative is rejected). |
broker.writeBufferSize, broker.readBufferSize, and broker.sliceMaxBytes are expressed
in megabytes, not bytes — the raw config value is multiplied by 1024×1024 internally. Set
readBufferSize: 10 for a 10 MB buffer. broker.maxPayload, by contrast, is in bytes.
Runtime tuning
Optional Go-runtime tuning through the tuning.* block. Every zero value means
"auto-detect from the environment." TuningConfig is the one config domain with no env-var
bindings at all — there are no TUNING_* environment variables (verified: tuning.go's
defaultTuningConfig() makes no bindViperEnv call). These keys are therefore only settable
through a mounted config.yaml/TOML file. There is no Helm/CRD path. For the three fields
that wrap standard Go knobs, the Go runtime independently honors the native GOGC,
GOMEMLIMIT, and GOMAXPROCS env vars.
| Setting | Type | Default | Valid values | Docker (config.yaml key · env var) | Helm/CRD path | Notes |
|---|---|---|---|---|---|---|
| GC percent | int | 0 (auto) | ≥ 0 | tuning.gc_percent · (no env var) | — | Config-file-only. Wraps Go GC frequency; use the native GOGC env var instead for env-based tuning. |
| Memory limit (MB) | int | 0 (auto) | ≥ 0 | tuning.memory_limit_mb · (no env var) | — | Config-file-only. Wraps GOMEMLIMIT; use the native GOMEMLIMIT env var for env-based tuning. |
| Max procs | int | 0 (auto) | ≥ 0 | tuning.max_procs · (no env var) | — | Config-file-only. Wraps GOMAXPROCS; use the native GOMAXPROCS env var for env-based tuning. |
| Pipe init buffer (KB) | int | 0 (auto) | ≥ 0 | tuning.pipe_init_buf_kb · (no env var) | — | Config-file-only. Internal memory-pipe initial buffer size. |
| Pipe max buffer (KB) | int | 0 (auto) | ≥ 0 | tuning.pipe_max_buf_kb · (no env var) | — | Config-file-only. Internal memory-pipe maximum buffer size. |
| Allow TLS SHA-1 | bool | false | true / false | tuning.tls_allow_sha1 · (no env var) | — | Config-file-only. Permits SHA-1 in TLS cipher suites (legacy interop). |
tuning.* keys use snake_case in config.yaml (they carry explicit mapstructure tags —
gc_percent, memory_limit_mb, etc.), unlike the dotted-camel keys elsewhere. Because there
are no TUNING_* env vars, a K8s CRD/Helm chart cannot set these today without a custom
mounted config file — prefer the native GOGC / GOMEMLIMIT / GOMAXPROCS container env
vars for GC/memory/CPU tuning.
Standalone clustering
Manual standalone clustering for Docker, configured through the cluster.* block. Uses the
server's standard enable: true/false toggle. This is Docker / config.yaml-only (env
CLUSTER_*) — there is no Helm/CRD path. On Kubernetes, high availability is
spec.replicas (operator-managed clustering), not cluster.*; the operator injects the
CLUSTER_* env vars into the StatefulSet pod template itself — see
Deployment & High Availability.
| Setting | Type | Default | Valid values | Docker (config.yaml key · env var) | Helm/CRD path | Notes |
|---|---|---|---|---|---|---|
| Enable | bool | false | true / false | cluster.enable · CLUSTER_ENABLE | — | Master toggle. When false, all other cluster.* fields are ignored (validation short-circuits). |
| Cluster name | string | kubemq | name string | cluster.name · CLUSTER_NAME | — | Shared cluster identifier across peers. |
| Cluster port | int | 5228 | 1–65535 | cluster.port · CLUSTER_PORT | — | Peer-to-peer cluster port. Validated only when enable: true. |
| Cluster routes | string | "" | route list | cluster.routes · CLUSTER_ROUTES | — | Addresses of peer nodes to connect to. |
| Is seed | bool | false | true / false | cluster.isseed · CLUSTER_IS_SEED | — | Whether this node is a seed node. Struct field is IsSeed; config.yaml key is cluster.isseed. |
The next storage engine uses an additional replication membership plane managed by Dragonboat. Its dedicated Cluster.Replication.* configuration fields and POD_NAME→ReplicaID auto-derivation are documented in the Storage Engines reference page.
Routing
Channel-routing rules, configured through the routing.* block. The server uses the standard
enable: true/false toggle. On the CRD, routing has no explicit toggle — the operator
auto-emits ROUTING_ENABLE=true whenever spec.routing.data or spec.routing.url is set.
Three fields map to spec.routing.*; enable and filePath are Docker-only (—).
| Setting | Type | Default | Valid values | Docker (config.yaml key · env var) | Helm/CRD path | Notes |
|---|---|---|---|---|---|---|
| Enable | bool | false | true / false | routing.enable · ROUTING_ENABLE | — | Master toggle (server side). On the CRD it is implicit — set automatically when data or url is provided. When false, the rest of the block is ignored. |
| Routing data | string | "" | inline routing rules | routing.data · ROUTING_DATA | spec.routing.data | Inline routing table. Consumed raw (not base64-decoded), so the operator emits it as a plain ConfigMap variable. Takes precedence over filePath and url. |
| Routing URL | string | "" | URL | routing.url · ROUTING_URL | spec.routing.url | Fetch the routing table from a URL. Validated as a URL when set. Struct field is URL; config.yaml key is routing.url. Emitted raw. |
| Auto-reload (ms) | int | 0 (off) | ≥ 0 | routing.autoreload · ROUTING_AUTO_RELOAD | spec.routing.autoReload | Reload interval in milliseconds. 0 disables periodic reload. CRD field is int32, omitempty — the operator only emits ROUTING_AUTO_RELOAD when non-zero (no CRD-side default). |
| Routing file | string | "" | file path | routing.filepath · ROUTING_FILE_PATH | — | Load rules from a file path. Docker / config.yaml-only — not exposed on the CRD (superseded by inline data). Validated as a filename when set. |
When routing is enabled you must provide exactly one source: data, filePath, or url
(enabling routing with none set is a configuration error). Precedence when more than one is
present: data → filePath → url. autoReload must be ≥ 0.
Example
Set a message-broker buffer. On Docker this is a config.yaml key (in MB) or a BROKER_*
env var; on Kubernetes the broker engine has no Helm/CRD path, so the operator owns it.
This is a single-setting snippet — see the Docker guide for complete,
runnable configurations.
broker:
readBufferSize: 10 # megabytes → 10 MB# Not available on Helm/CRD — the message-broker engine is config.yaml-only.
# On Kubernetes the operator manages the broker engine.For the full Docker delivery methods (env vars, mounted config.yaml, the CONFIG
variable) see the Docker guide.
Was this page helpful?