// Module included in the following assemblies:
//
// assembly-configuring-kafka-listeners.adoc

[id='con-kafka-listeners-{context}']
= Kafka listeners

You can configure Kafka broker listeners using the `listeners` property in the `Kafka.spec.kafka` resource.
The `listeners` property contains three sub-properties:

* `plain`
* `tls`
* `external`

When none of these properties are defined, the listener will be disabled.

.An example of `listeners` property with all listeners enabled
[source,yaml,subs="attributes+"]
----
# ...
listeners:
  plain: {}
  tls: {}
# ...
----

.An example of `listeners` property with only the plain listener enabled
[source,yaml,subs="attributes+"]
----
# ...
listeners:
  plain: {}
# ...
----

== External listener

The external listener is used to connect to a Kafka cluster from outside of an {ProductPlatformName} environment.
{ProductName} supports three types of external listeners:

* `route`
* `loadbalancer`
* `nodeport`

.Exposing Kafka using {OpenShiftName} Routes

An external listener of type `route` exposes Kafka by using {OpenShiftName} `Routes` and the HAProxy router.
A dedicated `Route` is created for every Kafka broker pod.
An additional `Route` is created to serve as a Kafka bootstrap address.
Kafka clients can use these `Routes` to connect to Kafka on port 443.

ifdef::Kubernetes[]
NOTE: `Routes` are available only on {OpenShiftName}. External listeners of type `route` cannot be used on {KubernetesName}.
endif::Kubernetes[]

When exposing Kafka using {OpenShiftName} `Routes`, TLS encryption is always used.

For more information on using `Routes` to access Kafka, see xref:proc-accessing-kafka-using-routes-{context}[].

.Exposing Kafka using loadbalancers

External listeners of type `loadbalancer` expose Kafka by using `Loadbalancer` type `Services`.
A new loadbalancer service is created for every Kafka broker pod.
An additional loadbalancer is created to serve as a Kafka _bootstrap_ address.
Loadbalancers listen to connections on port 9094.

By default, TLS encryption is enabled.
To disable it, set the `tls` field to `false`.

For more information on using loadbalancers to access Kafka, see xref:proc-accessing-kafka-using-loadbalancers-{context}[].

.Exposing Kafka using node ports

External listeners of type `nodeport` expose Kafka by using `NodePort` type `Services`.
When exposing Kafka in this way, Kafka clients connect directly to the nodes of {ProductPlatformName}.
You must enable access to the ports on the {ProductPlatformName} nodes for each client (for example, in firewalls or security groups).
Each Kafka broker pod is then accessible on a separate port.
Additional `NodePort` type `Service` is created to serve as a Kafka bootstrap address.

When configuring the advertised addresses for the Kafka broker pods, {ProductName} uses the address of the node on which the given pod is running.
When selecting the node address, the different address types are used with the following priority:

. ExternalDNS
. ExternalIP
. Hostname
. InternalDNS
. InternalIP

By default, TLS encryption is enabled.
To disable it, set the `tls` field to `false`.

NOTE: TLS hostname verification is not currently supported when exposing Kafka clusters using node ports.

For more information on using node ports to access Kafka, see xref:proc-accessing-kafka-using-nodeports-{context}[].

== Listener authentication

The listener sub-properties can also contain additional configuration.
Both listeners support the `authentication` property. This is used to specify an authentication mechanism specific to that listener:

* mutual TLS authentication (only on the listeners with TLS encryption)
* SCRAM-SHA authentication

If no `authentication` property is specified then the listener does not authenticate clients which connect though that listener.

.An example where the plain listener is configured for SCRAM-SHA authentication and the `tls` listener with mutual TLS authentication
[source,yaml,subs="attributes+"]
----
# ...
listeners:
  plain:
    authentication:
      type: scram-sha-512
  tls:
    authentication:
      type: tls
  external:
    type: loadbalancer
    tls: true
    authentication:
      type: tls
# ...
----


Authentication must be configured when using the User Operator to manage `KafkaUsers`.