> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/connectors/enterprise-connectors/kafka/kafkaconnection.md). # Kafka Connection Properties ## `brokers` (array, required) List of Kafka bootstrap brokers in `host:port` format. The client uses these only to discover the cluster; it then connects to whichever brokers own the relevant partitions. Provide at least two entries when possible so the client can still bootstrap if a single broker is unavailable. The object is an array with all elements of the type `string`. Examples: `["kafka1:9092","kafka2:9092"]`, `["kafka1:9092","kafka2:9092","kafka3:9092"]` ## `clientType` (string, enum) Determines the role of this connection on the Kafka cluster. A single connection can only host endpoints of one operation type: either all `write` endpoints (producer) or all `subscribe` endpoints (consumer). Use separate connection resources if you need to both publish to and consume from Kafka. A mismatch is not rejected when the service is installed: a `write` on a consumer connection fails with an error response, and a `subscribe` on a producer connection is ignored with a warning in the log. Available options: * `producer` (default): The connection accepts `write` endpoints that publish messages to their configured topic. * `consumer`: The connection accepts `subscribe` endpoints that receive messages from their configured topic. This element must be one of the following enum values: * `producer` * `consumer` Default: `"producer"` ## `groupId` (string) **Only applies when `clientType` is `consumer`.** The Kafka consumer group this client joins. Consumers sharing the same `groupId` cooperatively divide a topic's partitions between them and share committed offsets, so each message in a partition is delivered to only one member of the group. If omitted, the id of the Connection resource is used, which is composed as `-` (for example, `my-service-myKafkaConnection`). This default keeps groups unique per connection within a single Connectware, but is **not** unique across multiple Connectware instances: if two Connectware instances install the same service against the same Kafka broker, both consumers join the same group, and Kafka divides the topic's partitions between them, so each instance only receives part of the messages. With a single-partition topic, only one of the two instances receives anything at all. Set an explicit `groupId` whenever consumers on different Connectware instances must consume the same topic independently, or when you intentionally want several Connectware instances to share consumption of a topic. ## `clientId` (string) Logical identifier sent to the broker on every request. It does not affect message routing, but appears in broker-side logs and metrics, which makes it useful for tracing a particular Connectware connection on the Kafka cluster. Set a distinct value per connection when multiple Connectware instances share the same broker. Default: `"protocol-mapper-kafka"` Example: `"connectware_13462"` ## `connectionTimeout` (integer) Maximum time in milliseconds to wait when establishing a TCP connection to a broker. If the broker does not accept the connection within this period, the attempt fails and the configured retry policy applies. Increase this value on slow or high-latency networks. Default: `1000` ## `requestTimeout` (integer) Maximum time in milliseconds to wait for the broker's response to an individual request (for example, metadata, produce, or fetch). If the broker does not respond within this period, the request fails and the configured retry policy applies. This client-side limit also bounds how long a produce request waits, independently of the broker-side `timeout` configured on a Kafka Endpoint. Default: `10000` ## `trustAllCertificates` (boolean) If `true`, the broker's TLS certificate is accepted without validation against trusted CAs or the broker hostname. This only takes effect when the connection actually uses TLS, which is the case when `mutualAuthentication` is `true` or `sasl` is configured; with neither of them set, the connection is plaintext and this property has no effect. Intended for development and testing with self-signed certificates. Do not enable in production: it disables protection against man-in-the-middle attacks. Default: `false` Examples: `true`, `false` ## `mutualAuthentication` (boolean) If `true`, the client authenticates to the broker using a client certificate (mTLS) in addition to validating the broker's certificate. Requires `clientCert` and `clientPrivateKey` to be set, and `caCert` as well unless the broker certificate is signed by a CA in the system trust store. Cannot be combined with `sasl`: if both are configured, the SASL settings take precedence and the client certificate, private key and CA certificate are silently ignored. Default: `false` Examples: `true`, `false` ## `caCert` (string) PEM-encoded CA certificate (or certificate chain) used to validate the broker's TLS certificate, provided as a single string. Set this when the broker presents a certificate signed by a CA that is not in the system trust store, for example a private or internal CA. This property is only applied when `mutualAuthentication` is `true`. It is not applied to SASL connections, so a SASL broker using a private CA currently requires `trustAllCertificates` to be `true`. It also has no effect when `trustAllCertificates` is `true`, because the broker certificate is then not validated at all. ## `clientCert` (string) PEM-encoded client certificate presented to the broker during the mTLS handshake, provided as a single string. Must be issued by a CA that the broker trusts and paired with the matching `clientPrivateKey`. Only used when `mutualAuthentication` is `true`. ## `clientPrivateKey` (string) PEM-encoded private key that matches `clientCert`, provided as a single string. The key must be unencrypted (no passphrase). Only used when `mutualAuthentication` is `true`. ## `sasl` (object) SASL (Simple Authentication and Security Layer) credentials used to authenticate against the Kafka broker. When set, the connection automatically uses TLS to protect the credentials in transit; the broker must therefore expose a TLS-enabled SASL listener. Cannot be combined with `mutualAuthentication`: if both are configured, these SASL settings take precedence and the client certificate, private key and CA certificate are ignored. Note that `caCert` is not applied to SASL connections either, so a broker whose certificate is signed by a private CA requires `trustAllCertificates` to be `true`. Properties of the `sasl` object: #### `mechanism` (string, enum, required) SASL mechanism used to negotiate authentication with the broker. The selected mechanism must be enabled on the broker. Available options: * `plain`: Username and password are sent to the broker as cleartext inside the TLS-encrypted SASL exchange. Simplest to set up; relies entirely on TLS for credential protection. * `scram-sha-256`: Salted Challenge Response Authentication Mechanism using SHA-256. The password is never sent over the wire. * `scram-sha-512`: SCRAM using SHA-512. Same properties as `scram-sha-256` with a stronger hash function. This element must be one of the following enum values: * `plain` * `scram-sha-256` * `scram-sha-512` #### `username` (string, required) Username of the Kafka principal used to authenticate against the broker. #### `password` (string, required) Password of the Kafka principal used to authenticate against the broker. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.cybus.io/connectors/enterprise-connectors/kafka/kafkaconnection.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.