Spring Boot

The KubeMQ Spring Boot Starter is a production-quality Spring Boot 3.x and Spring Cloud Stream integration for the KubeMQ message broker. It brings KubeMQ into the Spring programming model through auto-configuration, a thread-safe KubeMQTemplate send API, and annotation-driven listeners — all built on the native KubeMQ Java SDK clients so your application speaks gRPC to the broker directly.

Why Spring Boot + KubeMQ?

• Native Spring idioms — auto-configuration, @ConfigurationProperties bound under kubemq.*, Spring Boot Actuator health contributors, and Micrometer metrics and observations
• Annotation-driven listeners — @KubeMQEventListener, @KubeMQEventStoreListener, @KubeMQQueueListener, @KubeMQCommandHandler, and @KubeMQQueryHandler turn beans into message consumers
• KubeMQTemplate send API — one injectable template covers all five messaging patterns (Events, Events Store, Queues, Commands, Queries) with sync, async, and fluent-builder variants
• Kotlin support — coroutine extensions, Flow adapters, and a configuration DSL via the Kotlin starter
• Spring Cloud Stream binder — bind Events, Events Store, and Queues through the Spring Cloud Stream programming model
• First-class test harness — MockKubeMQServer, TestContainers support, and a test starter for exercising producers and consumers without a live broker

Requirements

The starter targets the JVM and a running KubeMQ broker reachable over native gRPC on port 50000. Supported languages and versions:

Installation

Add the starter dependency — it aggregates the auto-configuration and the KubeMQ Java SDK:

dependencies {
    implementation("io.kubemq:kubemq-spring-boot-starter:1.0.0")
}

Then point the application at your broker. The properties are bound under kubemq.*:

kubemq:
  address: localhost:50000
  client-id: my-app

Inject KubeMQTemplate to send, and annotate a bean method to receive:

@Service
public class OrderService {
    private final KubeMQTemplate template;

    public OrderService(KubeMQTemplate template) {
        this.template = template;
    }

    public void placeOrder(Order order) {
        template.sendEvent("orders", order);
    }
}

@Component
public class OrderConsumer {
    @KubeMQEventListener(channels = "orders")
    public void onOrder(EventMessageReceived event) {
        // process event
    }
}

docker run -d \  --name kubemq \  -p 50000:50000 \  -p 9090:9090 \  -e KUBEMQ_TOKEN=YOUR_LICENSE_KEY \  europe-docker.pkg.dev/kubemq/images/kubemq:next

Modules

The project is a multi-module Gradle build. Add kubemq-spring-boot-starter to your project; the rest are pulled in transitively or added when you need Spring Cloud Stream, Kotlin, or testing support.

Architecture

KubeMQAutoConfiguration wires the native KubeMQ Java SDK clients — PubSubClient, QueuesClient, and CQClient — from your kubemq.* properties. The KubeMQTemplate send API and the @KubeMQ*Listener / @KubeMQ*Handler beans both delegate to those clients, which speak gRPC to the broker on port 50000. There is no connector to enable — the starter is a native SDK client that connects directly.

Auto-configuration binds the three SDK clients from kubemq.* properties; the template and listener beans delegate to them over gRPC on port 50000.

Capabilities

Each capability page documents the Spring API surface (KubeMQTemplate send methods and the @KubeMQ*Listener / @KubeMQ*Handler annotations) and links to the underlying KubeMQ pattern so you learn the concept once.

Quick Links

New to integrations? See what an integration is for the mental model, or start with the KubeMQ Getting Started guide for core broker concepts. This starter speaks native gRPC on port 50000 — it is a direct SDK client, not a connector.