Core & Licensing
Core KubeMQ server settings — license key, log level, host identity, and node naming for a single instance or a clustered deployment.
These are the foundational settings every KubeMQ server needs: the license key that
activates the server, the log level that controls how much it writes, and the host
identity it reports itself under. Each setting is shown for both deployment targets —
Docker single-node (config.yaml key · env var) and Kubernetes/Helm (spec.* path). A
dash (—) in the Helm/CRD column means the setting is not available on that surface.
Licensing & identity
The license is required on both targets. On Docker you can pass the key directly as an
env var, point at a license file, or embed the key in config.yaml; on Helm the chart
renders key (or license) straight into the CR.
| Setting | Type | Default | Valid values | Docker (config.yaml key · env var) | Helm/CRD path | Notes |
|---|---|---|---|---|---|---|
| License token | string | "" | activation UUID (online) or offline license-data blob | — · KUBEMQ_TOKEN (or --key flag) | spec.key | License.KubeMQToken — the value the runtime license service validates. Env/flag-only (os.Getenv); no config.yaml key, no viper binding. spec.key is consumed by the operator (activation + inventory metadata), not injected into the pod as KUBEMQ_TOKEN. |
| License data | string | "" | license-data blob (base64/PEM) | license.key.data · LICENSE_KEY_DATA | spec.license | License.Key.Data. Operator renders spec.license → LICENSE_KEY_DATA secret. Redacted in settings API. |
| License from file | string | "" | filesystem path | license.key.filename · LICENSE_KEY_FILENAME | — | License.Key.Filename. Docker/on-disk only; data wins over filename. |
| Host identity | string | derived hostname | any host string | host · HOST | — | Config.Host. Auto-derived from OS hostname when empty; explicit viper.BindEnv("Host","HOST"). No CRD field. ⚠️ Changing it orphans the store — see the warning below. |
Changing HOST silently orphans the entire persistent store. The store layout is
<storepath>/<host>/…, so the host identity is part of the data path, not just a label.
Point a running node at a new HOST and it boots clean and completely healthy onto an
empty directory, with the previous store sitting intact beside it, untouched and
unread. Nothing fails, nothing warns, and every health check passes — the messages are
simply gone from the server's point of view.
The same trap catches you from the other direction on Docker, where HOST is derived from
the OS hostname: a container recreated without --hostname gets a fresh random one and
lands on a new empty directory. See the
Docker configuration guide.
If you must change it, treat it as a migration: stop the server, move
<storepath>/<old-host> to <storepath>/<new-host>, then start it. To recover from an
accidental change, set HOST back to the original value — the old directory is still
there.
KUBEMQ_TOKEN and LICENSE_KEY_DATA are two different fields, not aliases for the
same setting. License token (KUBEMQ_TOKEN, License.KubeMQToken) is read
directly from the environment — there is no config.yaml key and no viper binding —
and it is the value the runtime license service validates. License data
(license.key.data · LICENSE_KEY_DATA, License.Key.Data) is the license-data blob
bound to config.yaml/Helm. On Kubernetes, spec.key is consumed by the operator
for activation and inventory metadata; it is not injected into the pod as
KUBEMQ_TOKEN. Only spec.license is delivered to the running server, rendered as the
LICENSE_KEY_DATA secret.
LicenseConfig.Validate() is dead code — Config.Validate() never calls it, so no
startup-time check runs against the license fields above. The real gate is the license
service, which validates KUBEMQ_TOKEN at runtime; a missing or invalid token fails
there, not at config validation.
Logging
Log level controls verbosity — the same value on both targets, passed through to the
server unchanged. Log to file / Log file path enable and locate an on-disk log; both
are Docker / config.yaml-only (no Helm/CRD path).
| Setting | Type | Default | Valid values | Docker (config.yaml key · env var) | Helm/CRD path | Notes |
|---|---|---|---|---|---|---|
| Log level | int (LogLevelType) | 2 (Info) | 0=Trace 1=Debug 2=Info 3=Warn 4=Error 5=Fatal | log.level · LOG_LEVEL | spec.log.level | Higher = less. Validate rejects only negatives; a value >5 silently maps to the verbose default (Trace/Debug), not silent. CRD constrains 0–5. |
| Log to file | bool | false | true | false | log.fileenable · LOG_FILE_ENABLE | — | When true, Log file path must be non-empty. |
| Log file path | string | "" | filesystem path | log.filepath · LOG_FILE_PATH | — | Required when file logging is enabled. |
The 0–5 scale above is authoritative (0=Trace … 5=Fatal, default 2=Info). The
operator passes the value through to the server verbatim. An older CRD annotation
describes a different scale (0=silent / 1=info / 2=debug) — that annotation does
not match the running server, so do not rely on it. Use the 0–5 enum above.
Example
Set the log level on each target. This is a single-setting snippet — see the Docker guide and the Kubernetes guide for complete, runnable configurations.
log:
level: 2log:
level: 2For the full Docker delivery methods (env vars, mounted config.yaml, the CONFIG
variable) see the Docker guide; for values.yaml mapped to
the KubemqCluster spec see the Kubernetes guide.
Was this page helpful?