Mosquitto MQTT Broker Helm Chart

Deploys the Eclipse Mosquitto MQTT broker on Kubernetes using the official eclipse-mosquitto Docker image.

Features

• MQTT and WebSockets listeners, optional MQTT over TLS
• Optional password authentication (inline users or an existing Secret)
• Persistent storage for broker data
• Runs non-root (uid 1883) with a restrictive security context
• Config rendered through Helm templating (tpl), fully overridable

Installation

# Install the chart
helm install mosquitto ./mosquitto-helm-chart

# Install with custom values
helm install mosquitto ./mosquitto-helm-chart -f custom-values.yaml

# Upgrade
helm upgrade mosquitto ./mosquitto-helm-chart

Configuration

Parameter	Description	Default
image.repository	Mosquitto image repository	eclipse-mosquitto
image.tag	Image tag (defaults to chart appVersion)	""
image.pullPolicy	Image pull policy	IfNotPresent
imagePullSecrets	Pull secrets for private registries	[]
service.type	Service type	ClusterIP
service.mqtt.port	MQTT port	1883
service.mqtts.port	MQTT over TLS port (only when tls.enabled)	8883
service.websockets.port	WebSocket port	9001
persistence.enabled	Enable persistent storage	true
persistence.storageClass	Storage class (empty = cluster default)	""
persistence.size	Storage size	1Gi
persistence.retain	Keep the PVC on helm uninstall	true
auth.enabled	Require password authentication	false
auth.users	List of {username, password} to provision	[]
auth.existingSecret	Secret with pre-hashed passwords file	""
tls.enabled	Enable the TLS listener	false
tls.existingSecret	TLS Secret (tls.crt/tls.key, ca.crt)	""
tls.requireClientCert	Require client certificates (mTLS)	false
config	Config files rendered through tpl and mounted in /mosquitto/config	see values.yaml
podSecurityContext / securityContext	Pod / container security contexts	non-root uid 1883
resources	CPU/memory requests and limits	see values.yaml
readinessProbe / livenessProbe	Probes, rendered verbatim	TCP readiness on mqtt
env	Extra environment variables (e.g. TZ)	{}
podAnnotations / podLabels	Extra pod metadata	{}
nodeSelector / tolerations / affinity	Scheduling controls	{} / [] / {}

Notes:

• The chart deploys a single replica. Mosquitto does not cluster, and the data volume is a single ReadWriteOnce PVC.
• Config changes roll the pod automatically (checksum annotation).

Authentication

By default anonymous access is enabled. To require passwords, either provision users inline:

auth:
  enabled: true
  users:
    - username: admin
      password: changeme

The chart stores these in a Secret; an init container hashes them with mosquitto_passwd -U at pod start. Convenient, but the plaintext passwords live in your values and the Helm release secret.

Or point at a Secret you manage, containing an already-hashed password file under the key passwords:

mosquitto_passwd -c -b passwords admin 'changeme'
kubectl create secret generic mosquitto-passwords --from-file=passwords

auth:
  enabled: true
  existingSecret: mosquitto-passwords

TLS

tls:
  enabled: true
  existingSecret: mosquitto-tls   # kubernetes.io/tls secret (e.g. from cert-manager)
  requireClientCert: false        # true = mTLS, needs ca.crt in the secret

Usage

After installation, the broker is available in-cluster at:

• MQTT: <release-name>-mosquitto:1883
• WebSockets: <release-name>-mosquitto:9001
• MQTT over TLS: <release-name>-mosquitto:8883 (when tls.enabled)

Smoke test:

kubectl run mqtt-test --rm -it --restart=Never --image=eclipse-mosquitto -- \
  mosquitto_pub -h <release-name>-mosquitto -t test -m hello

Uninstalling

helm uninstall mosquitto

Note: with the default persistence.retain: true, the data PVC survives helm uninstall; delete it manually if you want the broker state gone.

License

This chart is licensed under the Apache 2.0 License.