// This module is included in:
//
// overview/assembly-configuration-points.adoc

[id="configuration-points-broker_{context}"]
= Kafka cluster configuration

A kafka cluster comprises one or more brokers.
For producers and consumers to be able to access topics within the brokers, Kafka configuration must define how data is stored in the cluster, and how the data is accessed.
You can configure a Kafka cluster to run with multiple broker nodes across racks.

Storage::
Kafka and ZooKeeper store data on disks.
+
Strimzi requires block storage provisioned through `StorageClass`.
The file system format for storage must be _XFS_ or _EXT4_.
Three types of data storage are supported:
+
--
Ephemeral (Recommended for development only):: Ephemeral storage stores data for the lifetime of an instance. Data is lost when the instance is restarted.
Persistent:: Persistent storage relates to long-term data storage independent of the lifecycle of the instance.
JBOD (Just a Bunch of Disks, suitable for Kafka only):: JBOD allows you to use multiple disks to store commit logs in each broker.
--
+
The disk capacity used by an existing Kafka cluster can be increased if supported by the infrastructure.

Listeners:: Listeners configure how clients connect to a Kafka cluster.
+
By specifying a unique name and port for each listener within a Kafka cluster,
you can configure multiple listeners.
+
The following types of listener are supported:
+
--
* *Internal listeners* for access within Kubernetes
* *External listeners* for access outside of Kubernetes
--
+
You can enable TLS encryption for listeners, and configure xref:security-configuration-authentication_{context}[authentication].
+
Internal listeners expose Kafka by specifying an `internal` type:
+
--
* `internal` to connect within the same Kubernetes cluster
* `cluster-ip` to expose Kafka using per-broker `ClusterIP` services
--
+
External listeners expose Kafka by specifying an external `type`:
+
--
* `route` to use OpenShift routes and the default HAProxy router
* `loadbalancer` to use loadbalancer services
* `nodeport` to use ports on Kubernetes nodes
* `ingress` to use Kubernetes _Ingress_ and the {NginxIngressController}
--
+
NOTE: With the `cluster-ip` type can add your own access mechanism.
For example, you can use the listener with a custom Ingress controller or the Kubernetes Gateway API.

If you are using xref:security-configuration-authentication_{context}[OAuth 2.0 for token-based authentication], you can configure listeners to use the authorization server.

Rack awareness:: Racks represent data centers, or racks in data centers, or availability zones.
Configure rack awareness to distribute Kafka broker pods and topic replicas across racks.
Enable rack awareness using the `rack` property to specify a `topologyKey`.
The `topologyKey` is the name of the label assigned to Kubernetes worker nodes, which identifies the rack.  
Strimzi assigns a rack ID to each Kafka broker.
Kafka brokers use the IDs to spread partition replicas across racks.
You can also specify the `RackAwareReplicaSelector` selector plugin to use with rack awareness. 
The plugin matches the rack IDs of brokers and consumers, so that messages are consumed from the closest replica. 
To use the plugin, consumers must also have rack awareness enabled. 
You can enable rack awareness in Kafka Connect, MirrorMaker 2.0, and the Kafka Bridge.   

[discrete]
== Example YAML showing Kafka configuration
[source,shell,subs="+attributes"]
----
apiVersion: {KafkaApiVersion}
kind: Kafka
metadata:
  name: my-cluster
spec:
  kafka:
    # ...
    listeners:
      - name: tls
        port: 9093
        type: internal
        tls: true
        authentication:
          type: tls
      - name: external1
        port: 9094
        type: route
        tls: true
        authentication:
          type: tls
    # ...
    storage:
      type: persistent-claim
      size: 10000Gi
    # ...
    rack:
      topologyKey: topology.kubernetes.io/zone
    config:
      replica.selector.class: org.apache.kafka.common.replica.RackAwareReplicaSelector
    # ...
----
