// This module is included in the following assemblies:
//
// upgrading/assembly-upgrade-kafka.adoc

[id='con-upgrade-listeners-{context}']
= Updating listeners to the generic listener configuration

Strimzi provides a `GenericKafkaListener` schema for the configuration of Kafka listeners in a `Kafka` resource.

`GenericKafkaListener` replaces the `KafkaListeners` schema, which has been removed from Strimzi.

With the `GenericKafkaListener` schema, you can configure as many listeners as required,
as long as their names and ports are unique.
The `listeners` configuration is defined as an array, but the deprecated format is also supported.

For clients inside the Kubernetes cluster, you can create `plain` (without encryption) or `tls` _internal_ listeners.

For clients outside the Kubernetes cluster, you create _external_ listeners and specify a connection mechanism,
which can be `nodeport`, `loadbalancer`, `ingress` or `route`.

The `KafkaListeners` schema used sub-properties for `plain`, `tls` and `external` listeners, with fixed ports for each.
At any stage in the upgrade process, you must convert listeners configured using the `KafkaListeners` schema into the format of the `GenericKafkaListener` schema.

For example, if you are currently using the following configuration in your `Kafka` configuration:

.Old listener configuration
[source,shell,subs="+quotes,attributes"]
----
listeners:
  plain:
    # ...
  tls:
    # ...
  external:
    type: loadbalancer
    # ...
----

Convert the listeners into the new format using:

.New listener configuration
[source,shell,subs="+quotes,attributes"]
----
listeners:
  #...
  - name: plain
    port: 9092
    type: internal
    tls: false <1>
  - name: tls
    port: 9093
    type: internal
    tls: true
  - name: external
    port: 9094
    type: _EXTERNAL-LISTENER-TYPE_ <2>
    tls: true
----
<1> The TLS property is now required for all listeners.
<2> Options: `ingress`, `loadbalancer`, `nodeport`, `route`.

Make sure to use the *exact* names and port numbers shown.

For any additional `configuration` or `overrides` properties used with the old format, you need to update them to the new format.

Changes introduced to the listener `configuration`:

* `overrides` is merged with the `configuration` section
* `dnsAnnotations` has been renamed `annotations`
* `preferredAddressType` has been renamed `preferredNodePortAddressType`
* `address` has been renamed `alternativeNames`
* `loadBalancerSourceRanges` and `externalTrafficPolicy` move to the listener configuration from the now deprecated `template`

For example, this configuration:

.Old additional listener configuration
[source,shell,subs="+quotes,attributes"]
----
listeners:
  external:
    type: loadbalancer
    authentication:
      type: tls
    overrides:
      bootstrap:
        dnsAnnotations:
          #...
----

Changes to:

.New additional listener configuration
[source,shell,subs="+quotes,attributes"]
----
listeners:
    #...
  - name: external
    port: 9094
    type:loadbalancer
    tls: true
    authentication:
      type: tls
    configuration:
      bootstrap:
        annotations:
          #...
----

IMPORTANT: The name and port numbers shown in the new listener configuration *must* be used for backwards compatibility.
Using any other values will cause renaming of the Kafka listeners and Kubernetes services.

For more information on the configuration options available for each type of listener,
see the link:{BookURLUsing}#type-GenericKafkaListener-reference[`GenericKafkaListener` schema reference].
