Easegress Configuration for MQTT Proxying of IoT Traffic: A Complete Guide

Easegress configures MQTT proxying through the MQTTProxy object kind, which exposes TCP ports for IoT devices, routes MQTT packet types to protocol-specific pipelines, and supports bidirectional message flow via broker mode and HTTP endpoints.

Easegress is a Cloud Native traffic orchestration system that implements a first-class MQTT proxy for handling IoT traffic at scale. The proxy is defined as a top-level resource processed by the protocol-agnostic pipeline engine, enabling seamless integration between MQTT-enabled devices and backend systems like Kafka according to the megaease/easegress source code.

MQTTProxy Architecture and Core Components

The MQTT proxy implementation centers on the MQTTProxy spec defined in pkg/object/mqttproxy/spec.go. This specification describes how the proxy accepts connections, handles encryption, routes packets, and manages broker behavior.

The MQTTProxy Spec Structure

The Spec struct in pkg/object/mqttproxy/spec.go defines the configuration schema with these key fields:

• Port – The TCP port (default 1883) where MQTT clients connect
• UseTLS – Boolean flag to enable TLS encryption
• Certificate – Array of certificates processed by Spec.tlsConfig() into a Go tls.Config
• Rules – Array routing different MQTT packet types to specific pipelines
• BrokerMode – Boolean enabling bidirectional message distribution
• RetryInterval – Timing for backend reconnection attempts

Broker Mode Implementation

When brokerMode: true is configured, the proxy forwards published messages to both the backend system (e.g., Kafka) and any subscribed MQTT clients. Without broker mode, traffic flows only to the backend. This behavior is implemented in pkg/object/mqttproxy/broker.go, which manages subscription handling and message distribution to active client sessions.

Packet Routing via Rules

Each rule in the Rules array matches a specific packetType (Connect, Publish, Subscribe, Unsubscribe, or Disconnect) and routes matching packets to a named pipeline. The rule matching logic resides in pkg/object/mqttproxy/mqttproxy.go, where the proxy builds internal URLs and registers handlers for the pipeline engine.

Configuring TLS for Secure IoT Connections

To encrypt traffic between IoT devices and the proxy, set useTLS: true and provide certificate data:

useTLS: true
certificate:
  - name: cert1
    cert: |-
      -----BEGIN CERTIFICATE-----
      MIIDXTCCAkWgAwIBAgIJAJC1HiIAZAiU...
      -----END CERTIFICATE-----
    key: |-
      -----BEGIN PRIVATE KEY-----
      MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgw...
      -----END PRIVATE KEY-----

The Spec.tlsConfig() method in pkg/object/mqttproxy/spec.go (lines 8-23) transforms this YAML configuration into a functional Go tls.Config used by the TCP listener.

Pipeline Integration for MQTT Traffic

The MQTT proxy leverages Easegress's protocol-aware pipeline system. Each rule references a pipeline containing MQTT-specific filters that process packets before forwarding.

Authentication Pipelines for Connect Packets

When packetType: Connect matches, the pipeline typically contains the MQTTClientAuth filter to validate credentials:

name: pipeline-mqtt-auth
kind: Pipeline
protocol: MQTT
flow:
  - filter: auth
filters:
  - name: auth
    kind: MQTTClientAuth
    salt: mySalt
    auth:
      - username: device001
        saltedSha256Pass: 1bc1a361f17092bc7af4b2f82bf9194ea9ee2ca49eb2e53e39f555bc1eeaed74

Backend Integration Pipelines for Publish Packets

Publish packets route to pipelines containing the KafkaMQTT filter for backend forwarding:

name: pipeline-mqtt-publish
kind: Pipeline
protocol: MQTT
flow:
  - filter: publish-kafka-backend
filters:
  - name: publish-kafka-backend
    kind: KafkaMQTT
    backend: ["127.0.0.1:9092"]
    topic:
      default: sensor-data-topic

HTTP Publish API for Backend Services

Backend microservices can push messages to subscribed IoT clients via the HTTP endpoint implemented in pkg/object/mqttproxy/broker.go. The handler httpTopicsPublishHandler (lines 150-170) accepts POST requests at /apis/v1/mqttproxy/{name}/topics/publish.

Send messages using standard HTTP clients:

curl -X POST http://127.0.0.1:2381/apis/v1/mqttproxy/mqttproxy/topics/publish \
  -H "Content-Type: application/json" \
  -d '{
        "topic": "Beijing/Phone/Update",
        "qos": 1,
        "payload": "time to update",
        "base64": false
      }'

The request body requires topic, qos, and payload fields, with an optional base64 boolean for binary data encoding.

Practical Configuration Example

Deploy a complete MQTT proxy by combining the spec with its referenced pipelines in a single YAML file:

kind: MQTTProxy
name: mqttproxy
port: 1883
useTLS: true
certificate:
  - name: iot-cert
    cert: |-
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    key: |-
      -----BEGIN PRIVATE KEY-----
      ...
      -----END PRIVATE KEY-----
rules:
  - when:
      packetType: Connect
    pipeline: pipeline-mqtt-auth
  - when:
      packetType: Publish
    pipeline: pipeline-mqtt-publish
brokerMode: true
connectionLimit:
  requestRate: 1000
clientPublishLimit:
  requestRate: 5000
  timePeriod: 1
---
name: pipeline-mqtt-auth
kind: Pipeline
protocol: MQTT
flow:
  - filter: auth
filters:
  - name: auth
    kind: MQTTClientAuth
    salt: mySalt
    auth:
      - username: test
        saltedSha256Pass: 1bc1a361f17092bc7af4b2f82bf9194ea9ee2ca49eb2e53e39f555bc1eeaed74
---
name: pipeline-mqtt-publish
kind: Pipeline
protocol: MQTT
flow:
  - filter: kafka-backend
filters:
  - name: kafka-backend
    kind: KafkaMQTT
    backend: ["127.0.0.1:9092"]
    topic:
      default: kafka-topic

Apply this configuration using the Easegress CLI:

egctl create -f mqtt-proxy.yaml

Rate Limiting and Traffic Management

The MQTT proxy supports granular rate limiting through fields in pkg/object/mqttproxy/spec.go using the RateLimit struct:

• ConnectionLimit – Controls new connection establishment rates (requestRate, bytesRate)
• ClientPublishLimit – Throttles publish packets per client connection with configurable timePeriod

These limits prevent resource exhaustion during traffic spikes from high-volume IoT deployments.

Summary

• MQTTProxy is a top-level resource kind defined in pkg/object/mqttproxy/spec.go that exposes TCP ports (default 1883) for IoT device connections.
• Broker mode enables bidirectional messaging, forwarding publishes to both backend systems and subscribed MQTT clients via logic in pkg/object/mqttproxy/broker.go.
• Rules map MQTT packet types (Connect, Publish, Subscribe) to protocol-specific pipelines containing filters like MQTTClientAuth and KafkaMQTT.
• TLS encryption is configured via useTLS: true and certificate arrays processed by Spec.tlsConfig().
• Backend integration works bidirectionally: IoT devices publish through MQTT while backend services push updates via the HTTP endpoint /apis/v1/mqttproxy/{name}/topics/publish.

Frequently Asked Questions

What is the default port for the Easegress MQTT proxy?

The default port is 1883, the standard MQTT port, configurable via the port field in the MQTTProxy spec. You can change this to any available TCP port, commonly using 8883 when useTLS: true is enabled for MQTT over TLS.

How does broker mode affect message routing?

When brokerMode: true is set, the proxy acts as a full MQTT broker, storing subscriptions in pkg/object/mqttproxy/topicmgr.go and forwarding published messages to both the configured backend (e.g., Kafka) and any connected clients subscribed to matching topics. Without broker mode, messages flow only to the backend pipeline, making the proxy act as a simple protocol translator.

Can the Easegress MQTT proxy authenticate clients with custom credentials?

Yes. The MQTTClientAuth filter in authentication pipelines validates usernames against salted SHA256 hashes. Configure the salt field and auth array in the filter configuration within a pipeline referenced by a Connect packet rule, as implemented in the authentication logic referenced by pkg/object/mqttproxy/mqttproxy.go.

How do backend services publish messages to MQTT clients?

Backend services POST to the HTTP endpoint /apis/v1/mqttproxy/{name}/topics/publish with a JSON body containing the topic, qos, and payload. The handler httpTopicsPublishHandler in pkg/object/mqttproxy/broker.go processes these requests and distributes the message to subscribed clients through the topic manager, enabling server-side logic to communicate with IoT devices without maintaining MQTT client connections.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}