// This module is included in:
//
// assembly-deploy-client-access.adoc

[id="configuration-points-listeners-{context}"]
= Configuring listeners to connect to Kafka

[role="_abstract"]
Use listeners to enable client connections to Kafka.
Strimzi provides a generic `GenericKafkaListener` schema with properties to configure listeners through the `Kafka` resource.

When configuring a Kafka cluster, you specify a listener `type` based on your requirements, environment, and infrastructure. 
Services, routes, load balancers, and ingresses for clients to connect to a cluster are created according to the listener type.

Internal and external listener types are supported.

Internal listeners:: Use internal listener types to connect clients within a kubernetes cluster.
+
* `internal` to connect within the same Kubernetes cluster
* `cluster-ip` to expose Kafka using per-broker `ClusterIP` services
+
Internal listeners use a headless service and the DNS names assigned to the broker pods. 
By default, they do not use the Kubernetes service DNS domain (typically `.cluster.local`). 
However, you can customize this configuration using the `useServiceDnsDomain` property. 
Consider using a `cluster-ip` type listener if routing through the headless service isn't feasible or if you require a custom access mechanism, such as when integrating with specific Ingress controllers or the Kubernetes Gateway API.

External listeners:: Use external listener types to connect clients outside a Kubernetes cluster.
+
* `nodeport` to use ports on Kubernetes nodes
* `loadbalancer` to use loadbalancer services
* `ingress` to use Kubernetes `Ingress` and the {NginxIngressController} (Kubernetes only)
* `route` to use OpenShift `Route` and the default HAProxy router (OpenShift only)
+
External listeners handle access to a Kafka cluster from networks that require different authentication mechanisms.
For example, loadbalancers might not be suitable for certain infrastructure, such as bare metal, where node ports provide a better option.

IMPORTANT: Do not use the built-in `ingress` controller on OpenShift, use the `route` type instead. The Ingress NGINX Controller is only intended for use on Kubernetes. The `route` type is only supported on OpenShift.

Each listener is defined as an array in the `Kafka` resource.

.Example listener configuration
[source,yaml,subs="+attributes"]
----
apiVersion: {KafkaApiVersion}
kind: Kafka
metadata:
  name: my-cluster
spec:
  kafka:
    # ...
    listeners:
      - name: plain
        port: 9092
        type: internal
        tls: false
        configuration:
          useServiceDnsDomain: true
      - name: tls
        port: 9093
        type: internal
        tls: true
        authentication:
          type: tls
      - name: external1
        port: 9094
        type: route
        tls: true
        configuration:
          brokerCertChainAndKey:
            secretName: my-secret
            certificate: my-certificate.crt
            key: my-key.key
    # ...
----

You can configure as many listeners as required, as long as their names and ports are unique.
You can also configure listeners for secure connection using authentication.

NOTE: If you scale your Kafka cluster while using external listeners, it might trigger a rolling update of all Kafka brokers. This depends on the configuration.

[role="_additional-resources"]
.Additional resources

* link:{BookURLConfiguring}#type-GenericKafkaListener-reference[`GenericKafkaListener` schema reference]