# Configuration Reference (/integrations/spring-boot/reference/configuration)



This page is the authoritative reference for the KubeMQ Spring Boot Starter's configuration surface: the module coordinates and every `kubemq.*` property bound from `KubeMQProperties`. For the runtime API (the `KubeMQTemplate` send methods, listener annotations, the Spring Cloud Stream binder, and Actuator endpoints), see the [API reference](/integrations/spring-boot/reference/api).

## Modules & Coordinates [#modules--coordinates]

The project is a multi-module Gradle build published under group `io.kubemq` at version `1.0.0`. Most applications add only `kubemq-spring-boot-starter`; the binder, Kotlin, and test modules are added when you need them.

| Module (artifact ID)                | Group       | Version | Purpose                                                                     |
| ----------------------------------- | ----------- | ------- | --------------------------------------------------------------------------- |
| `kubemq-spring-boot-autoconfigure`  | `io.kubemq` | `1.0.0` | Auto-configuration, `KubeMQTemplate`, listener annotations, health, metrics |
| `kubemq-spring-boot-starter`        | `io.kubemq` | `1.0.0` | Dependency aggregator — add this to your project                            |
| `kubemq-spring-cloud-stream-binder` | `io.kubemq` | `1.0.0` | Spring Cloud Stream binder for Events, Events Store, and Queues             |
| `kubemq-spring-boot-starter-kotlin` | `io.kubemq` | `1.0.0` | Kotlin coroutine extensions, `Flow` adapters, and configuration DSL         |
| `kubemq-spring-boot-starter-test`   | `io.kubemq` | `1.0.0` | `MockKubeMQServer`, TestContainers, and test harness                        |

```kotlin title="build.gradle.kts"
dependencies {
    implementation("io.kubemq:kubemq-spring-boot-starter:1.0.0")

    // Add only when you need them:
    implementation("io.kubemq:kubemq-spring-cloud-stream-binder:1.0.0")
    implementation("io.kubemq:kubemq-spring-boot-starter-kotlin:1.0.0")
    testImplementation("io.kubemq:kubemq-spring-boot-starter-test:1.0.0")
}
```

<Callout type="info">
  Start a local broker with Docker — the gRPC API the starter connects to listens on `50000`, and the shared HTTP/REST and dashboard endpoints on `9090`:

  <RunKubeMQ ports="[50000, 9090]" />

  The Spring Boot Starter speaks gRPC to the broker on `50000` through the native KubeMQ Java SDK — there is no connector enable flag to set.
</Callout>

## Configuration Properties [#configuration-properties]

All properties are bound from `KubeMQProperties` under the `kubemq.*` prefix. `Duration` values accept Spring's duration syntax (`30s`, `5m`, `100ms`), and `DataSize` values accept sizes such as `100MB`.

### Top-Level Properties [#top-level-properties]

| Property            | Type      | Default           | Description                                                                      |
| ------------------- | --------- | ----------------- | -------------------------------------------------------------------------------- |
| `kubemq.enabled`    | `boolean` | `true`            | Master switch for all KubeMQ auto-configuration.                                 |
| `kubemq.address`    | `String`  | `localhost:50000` | KubeMQ server gRPC address in `host:port` format.                                |
| `kubemq.client-id`  | `String`  | `""`              | Client identifier sent with every request. Empty means the SDK generates a UUID. |
| `kubemq.auth-token` | `String`  | `""`              | JWT/OIDC authentication token.                                                   |

```yaml title="application.yml"
kubemq:
  enabled: true
  address: localhost:50000
  client-id: my-app
  auth-token: ""
```

### TLS — `kubemq.tls.*` [#tls--kubemqtls]

Bound from `KubeMQProperties.Tls`. Configures TLS/mTLS for the gRPC connection.

| Property                  | Type      | Default | Description                                                    |
| ------------------------- | --------- | ------- | -------------------------------------------------------------- |
| `kubemq.tls.enabled`      | `boolean` | `false` | Enable TLS for the gRPC connection.                            |
| `kubemq.tls.cert-file`    | `String`  | `""`    | Path to the client certificate (mTLS).                         |
| `kubemq.tls.key-file`     | `String`  | `""`    | Path to the client private key (mTLS).                         |
| `kubemq.tls.ca-cert-file` | `String`  | `""`    | Path to the CA certificate that signed the server certificate. |

```yaml title="application.yml"
kubemq:
  tls:
    enabled: true
    cert-file: /etc/kubemq/tls/client.crt
    key-file: /etc/kubemq/tls/client.key
    ca-cert-file: /etc/kubemq/tls/ca.crt
```

### Connection — `kubemq.connection.*` [#connection--kubemqconnection]

Bound from `KubeMQProperties.Connection` and `KubeMQProperties.KeepAlive`. Tunes the gRPC channel.

| Property                               | Type       | Default | Description                                                                       |
| -------------------------------------- | ---------- | ------- | --------------------------------------------------------------------------------- |
| `kubemq.connection.timeout`            | `Duration` | `30s`   | Connection establishment timeout.                                                 |
| `kubemq.connection.max-receive-size`   | `DataSize` | `100MB` | Maximum inbound message size on the gRPC channel.                                 |
| `kubemq.connection.keep-alive.time`    | `Duration` | `30s`   | Interval between gRPC keep-alive pings.                                           |
| `kubemq.connection.keep-alive.timeout` | `Duration` | `10s`   | Time to wait for a keep-alive ping acknowledgement before closing the connection. |

```yaml title="application.yml"
kubemq:
  connection:
    timeout: 30s
    max-receive-size: 100MB
    keep-alive:
      time: 30s
      timeout: 10s
```

### Listener — `kubemq.listener.*` [#listener--kubemqlistener]

Bound from `KubeMQProperties.Listener` and the per-pattern nested classes. These are the defaults applied to every `@KubeMQ*Listener` / `@KubeMQ*Handler`; individual annotations can override them.

The top-level listener settings apply to all patterns:

| Property                           | Type       | Default | Description                                               |
| ---------------------------------- | ---------- | ------- | --------------------------------------------------------- |
| `kubemq.listener.concurrency`      | `int`      | `1`     | Number of concurrent message processors per listener.     |
| `kubemq.listener.auto-startup`     | `boolean`  | `true`  | Whether listeners start with the application context.     |
| `kubemq.listener.shutdown-timeout` | `Duration` | `30s`   | Grace period for draining in-flight messages on shutdown. |

Queue listeners add poll-loop and acknowledgement settings (`KubeMQProperties.QueuesListener`):

| Property                                          | Type       | Default | Description                                                     |
| ------------------------------------------------- | ---------- | ------- | --------------------------------------------------------------- |
| `kubemq.listener.queues.poll-timeout`             | `Duration` | `5s`    | Maximum time to wait for messages per poll cycle.               |
| `kubemq.listener.queues.max-poll-messages`        | `int`      | `1`     | Maximum messages returned per poll.                             |
| `kubemq.listener.queues.visibility-timeout`       | `Duration` | `30s`   | Time received messages stay hidden from other consumers.        |
| `kubemq.listener.queues.auto-ack`                 | `boolean`  | `false` | Whether messages are acknowledged automatically on receipt.     |
| `kubemq.listener.queues.error-backoff-initial`    | `Duration` | `1s`    | Initial backoff after a poll-loop error.                        |
| `kubemq.listener.queues.error-backoff-max`        | `Duration` | `30s`   | Maximum backoff between retries.                                |
| `kubemq.listener.queues.error-backoff-multiplier` | `double`   | `2.0`   | Multiplier applied to the backoff after each consecutive error. |

Command and query handlers add a response timeout (`KubeMQProperties.CommandsListener` / `KubeMQProperties.QueriesListener`):

| Property                           | Type       | Default | Description                            |
| ---------------------------------- | ---------- | ------- | -------------------------------------- |
| `kubemq.listener.commands.timeout` | `Duration` | `10s`   | Response timeout for command handlers. |
| `kubemq.listener.queries.timeout`  | `Duration` | `10s`   | Response timeout for query handlers.   |

<Callout type="info">
  Events are push-based subscriptions in KubeMQ, so `kubemq.listener.events` has no poll-related settings — it is reserved for future events-specific configuration.
</Callout>

```yaml title="application.yml"
kubemq:
  listener:
    concurrency: 1
    auto-startup: true
    shutdown-timeout: 30s
    queues:
      poll-timeout: 5s
      max-poll-messages: 1
      visibility-timeout: 30s
      auto-ack: false
      error-backoff-initial: 1s
      error-backoff-max: 30s
      error-backoff-multiplier: 2.0
    commands:
      timeout: 10s
    queries:
      timeout: 10s
```

### Template, Health, Metrics & Kotlin [#template-health-metrics--kotlin]

The remaining nested groups on `KubeMQProperties` control the send-side template, the Actuator health indicator, Micrometer metrics, and Kotlin coroutine support.

| Property                              | Type       | Default   | Description                                                                                   |
| ------------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------- |
| `kubemq.template.observation-enabled` | `boolean`  | `true`    | Wrap `KubeMQTemplate` sends in a Micrometer `Observation`. Requires an `ObservationRegistry`. |
| `kubemq.health.enabled`               | `boolean`  | `true`    | Register the KubeMQ Actuator health indicator.                                                |
| `kubemq.health.timeout`               | `Duration` | `5s`      | Per-client ping timeout for the health check.                                                 |
| `kubemq.health.cache-duration`        | `Duration` | `15s`     | How long a health result is cached before re-probing the broker.                              |
| `kubemq.metrics.enabled`              | `boolean`  | `true`    | Register Micrometer metrics for KubeMQ operations.                                            |
| `kubemq.metrics.scrape-interval`      | `Duration` | `30s`     | Interval for periodic metric collection.                                                      |
| `kubemq.kotlin.dispatcher`            | `String`   | `default` | Coroutine dispatcher for suspend-function listeners. One of `default`, `io`, or `unconfined`. |

```yaml title="application.yml"
kubemq:
  template:
    observation-enabled: true
  health:
    enabled: true
    timeout: 5s
    cache-duration: 15s
  metrics:
    enabled: true
    scrape-interval: 30s
  kotlin:
    dispatcher: default
```

## Requirements & Compatibility [#requirements--compatibility]

| Requirement                  | Version                  |
| ---------------------------- | ------------------------ |
| Java                         | 17+                      |
| Spring Boot                  | 3.2.0+                   |
| Spring Cloud (binder module) | 2023.0.0                 |
| KubeMQ broker                | gRPC API on port `50000` |

The starter sets `sourceCompatibility`/`targetCompatibility` to Java 17 and imports the `spring-boot-dependencies:3.2.0` BOM. The Spring Cloud Stream binder additionally imports the `spring-cloud-dependencies:2023.0.0` BOM.

## Related [#related]

<Cards>
  <Card title="API Reference" href="/integrations/spring-boot/reference/api" description="The KubeMQTemplate send methods, listener annotation attributes, the binder, and Actuator endpoints." />

  <Card title="Configure Connection, TLS, and Observability" href="/integrations/spring-boot/how-to/configure-connection-tls-observability" description="Task-focused walkthrough of the connection, security, and observability settings." />
</Cards>