# Configuration (/connectors/kafka/concepts/configuration)



## Overview [#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 [#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:

<RunKubeMQ ports="[9092, 9093, 50000]" env="{ CONNECTORS_KAFKA_ENABLE: 'true' }" />

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](/connectors/kafka/concepts/architecture)).

<Callout type="warn">
  This opt-in-by-default posture is also why a multi-node deployment needs one operator habit up
  front: producers must use `acks>=1`. A single Kafka-facing Service can land a produce on any pod,
  and a follower forwards an `acks>=1` produce to the leader transparently — but silently **drops**
  an `acks=0` produce instead of forwarding it. Single-node deployments are unaffected.
</Callout>

## Security posture [#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](/connectors/kafka/how-to/authentication) and
[TLS and mTLS](/connectors/kafka/how-to/tls-and-mtls) walk through configuring each
mechanism; [Configuration reference](/connectors/kafka/reference/configuration) has the
copy-paste TOML/environment/Docker examples.

## How configuration maps to behavior [#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](/configure/reference/connectors#kafka). This page is
orientation, not the source of truth for any individual field.

## Enabling on Kubernetes [#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:

```yaml
# 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](/connectors/kafka/reference/configuration)
and [the Kafka settings reference](/configure/reference/connectors#kafka), not restated
here.

## The next engine relationship [#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 &#x2A;*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](/configure/reference/storage-engines#zero-config-engine-selection).

## Related [#related]

<Cards>
  <Card title="Kafka settings reference" href="/configure/reference/connectors#kafka" description="The canonical field-by-field table — every CONNECTORS_KAFKA_* setting, its default, and its CRD name." />

  <Card title="Configuration reference" href="/connectors/kafka/reference/configuration" description="TOML, environment, and Docker examples for enabling and configuring the connector." />

  <Card title="Authentication" href="/connectors/kafka/how-to/authentication" description="Configure SASL/PLAIN, SCRAM, OAUTHBEARER, mTLS, and the ACL model that authorizes each request." />

  <Card title="Architecture" href="/connectors/kafka/concepts/architecture" description="The wire-protocol listeners, the dispatch surface, and how topics map to Events Store logs." />
</Cards>