Core & Licensing
Core KubeMQ server settings — the license environment variables and their precedence, the licensing endpoint, log level, and host identity.
These are the foundational settings every KubeMQ server needs: the license (a key or
a file) that lets the server start, 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.
License
License input is environment-only: there is no config.yaml key and no command-line
flag, and a license: block inside config.yaml or the base64 CONFIG variable is rejected
by the loader. On Kubernetes the operator renders the spec.license* fields into the pod
environment for you (License fields). Which
license you need is on Plans compared; what the server does at start, offline
and at expiry is on How licensing works. This section lists the
settings.
| Setting | Type | Default | Valid values | Docker (config.yaml key · env var) | Helm/CRD path | Notes |
|---|---|---|---|---|---|---|
| License key | string | unset | 43-character key | — · KUBEMQ_LICENSE_KEY | spec.licenseKey · spec.licenseKeySecretRef{name,key} | Online license. To apply it, follow the license step of Install with kmq, Install with Docker or Install on Kubernetes. |
| License file | string | unset | path to an armored license file | — · KUBEMQ_LICENSE_FILE | — | Offline license file. Wins over the key. See Install air-gapped. |
| License data | string | unset | armored file contents, or the bare token | — · KUBEMQ_LICENSE_DATA | spec.licenseFile · spec.licenseFileSecretRef{name,key} | Offline license file contents. Wins over the key; if both FILE and DATA are set, FILE wins and a warning is logged. |
| Licensing endpoint | string | https://license.kubemq.io | https:// base URL (a trailing slash is trimmed) | — · KUBEMQ_LICENSE_ENDPOINT | — | Where an online server activates, refreshes and reports usage. Change only when told to by KubeMQ. Any value that is not an https:// base URL is a configuration error (exit code 1). |
| Drain window | int (seconds) | 300 | 0–3600 | — · KUBEMQ_LICENSE_DRAIN_SECONDS | — | How long the server drains connections before a licensing exit (exit code 3). A value outside the range is a configuration error (exit code 1). |
| First-boot retry | int (minutes) | 2 for an automatic evaluation; 30 when a key is set | 1–1440 | — · KUBEMQ_LICENSE_FIRST_BOOT_RETRY_MINUTES | — | How long a first start keeps retrying when it cannot reach the licensing endpoint, before it exits with #first-boot-unreachable. Setting the variable applies the value to both cases. A value outside the range is a configuration error (exit code 1). |
| Cached lease | string | unset | set by the operator | — · KUBEMQ_LICENSE_CACHED_LEASE | set by the operator | Set by the operator. Do not set it yourself. |
| Operator token | string | unset | set by the operator | — · KUBEMQ_API_OPERATOR_TOKEN | set by the operator | Set by the operator. Do not set it yourself. |
Precedence: KUBEMQ_LICENSE_FILE > KUBEMQ_LICENSE_DATA > KUBEMQ_LICENSE_KEY. With none
set, a fresh single Docker or Podman server starts the 14-day evaluation (Plans compared).
The credential values — KUBEMQ_LICENSE_KEY, KUBEMQ_LICENSE_DATA,
KUBEMQ_LICENSE_CACHED_LEASE and KUBEMQ_API_OPERATOR_TOKEN — are redacted on
GET /config and in the dashboard; the file path, endpoint, drain and retry values are
shown as set.
Kubernetes always needs a trial key (choose Kubernetes when you request it), a license key or an offline license file (Plans compared).
Host identity
| Setting | Type | Default | Valid values | Docker (config.yaml key · env var) | Helm/CRD path | Notes |
|---|---|---|---|---|---|---|
| Host identity | string | derived hostname | any host string | host · HOST | — | Config.Host. Auto-derived from the OS hostname when empty; explicit viper.BindEnv("Host","HOST"). No CRD field. Part of the store path — see the warning below. |
A changed host can orphan the store. The store layout is <storepath>/<host>/…, so the
host identity is part of the data path, not just a label. On a cluster, or when HOST is set
explicitly, a changed host boots clean and healthy onto an empty directory, with the previous
store intact beside it and unread. Nothing fails and every health check passes.
A single Docker server keeps its data across a hostname change. With HOST unset and one
server directory in the store, it adopts that directory and logs
NOTICE: adopting existing store identity. Keep --hostname fixed anyway, as the
Docker guide does.
If you must change HOST, 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.
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 cluster-values.yaml mapped to
the KubemqCluster spec see the Kubernetes guide.
Was this page helpful?