Configuration

Overview

Configuring the Kafka connector is entirely a server-side decision. A Kafka client configures nothing KubeMQ-specific — it just points bootstrap.servers at the broker and, if the deployment requires it, supplies SASL credentials or a client certificate. Everything below — whether the listeners even open, which ports they bind, which authentication mechanisms are offered, and which storage engine backs the resulting topics — is decided once, on the server, and applies to every client that connects.

Opt-in by design

The connector ships disabled by default. A stock KubeMQ server does not bind port 9092 or 9093, does not advertise itself as a Kafka broker, and imposes zero runtime cost on a deployment that never uses Kafka. You turn it on with one flag:

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

Setting CONNECTORS_KAFKA_ENABLE=false again closes both listeners immediately — a config-only rollback with nothing to migrate, because the connector never owned a separate data store to begin with: every produced record already lives in a plain Events Store log (see Architecture).

Security posture

At a glance, the connector supports the same authentication and authorization shape a real Kafka deployment does, at the same layers:

• SASL — PLAIN and both SCRAM-SHA-256/SCRAM-SHA-512 mechanisms are available once any Kafka credential is configured; a client authenticates with a username and password checked against the connector's own dedicated credential store, separate from KubeMQ's general-purpose auth.
• OAUTHBEARER — OIDC-federated bearer tokens, validated against a configured issuer and offered only on the TLS listener — a bearer token is never accepted over plaintext.
• mTLS — a client certificate presented on the TLS listener yields a principal derived from the certificate's common name, and only from a verified certificate chain.
• ACLs — every request that reaches dispatch is authorized against KubeMQ's own policy engine, mapped onto the access level Kafka would expect: a produce or an offset commit needs write access, while a fetch or a group heartbeat needs read access.

None of this is mutually exclusive — a deployment can run SASL/SCRAM on the plaintext listener for internal traffic and OAUTHBEARER plus mTLS on the TLS listener for anything crossing a trust boundary. Authentication and TLS and mTLS walk through configuring each mechanism; Configuration reference has the copy-paste TOML/environment/Docker examples.

How configuration maps to behavior

Every Kafka setting can be supplied three ways — a [Connectors.Kafka] block in a TOML config file, a CONNECTORS_KAFKA_* environment variable, or (on Kubernetes) a typed field under spec.kafka on the KubeMQ cluster resource — and all three ultimately populate the same in-memory configuration the connector reads once at startup. That single source of truth is why the connector's runtime behavior is fully predictable from its configuration: the enable flag gates whether the listeners open at all, the port fields decide what a client dials, the credential and SASL-mechanism fields decide what the security posture above actually offers, and a handful of numeric fields — maximum connections, maximum message size, per-request fan-out caps — bound how much of the shared server the connector is allowed to consume.

The full field-by-field table — every setting, its default, its valid range, and its exact environment-variable and CRD names — lives in one canonical place: the Kafka settings reference. This page is orientation, not the source of truth for any individual field.

Enabling on Kubernetes

The Kubernetes path is the same one-liner as the Docker flag above, expressed as a typed field instead of an environment variable:

# Helm values
kafka:
  enabled: true

The equivalent CRD field is spec.kafka.enabled: true on the KubemqCluster resource. On a fresh cluster this one field is enough — no engine choice, no networking configuration — the connector opens an in-cluster, plaintext endpoint at <cluster>-kafka.<namespace>.svc:9092 that any in-cluster client can dial immediately. Reaching that endpoint from outside the cluster needs two more fields, advertisedHost and advertisedPort, plus a LoadBalancer or NodePort Service exposure — covered in Configuration reference and the Kafka settings reference, not restated here.

The next engine relationship

One configuration consequence deserves its own callout: enabling Kafka couples the deployment to KubeMQ's next storage engine, because Kafka's headline behaviors — compacted topics and the quorum-fsynced acknowledgment contract — exist only there. You do not configure this coupling directly. On a fresh store, enabling Kafka auto-selects next automatically; on a store that already has data under the other engine, enabling Kafka fails closed with a clear configuration error instead of silently running in a reduced mode. The full decision tree — fresh store, existing store, explicit pin — lives at Storage Engines → Zero-config engine selection.

Related