mosquitto/README.md

Mosquitto MQTT Broker on Kubernetes

This project deploys a secure Mosquitto MQTT broker inside Kubernetes with:

• TLS Encryption (auto-generated via cert-manager with a self-signed CA)
• User Authentication (username/password using Kubernetes Secrets)
• Access Control List (ACL) for fine-grained publish/subscribe permissions
• Persistent Storage using PVCs
• TCP passthrough for MQTT over TLS and WebSocket Secure (WSS) via Ingress-NGINX

---

📂 Project Structure

├── ConfigMap-ingress-nginx.yaml        # TCP passthrough ConfigMap for NGINX (ports 8883/9443) 
├── ConfigMap.yaml                      # Mosquitto main configuration (mosquitto.conf) 
├── README.md                           # This documentation 
├── deployment.yaml                     # Mosquitto Kubernetes Deployment 
├── mosquitto-acl-secret.yaml           # ACL file as a Kubernetes Secret 
├── mosquitto-internal-tls.yaml         # TLS Certificate and CA with cert-manager 
├── mosquitto-passwd-secret.yaml        # Password file as a Kubernetes Secret 
├── namespace.yaml                      # Namespace definition 
├── pvc.yaml                            # Persistent Volume Claim for Mosquitto data 
└── svc.yaml                            # Mosquitto Services (ClusterIP)

🔒 User Authentication

There are two users configured :

Username	Permissions	Description
pubuser	publish + subscribe	Used by publishers
subuser	subscribe only	Used by all subscribers

Passwords are securely stored in mosquitto-passwd-secret.yaml

📜 ACL Rules

ACL (Access Control List) enforces:

• pubuser: can publish and subscribe on all topics (#)
• subuser: can only subscribe to all topics (#)

ACL file is stored in mosquitto-acl-secret.yaml.

🔐 TLS Security

• Self-signed CA generated via cert-manager
• Broker certificates issued automatically
• Clients must trust the ca.crt (exported from Kubernetes)

📡 MQTT Ports

Service	Port	Description
MQTT over TLS	8883	Secure MQTT
WebSocket Secure (WSS)	9443	Secure WebSocket for MQTT

TCP ports are passed directly to Mosquitto via NGINX Ingress TCP services.