# Client Configuration Settings for Confluent Cloud Configure Kafka producer and consumer properties to optimize performance, reliability, and resilience for Confluent Cloud streaming applications. Key properties include `linger.ms`, `batch.size`, `retries`, `acks`, and `socket.connection.setup.timeout.ms` for Java and librdkafka clients. Handle common errors like `NOT_LEADER_OR_FOLLOWER`, `LEADER_NOT_AVAILABLE`, and `UNKNOWN_TOPIC_OR_PARTITION` that occur during cluster upgrades and rolling restarts. For in-depth producer and consumer concepts, see [Kafka Producer for Confluent Cloud](producer.md#kafka-producer-cc) and [Kafka Consumer for Confluent Cloud](consumer.md#kafka-consumer-cc). ## Recommendations Consider the following client configuration recommendations: * Always use current, supported clients. Current clients contain bug fixes and default settings tuned to allow clients to gracefully handle warnings without disrupting your streaming applications. For more information, see [Client versions and support](overview.md#client-support-matrix). * Rely on the existing retry logic to resolve retryable errors and warnings. * Trigger alerts on actual errors, not retryable errors and warnings. The warnings listed in [Cluster Upgrades and Error Handling](https://docs.confluent.io/cloud/current/client-apps/client-configs.html#cluster-upgrades-and-error-handling) occur regularly as part of normal cluster operations and may not have any impact on your workload. * If you are using consumer groups, configure your consumers with `group.protocol=CONSUMER` to enable the next generation of the rebalance protocol, available in Confluent Cloud. The Java client supports this protocol as of version 4.0 of Apache Kafka®, and the librdkafka clients support this protocol as of version 2.12.0. Use this protocol for faster rebalances, more stable consumer groups, and simplified consumers. See [Rebalance Protocols](https://docs.confluent.io/cloud/current/client-apps/consumer.html#overview-of-the-rebalance-protocols). For additional recommendations on how to architect, monitor, and optimize your Kafka applications on Confluent Cloud, see [Build Streaming Applications](index.md#ccloud-best-practices). ## Transport Layer Security (TLS) and Connection Requirements To protect data in transit between Confluent Cloud resources (for example, Kafka clusters, Confluent Cloud Schema Registry, and API endpoints) and your connecting clients and applications, Confluent Cloud supports [Transport Layer Security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security) encryption, the successor of the now-deprecated Secure Socket Layer (SSL). For details on TLS encryption on Confluent Cloud, see [Manage Data in Transit with TLS on Confluent Cloud](../security/encrypt/tls.md#manage-data-in-transit-with-tls). ### TLS SNI extension requirement The client libraries you use to connect to Confluent Cloud must include a Server Name Indication (SNI) extension in the TLS handshake. Note that the client libraries that Confluent provides do include the SNI extension in the TLS handshake. For Kafka protocol connections (which use port 9092), the SNI extension must be set to the DNS hostname of the bootstrap endpoint or one of the Kafka brokers. 1. For initial connections to the cluster, they include the configured bootstrap endpoint as the SNI extension. 2. For the subsequent connections to individual brokers which are made after bootstrapping, they include that specific broker’s endpoint as the SNI extension. These broker endpoints are automatically discovered as part of client bootstrapping and do not need to be configured. For REST connections (which use port 443), the SNI extension must be set to the DNS hostname of the REST endpoint. Any forward proxies deployed in your environment that are in the path of the network traffic to Confluent Cloud must be configured to forward the SNI extension unmodified. For testing conformance with TLS SNI requirements, see [TLS connectivity testing](../networking/testing.md#test-tcp-sni-connectivity). See [Transport Layer Security (TLS) Extensions: Server Name Indication](https://datatracker.ietf.org/doc/html/rfc6066#section-3) and [The Transport Layer Security (TLS) Protocol Version 1.3: Server Name Indication](https://datatracker.ietf.org/doc/html/rfc8446#section-4.2). ### Manage TLS certificates Confluent Cloud employs TLS certificates from [Let’s Encrypt](https://letsencrypt.org/), a trusted certificate authority. The Let’s Encrypt chain of trust is available for verification: [Chain of Trust](https://letsencrypt.org/certificates/). Confluent Cloud uses the TLS certificates from Let’s Encrypt to sync them to all data plane components that require TLS termination. Because Let’s Encrypt certificates are subject to change, Confluent Cloud might update these intermediate certificates at any time. Review the following recommendations to ensure that your clients and applications can connect to Confluent Cloud without interruption: * **Avoid certificate pinning** because it can introduce connection failures. Confluent might change intermediate certificates or their properties at any time. If the pinned certificate you use is replaced, then your applications will fail to connect. * If your organization requires pinning, then pin to the [Let’s Encrypt ISRG Root X1 certificate](https://letsencrypt.org/certificates/) instead of any subordinate (intermediate) certificate. * If Confluent switches CA providers, connections to your applications might be impacted. To avoid connection failures, you can pin to the root certificate to avoid subordinate (intermediate) certificates that are subject to change. ## Client Prerequisites and Version Requirements * Before connecting a client application to Confluent Cloud, increase the timeout for API version requests from the default value of 10 seconds. You can change this with librdkafka `api.version.request.timeout.ms` parameter. For more information, see the [librdkafka configuration documentation](https://github.com/edenhill/librdkafka/blob/master/CONFIGURATION.md). * For librdkafka versions prior to 2.11, specify the location of your client configuration for TLS (`ssl.ca.location`) if your operating system and configuration requires it, for example, if your OS does not provide root CA certificates or if the certificates are stored in a non-standard location. Starting with librdkafka 2.11 or later, CA certificate configuration for HTTPS has been improved to automatically probe several paths when OpenSSL is statically linked and provides better customization options. In most cases, the `ssl.ca.location` parameter is no longer required to be explicitly set. * For librdkafka-based clients (C/C++, .NET, Python, and Go), to connect to Confluent Cloud, you need [Let’s Encrypt](https://letsencrypt.org/) TLS certificates installed locally. For RHEL and CentOS, these certificates are not included and must be downloaded. * For Java clients, use Java 8 or Java 11. Java 7 and earlier versions are no longer supported. Use the latest patch release of each major version to ensure known security vulnerabilities are addressed. ## JVM settings for Java clients There are two recommended JVM settings for Java clients when interacting with Confluent Cloud: - JVM Security configuration ```none java.security.Security.setProperty(“networkaddress.cache.ttl” , “30"); java.security.Security.setProperty(“networkaddress.cache.negative.ttl” , “0"); ``` - Kafka Producer and Consumer configuration ```none consumer.client.dns.lookup="use_all_dns_ips" producer.client.dns.lookup="use_all_dns_ips" ``` ## Cluster upgrades and error handling Confluent Cloud regularly updates clusters to perform [upgrades and maintenance](../release-notes/upgrade-policy.md#minor-ccloud-upgrade). During this process, Confluent performs [rolling restarts](../_glossary.md#term-rolling-restart) of all the brokers in a cluster. The Kafka protocol and architecture are designed for this type of highly-available, fault-tolerant operation. To ensure seamless client handling of cluster updates, you must configure your clients using [current client libraries](overview.md#client-support-matrix). Confluent recommends you use the strategies for error handling outlined below. During normal cluster operations that use a rolling restart, clients may encounter the following warning exceptions: ```none UNKNOWN_TOPIC_OR_PARTITION: "This server does not host this topic-partition." ``` ```none LEADER_NOT_AVAILABLE: "There is no leader for this topic-partition as we are in the middle of a leadership election." ``` ```none NOT_COORDINATOR: "This is not the correct coordinator." ``` ```none NOT_ENOUGH_REPLICAS: "Messages are rejected since there are fewer in-sync replicas than required." ``` ```none NOT_ENOUGH_REPLICAS_AFTER_APPEND: "Messages are written to the log, but to fewer in-sync replicas than required." ``` ```none NOT_LEADER_OR_FOLLOWER: "This server is not the leader for the given partition." ``` ```none KAFKA_STORAGE_ERROR: "Disk error when trying to access log file on the disk." ``` The following message is what a client would log at `WARN` level if the client attempts to connect to a broker that restarted for maintenance: ```none "Connection to node {} ({}) terminated during authentication. This may happen due to any of the following reasons: (1) Authentication failed due to invalid credentials with brokers older than 1.0.0, (2) Firewall blocking Kafka TLS traffic (eg it may only allow HTTPS traffic), (3) Transient network issue." ``` Configure clients with a sufficient number of retries or retry time to prevent these warning exceptions from getting logged as errors. * By default, Kafka producer clients retry for two minutes, print these warnings to logs, and recover without any intervention. * By default, Kafka consumer and admin clients retry for one minute. Timeout exceptions will occur if clients run out of memory buffer space while retrying or if clients run out of time while waiting for memory. In general, planning for volatility is a basic tenet of building cloud-native client applications. In addition to normal cluster operations, brokers may disappear for a variety of reasons, such as issues with the underlying infrastructure at the cloud-provider layer. For more information, see [Cloud-native applications](architecture.md#ccloud-architecture-cloud-native-apps). ## Client configuration properties Client configuration properties for an Apache Kafka® Producer or Consumer determine how the client interacts with a Kafka cluster. You can tweak several default configuration property settings to achieve better performance based on the workload. ## Why tuning client configurations is important Kafka client configurations provide flexibility and control over various aspects of the client’s behavior, performance, security, and reliability. Properly tuning these configurations helps optimize the client’s interactions with the Kafka cluster and ensures efficient message processing. The following are two specific areas where ensuring correct settings positively impacts the workload: * **Performance**: Client configurations can be adjusted to optimize performance. Adjusting properties that control batching, compression, linger, and prefetch can significantly impact client throughput, latency, and resource utilization. * **Error handling**: Kafka clients need to handle errors with retries, or fail gracefully until a solution can be implemented to resolve the error. Ensuring the configuration is correct can enhance workload resilience and ensure reliability for mission-critical applications. ## Configuration categories Client configuration properties are grouped into the following configuration categories: * **Connection and network** properties: A Kafka client must establish a connection with Confluent clusters to produce and consume messages. This category includes settings for bootstrap servers, connection timeout, and network buffer sizes. Optimizing these settings can ensure reliable and efficient communication between the client and the Kafka cluster. * **Security and authentication** properties: Kafka supports various security mechanisms, such as SSL/TLS encryption, SASL authentication, and authorization using Access Control Lists (ACLs). This category includes security-related settings, such as SSL certificates, authentication protocols, and user credentials. Properly configuring security settings ensures the confidentiality, integrity, and authenticity of the communication between clients and the Kafka cluster. * **Message processing** properties: Kafka clients can process messages in various ways, such as consuming messages from specific topics, committing message offsets, or specifying how to handle message errors. This category includes `max.poll.records`, `auto.commit.interval.ms`, `acks`, and several others. Fine-tuning these property settings may improve client throughput, fault tolerance, and processing guarantees. ## Configuration properties The following tables provide several important configuration properties for Java and librdkafka clients. For a complete listing of configuration properties, see the following documentation: * [Kafka Producer Configurations](/platform/current/installation/configuration/producer-configs.html) * [Kafka Consumer Configurations](/platform/current/installation/configuration/consumer-configs.html) * [librdkafka Configurations](/platform/current/clients/librdkafka/html/md_CONFIGURATION.html) ### Before you modify properties Before you start modifying client configuration properties to find out if you can tweak client performance, be sure to complete the following steps. 1. Verify your client is using default configuration properties. Someone may have changed configuration properties from their default settings. 2. Update your client to the latest supported version available. Default configuration property settings are optimized in later clients. For more information, see [Client versions and support](overview.md#client-support-matrix). #### IMPORTANT When modifying configuration properties, monitor the impact on your system and ensure it behaves as expected. Always test any changes in a staging or pre-production environment before rolling them out to production. ### Common properties The following table provides several common configuration properties for Producers and Consumers that you can review for potential modification. | Configuration property | Java default | librdkafka default | Notes | |------------------------------------------|-------------------|------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `client.id` | empty string | rdkafka | You should set the `client.id` to something meaningful in your
application, especially if you are running multiple clients or want to
easily trace logs or activities to specific client instances. | | `connections.max.idle.ms` | 540000 ms (9 min) | See librdkafka `socket.timeout.ms` | You can change this when an intermediate load balancer disconnects idle
connections after inactivity. For example: AWS 350 seconds, Azure 4
minutes, Google Cloud 10 minutes. | | `sasl.kerberos.service.name` | null | kafka | Changing the default service name will cause issues for those who don’t
have it configured. | | `socket.connection.setup.timeout.max.ms` | 30000 ms (30 sec) | not available | librdkafka doesn’t have exponential backoff for this timeout. | | `socket.connection.setup.timeout.ms` | 10000 ms (10 sec) | 30000 ms (30 sec) | librdkafka doesn’t have exponential backoff for this timeout. | | `metadata.max.age.ms` | 300000 ms (5 min) | 900000 ms (15 min) | librdkafka has the `topic.metadata.refresh.interval.ms` property that
defaults to 300000 milliseconds (5 minutes). | | `reconnect.backoff.max.ms` | 1000 ms (1 sec) | 10000 ms (10 sec) | | | `reconnect.backoff.ms` | 50 ms | 100 ms | | | `max.in.flight.requests.per.connection` | 5 | 1000000 | librdkafka produces to a single partition per batch, setting it to 5
limits producing to 5 partitions per broker. | ### Producer properties The following table provides a few configuration properties for Producers that you can review for potential modification. | Configuration property | Java default | librdkafka default | Notes | |--------------------------|--------------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `batch.size` | 16384 | 1000000 | | | `delivery.timeout.ms` | 120000 ms (2 min) | 300000 ms (5 min) | | | `linger.ms` | 0 ms | 5 ms | librdkafka `linger.ms` reduces the number of in-flight Produce requests
and increases batching (see `max.in.flight.requests.per.connection`) | | `enable.idempotence` | true | false | Enabling idempotence sets `max.in.flight.requests.per.connection` to
`5` (see `max.in.flight.requests.per.connection`) | | `partitioner` | murmur2_random (default Kafka partitioner) | consistent_random | Changing the default partitioner causes the client to send keyed messages to
different partitions. If both a librdkafka-based and a Java Client are producing
to the same topic, change this property to murmur2_random for the librdkafka client
so that messages with the same key are sent to the same partition. | ### Consumer properties The following table provides a few configuration properties for Consumers that you can review for potential modification. | Configuration property | Java default | librdkafka default | Notes | |---------------------------------|------------------------------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `group.protocol` | classic | classic | Set it to `consumer` to enable the new group rebalance protocol.
It is production-ready in Confluent Cloud, and Confluent Platform as of version 8.0.
Clients need to enable it with this configuration.
The new protocol significantly improves rebalances and group stability.
Supported by the Java client as of version 4.0 of Apache Kafka®,
and the librdkafka clients as of version 2.12.0. | | `allow.auto.create.topics` | true | false | | | `isolation.level` | read_uncommitted | read_committed | | | `partition.assignment.strategy` | RangeAssignor, CooperativeStickyAssignor | range, roundrobin | Online upgrade from eager to cooperative assignor is not supported in
librdkafka. | | `check.crcs` | true | false | Record checksum validation comes at slightly increased CPU usage.
Checksum is also present at the IPv4 and TCP layers. Other types of
checks could be available at disk sector (ECC) or file system level (not
in ext4 by default). | ## OpenId Connect (OIDC) and token retry behavior The OIDC retry behavior handles operations such as retrieving a new authentication tokens or refreshing existing tokens. Before modifying configuration properties related to retry behavior, read this section to understand how it works for your client. ### Java Client The token refresh process begins when a credential’s lifetime reaches a specified percentage. This percentage is 80% by default, but you can configure a different value by implementing the `org.apache.kafka.common.security.oauthbearer.OAuthBearerToken` interface in a custom class and specifying the token lifetime. If an authentication error occurs during the token refresh process, the client waits 10 seconds before retrying the token refresh. You cannot configure the wait time before the refresh retry. There are no maximum number of tries for token refresh. The token refresh process continues to retry until it succeeds or the application is closed. The underlying HTTP request to fetch the token from the identity provider (IdP) uses an exponential retry delay mechanism (backoff). This retry delay mechanism doubles after each failed attempt. By default, the retry backoff starts at 100 ms and increase up to a maximum of 10000 ms. You can configure alternatives values if you like by configuring `sasl.oauthbearer.jwks.endpoint.retry.backoff.ms` and `sasl.oauthbearer.jwks.endpoint.retry.backoff.max.ms`. ### Schema Registry Java Client The retry behavior for this client is identical to the Java Client. By default, the retry starts at 100 ms and increases up to a maximum of 10000ms. You can configure alternative values if you like by configuring `sasl.oauthbearer.jwks.endpoint.retry.backoff.ms` and `sasl.oauthbearer.jwks.endpoint.retry.backoff.max.ms`. ### JavaScript Client for Kafka The token refresh process begins when a credential’s lifetime reaches 80%. The token refresh can fail due to one of these error codes: | Code | Description | |--------|-----------------------| | `408` | Request timeout | | `425` | Too early | | `429` | Too many requests | | `500` | Internal server error | | `502` | Bad gateway | | `503` | Service unavailable | | `504` | Gateway timeout | To see the errors in the source [go here](https://github.com/confluentinc/librdkafka/blob/v2.6.0/src/rdhttp.c#L268). If any of these errors occur, the retry process attempts four retries with backoff (5s, 10s, 15s, 20s), with no error logging. If the process returns a different error code, or if all the retries fail, then the process logs an error and repeats the same process with a linear backoff (1+4) tries after 10s. This process continues until retry succeeds or the token expires. If all attempts to refresh a token fail and the token expires, produce and fetch operations begin failing also. If you would like to add custom behavior, for example, jitter, or different timeouts, you can write an application-side token refresh callback. It replaces the process of fetching the credentials and the 1+4 tries. The library triggers the custom callback at 80% of token expiry duration, and in case the callback signals failure, it is re-triggered after 10s. ### Schema Registry JavaScript Client The token refresh process begins at 30 minutes before the token expires. If token retrieval fails due to a `429` rate limitation error, the process retries `maxRetries`, from a `retriesWaitMs` minimum to a maximum `retriesMaxWaitMs` delay. You can configure these retry properties on your client, for example: ```javascript const clientConfig = { baseURLs: ['http://my-schema-registry:8081'], maxRetries: 5, retriesWaitMs: 1000, retriesMaxWaitMs: 8000, }; ``` After each retry, the delay value before the next retry increases exponentially by multiples of two, with full jitter. Full jitter means the retry process multiplies the delay value by a random number from zero to one to determine the actual delay. Any other non-retriable error code causes the process to throw an error. Token retrieval at startup follows the same retry pattern. ### librdkafka derived (non-Java) clients For these clients, the token refresh process is identical to the JavaScript Client for Kafka. For additional information about optimizing and tuning clients, see [Optimize and Tune Confluent Cloud Clients](optimizing/overview.md#ccloud-optimizing).