KubeMQ
DeployInstall

Install air-gapped

Install a KubeMQ cluster on Kubernetes with no internet access: download a verified bundle, mirror the images, apply an offline license file.

This page installs a KubeMQ cluster on Kubernetes with no internet access. You download everything on a connected machine, move it in, and license the cluster with an offline license file. Then kmq license shows every server active. Time: about 60 minutes.

You work in two sittings: steps 1–4, a wait for your offline license file, then steps 5–7. Need an offline Docker server? Contact support.

These commands are for bash on macOS and Linux. On Windows, run them in WSL (Windows Subsystem for Linux), or use the kmq tab of Try KubeMQ, which runs natively on Windows.

Before you start

Do this on both machines.

Create a private folder, readable only by you, and work inside it:

mkdir -p -m 700 kubemq-private
cd kubemq-private

Steps

Download the bundle

On the connected machine:

kmq deploy artifacts pull --out kubemq-bundle --registry YOUR_MIRROR_REGISTRY --platform linux/amd64 --deadline 30m

Replace: YOUR_MIRROR_REGISTRY — your registry's address, as the cluster nodes reach it.

You should see:

Output
HARNESS_OUTPUT_PENDING

Set --platform to the administration machine's: linux/amd64, linux/arm64, darwin/amd64 or darwin/arm64. The checksummed bundle holds the latest release, the tools and a mirror-values.yaml for your registry. Verify it:

kmq deploy artifacts inspect --manifest kubemq-bundle/artifacts.json

You should see:

Output
HARNESS_OUTPUT_PENDING

Move the bundle in and mirror the images

Copy kubemq-bundle into kubemq-private on the administration machine and install kmq:

sudo install -m 755 kubemq-bundle/bin/kmq /usr/local/bin/

If Helm or kubectl is missing:

sudo install -m 755 kubemq-bundle/bin/helm /usr/local/bin/
sudo install -m 755 kubemq-bundle/bin/kubectl /usr/local/bin/
kmq deploy artifacts inspect --manifest kubemq-bundle/artifacts.json

You should see:

Output
HARNESS_OUTPUT_PENDING
kmq deploy artifacts push --manifest kubemq-bundle/artifacts.json --registry YOUR_MIRROR_REGISTRY --deadline 30m

You should see:

Output
HARNESS_OUTPUT_PENDING

Install the operator

kubectl --context YOUR_KUBE_CONTEXT create namespace kubemq --dry-run=client -o yaml | kubectl --context YOUR_KUBE_CONTEXT apply -f -

Replace: YOUR_KUBE_CONTEXT — the target cluster's kubectl context.

You should see:

Output
HARNESS_OUTPUT_PENDING
helm upgrade --install kubemq-operator kubemq-bundle/chart/kubemq-next.tgz \
  --kube-context YOUR_KUBE_CONTEXT \
  -n kubemq \
  -f kubemq-bundle/mirror-values.yaml \
  --set operator.enabled=true \
  --set cluster.enabled=false \
  --wait

You should see:

Output
HARNESS_OUTPUT_PENDING

Your mirror must allow anonymous pulls from cluster nodes. If it requires credentials, contact support.

Request your offline license file

kmq license fingerprint --kube-context YOUR_KUBE_CONTEXT --namespace kubemq --out fingerprint.json

You should see:

Output
HARNESS_OUTPUT_PENDING

Send fingerprint.json and your server count through Plans compared. Put the kubemq.license you receive in kubemq-private.

Apply the offline license file

kubectl --context YOUR_KUBE_CONTEXT -n kubemq create secret generic messaging-license --from-file=licenseFile=kubemq.license --dry-run=client -o yaml | kubectl --context YOUR_KUBE_CONTEXT apply -f -

You should see:

Output
HARNESS_OUTPUT_PENDING

Install the cluster

cluster-values.yaml
operator:
  enabled: false
cluster:
  enabled: true
fullnameOverride: messaging
replicas: 3
licenseFileSecretRef:
  name: messaging-license
  key: licenseFile
image:
  pullPolicy: IfNotPresent
volume:
  size: 20Gi
  storageClass: YOUR_STORAGE_CLASS
api:
  expose: ClusterIP
  auth:
    enable: true
    adminUsername: admin
env:
  STORE_NEXT_ACK_POLICY: "strict"

Replace: YOUR_STORAGE_CLASS — a storage class from kubectl --context YOUR_KUBE_CONTEXT get storageclass.

As on Install on Kubernetes, with the offline license file as the only license source.

IfNotPresent lets a server restart without the registry.

helm upgrade --install messaging kubemq-bundle/chart/kubemq-next.tgz \
  --kube-context YOUR_KUBE_CONTEXT \
  -n kubemq \
  -f kubemq-bundle/mirror-values.yaml \
  -f cluster-values.yaml

You should see:

Output
HARNESS_OUTPUT_PENDING
kubectl --context YOUR_KUBE_CONTEXT -n kubemq wait --for=condition=Ready kubemqclusters.next.kubemq.io/messaging --timeout=10m

You should see:

Output
HARNESS_OUTPUT_PENDING

Check the license

Expect every server active, with EXPIRES on your file's end date.

kmq license --kube-context YOUR_KUBE_CONTEXT

You should see:

Output
HARNESS_OUTPUT_PENDING

Other states: How licensing works. Test messages: Install on Kubernetes.

Renew before it expires

The file does not renew itself: the servers stop on the EXPIRES date kmq license shows. Monitor it as How licensing works describes. To renew, delete fingerprint.json, repeat step 4, replace kubemq.license, and repeat steps 5 and 7. Servers restart one at a time, keeping their data.

If something goes wrong

  • ImagePullBackOff. An image is missing from your registry or needs credentials (steps 2 and 3).
  • No servers start. If kubectl describe on the messaging cluster shows LicenseInvalid, check that the Secret's key is licenseFile (step 5; Troubleshooting).
  • A server logs #fingerprint-mismatch. Usually the server account cannot read kube-system (Troubleshooting); otherwise the file is for another cluster (Troubleshooting).
  • The servers stopped on the EXPIRES date. Renew the file (Troubleshooting).

Next steps

To upgrade, delete kubemq-bundle, repeat steps 1 and 2, apply the new custom resource definitions, then repeat steps 3 and 6:

helm show crds kubemq-bundle/chart/kubemq-next.tgz | kubectl --context YOUR_KUBE_CONTEXT apply --server-side --force-conflicts -f -

Replace: YOUR_KUBE_CONTEXT — the target cluster's kubectl context.

Production checklist

Harden the cluster before production traffic.

Upgrade KubeMQ

Move a running KubeMQ to a newer release.

Plans compared

Compare offline license files with the other license kinds.

Was this page helpful?

Install on Kubernetes

Install the KubeMQ operator and a three-server cluster with kmq or Helm, add your license, check it, send a test message and connect your apps.

Production checklist

Everything that must be true before KubeMQ takes production traffic: cluster shape, license, security, network, backups, monitoring and your applications.

On this page

Before you startStepsDownload the bundleMove the bundle in and mirror the imagesInstall the operatorRequest your offline license fileApply the offline license fileInstall the clusterCheck the licenseRenew before it expiresIf something goes wrongNext steps