Requirements and supported setups
Supported KubeMQ setups, Kubernetes and platform requirements, sizing, network access, artifact names and the latest-release version policy.
This page lists the setups KubeMQ supports, Kubernetes and platform requirements, sizing, network access, and the artifacts every install pulls. The install pages link here.
Supported setups
| Setup | Use it for | Install page |
|---|---|---|
| One KubeMQ server on Docker or Podman | Development and test | Install with kmq or Install with Docker |
| A cluster of 3 or more servers on Kubernetes, created by the KubeMQ operator | Production and staging | Install on Kubernetes |
| The same Kubernetes cluster with no internet access | Production at an air-gapped site | Install air-gapped |
Not supported:
- A server run directly on a host or virtual machine, in another container runtime, or as several Docker or Podman servers joined into a cluster. The server refuses to start.
- Kubernetes pods that the operator did not create. The server exits; see Troubleshooting.
- A Kubernetes cluster of fewer than 3 servers, including
standalone: true. - Changing the number of servers after the cluster is created, including autoscaling.
- A single Docker server with no internet access. Contact support.
Kubernetes
| Requirement | Detail |
|---|---|
| Servers | An odd number, at least 3 (3, 5 or 7). The number is fixed when the cluster is created. |
| Operator | The KubeMQ operator creates and manages every server. Each namespace gets one operator release, and its cluster releases go in the same namespace. |
| Storage | A storage class that creates volumes on demand. Each server gets its own persistent volume claim. |
| Server-to-server network | Servers reach each other by stable DNS names through a headless Service on ports 5228 and 5229. The operator creates it. |
| Cluster identity | The server's service account, kubemq-cluster-next, reads the kube-system namespace, the cluster's license identity. The operator release grants this. |
| Installer permissions | The account that installs KubeMQ can create custom resource definitions, cluster roles and cluster role bindings. |
| Nodes | An x86-64 node for the operator, whose image is x86-64 only. Servers run on x86-64 or Arm nodes. |
| Kubernetes and Helm versions | KubeMQ does not publish minimum versions yet. |
Platforms
| Requirement | Detail |
|---|---|
| Server images | Linux, on x86-64 or 64-bit Arm; kmq pulls the one that matches your machine. The Docker commands on these pages ask for x86-64, so on Apple silicon or another Arm machine they need x86-64 emulation. |
| kmq | Runs natively on macOS, Linux and Windows (x86-64 only on Windows). A server kmq starts still needs Docker Desktop or Podman, but you never open a WSL shell. |
| Shell | The Docker, Kubernetes and air-gapped pages use bash: on Windows, run them in WSL. |
| Podman | Works for one server: add --runtime podman to kmq onboard, or use the "With Podman" line on Install with Docker. |
| File permissions | The server runs as user ID 1001. A file you mount into the container must be readable by that user. |
| FIPS 140-3 | FIPS builds of the server and operator images are listed under Artifacts and versions. |
Sizing
KubeMQ does not publish CPU, memory or disk sizing yet. Size volumes for the messages you keep.
| Setup | Disk per server | CPU and memory |
|---|---|---|
| One Docker server | The kubemq-data volume, limited only by the host's disk | No limits set |
| Kubernetes, as Install on Kubernetes sets it | A 20 GiB volume | No requests or limits set |
| Kubernetes, when your values set no size | A 5 GiB volume, the chart's and kmq's default | No requests or limits set |
Set volume size, CPU and memory for Kubernetes as Deployment & High Availability describes.
Network
Outbound access, over HTTPS on port 443:
| Host | Used by | When |
|---|---|---|
license.kubemq.io | Every server on an evaluation, trial key or license key | At start and while it runs. Data sent to KubeMQ lists every field |
onboarding.kubemq.io | kmq | Only when you request, verify, claim or recover a trial key |
europe-docker.pkg.dev | Docker, Podman, Kubernetes nodes and kmq | Pulling KubeMQ images |
kubemq-io.github.io | Helm, and kmq on Kubernetes | Downloading the Helm chart |
raw.githubusercontent.com | You | Downloading the kmq installer |
github.com, release-assets.githubusercontent.com | The kmq installer, kmq update, kmq version --check | Installing or updating kmq |
api.github.com | The Windows kmq installer | Finding the latest kmq release |
Behind a proxy, set HTTPS_PROXY, HTTP_PROXY and NO_PROXY in the server's environment. An air-gapped cluster needs none of these hosts; see Install air-gapped.
Server ports, inbound:
| Port | Interface | Where |
|---|---|---|
| 50000 | gRPC, for client SDKs | Every server, on by default |
| 9090 | REST and WebSocket | Every server, on by default |
| 8080 | Management API and web dashboard | Every server, on by default |
| 9092 | Kafka-compatible | Every server, on by default |
| 5672 | AMQP 0-9-1, RabbitMQ-compatible | Every server, on by default |
| 5228, 5229 | Server to server | Kubernetes only, inside the cluster |
The commands on these pages publish ports on this machine only (127.0.0.1). Interfaces (gRPC · REST · API · HTTP) covers exposing them.
Artifacts and versions
| Artifact | Name |
|---|---|
| Server image | europe-docker.pkg.dev/kubemq/images/kubemq-next |
| FIPS 140-3 server image | europe-docker.pkg.dev/kubemq/images/kubemq-next-fips |
| Operator image (the chart sets it; you never do) | europe-docker.pkg.dev/kubemq/images/kubemq-operator-next |
| FIPS 140-3 operator image | europe-docker.pkg.dev/kubemq/images/kubemq-operator-next-fips |
| Helm repository and chart | https://kubemq-io.github.io/charts-next, chart kubemq-next |
| kmq | Releases of kubemq-io/kmq |
-next is part of each artifact's name. It is not a preview channel. The image named kubemq without -next is legacy KubeMQ, and its latest tag is a legacy build. See Move from legacy KubeMQ.
Every command on these pages installs the latest KubeMQ release; you never edit a version number. kmq installs the server release matching its own version. On Kubernetes, the latest chart sets exact images, so every server runs the same release. To install a specific release, for GitOps, change control or a mirror, open "Pin a version" under the command. The Release notes list each release's exact artifacts.
To see what you run:
| What | Command |
|---|---|
| kmq | kmq version |
| Helm chart and app version | helm list --kube-context YOUR_KUBE_CONTEXT -n kubemq. Replace: YOUR_KUBE_CONTEXT — your cluster's kubectl context. |
| A running server | The VERSION column of kmq license |
Related
Was this page helpful?
Choose your path
Pick the right way to run KubeMQ: try it on a laptop, install with kmq, Docker or Kubernetes, go air-gapped, migrate a broker or upgrade.
Install with kmq
Keep the KubeMQ server you started with kmq: add a trial or license key, check the license, manage the server and keep kmq up to date.