Configures Kafka listeners.

[id='property-listener-config-brokerCertChainAndKey-{context}']
= Providing your own listener certificates

The `brokerCertChainAndKey` property is for listeners that have TLS encryption enabled only. 
Use this property to provide your own Kafka listener certificates.

.Example `loadbalancer` listener configuration to provide certificates
[source,yaml,subs="attributes+"]
----
listeners:
  #...
  - name: external3
    port: 9094
    type: loadbalancer
    tls: true
    configuration:
      brokerCertChainAndKey:
        secretName: my-secret
        certificate: my-listener-certificate.crt
        key: my-listener-key.key
# ...
----

When the certificate or key in the `brokerCertChainAndKey` secret is updated, the operator automatically detects it in the next reconciliation and triggers a rolling update of the Kafka brokers to reload the certificate.

[id='property-listener-config-traffic-policy-{context}']
= Avoiding hops to other nodes

The `externalTrafficPolicy` property is used with `loadbalancer` and `nodeport` listeners.
When exposing Kafka outside of Kubernetes, you can choose `Local` or `Cluster`.
`Local` avoids hops to other nodes and preserves the client IP, whereas `Cluster` does neither.
The default is `Cluster`.

.Example `loadbalancer` listener configuration avoiding hops
[source,yaml,subs="attributes+"]
----
listeners:
  #...
  - name: external3
    port: 9094
    type: loadbalancer
    tls: true
    configuration:
      externalTrafficPolicy: Local   
# ...
----

[id='property-listener-config-source-ranges-{context}']
= Providing CIDR source ranges for a loadbalancer

The `loadBalancerSourceRanges` property is for `loadbalancer` listeners only. 
When exposing Kafka outside of Kubernetes, use CIDR (Classless Inter-Domain Routing) source ranges in addition to labels and annotations to customize how a service is created.

.Example `loadbalancer` listener configuration to provide source ranges
[source,yaml,subs="attributes+"]
----
listeners:
  #...
  - name: external3
    port: 9094
    type: loadbalancer
    tls: true
    configuration:
      loadBalancerSourceRanges:
        - 10.0.0.0/8
        - 88.208.76.87/32    
# ...
----

[id='property-listener-config-preferredNodePortAddressType-{context}']
= Specifying a preferred node port address type

The `preferredNodePortAddressType` property is for `nodeport` listeners only.
Use this property in your listener configuration to specify the first address type checked as the node address. 
This property is useful, for example, if your deployment does not have DNS support or you only want to expose a broker internally through an internal DNS or IP address. 

If an address of this type is found, it is used. If the preferred address type is not found, Strimzi proceeds through the types in the standard order of priority:

* ExternalDNS
* ExternalIP
* Hostname
* InternalDNS
* InternalIP

.Example `nodeport` listener using a preferred node port address type
[source,yaml,subs=attributes+]
----
listeners:
  #...
  - name: external4
    port: 9094
    type: nodeport
    tls: false
    configuration:
      preferredNodePortAddressType: InternalDNS
# ...
----

[id='property-listener-config-dns-{context}']
= Using fully-qualified DNS names

The `useServiceDnsDomain` property is for `internal` and `cluster-ip` listeners. 
It defines whether the fully-qualified DNS names that include the cluster service suffix (usually `.cluster.local`) are used. 

* Set to `false` (default) to generate advertised addresses without the service suffix; for example, `my-cluster-kafka-0.my-cluster-kafka-brokers.myproject.svc`. 
* Set to `true` to generate advertised addresses with the service suffix; for example, `my-cluster-kafka-0.my-cluster-kafka-brokers.myproject.svc.cluster.local`.

.Example `internal` listener using the service DNS domain
[source,yaml,subs=attributes+]
----
listeners:
  #...
  - name: plain
    port: 9092
    type: internal
    tls: false
    configuration:
      useServiceDnsDomain: true
# ...
----

[id='property-listener-config-host-{context}']
= Specifying the hostname

To specify the hostname used for the bootstrap resource or brokers, use the `host` property.
The `host` property is for `route` and `ingress` listeners only.

A `host` property value is mandatory for ingress listener configuration, as the Ingress controller does not assign any hostnames automatically. 
Make sure that the hostname resolves to the Ingress endpoints. 
Strimzi will not perform any validation to ensure that the requested hosts are available and properly routed to the Ingress endpoints.

.Example `ingress` listener with host configuration
[source,yaml,subs="attributes+"]
----
listeners:
  #...
  - name: external2
    port: 9094
    type: ingress
    tls: true
    configuration:
      bootstrap:
        host: bootstrap.myingress.com
      brokers:
      - broker: 0
        host: broker-0.myingress.com
      - broker: 1
        host: broker-1.myingress.com
      - broker: 2
        host: broker-2.myingress.com
# ...
----

By default, route listener hosts are automatically assigned by OpenShift. 
However, you can override the assigned route hosts by specifying hosts.

Strimzi does not perform any validation to ensure that the requested hosts are available. 
You must ensure that they are free and can be used.

.Example `route` listener with host configuration
[source,yaml,subs="attributes+"]
----
# ...
listeners:
  #...
  - name: external1
    port: 9094
    type: route
    tls: true
    configuration:
      bootstrap:
        host: bootstrap.myrouter.com
      brokers:
      - broker: 0
        host: broker-0.myrouter.com
      - broker: 1
        host: broker-1.myrouter.com
      - broker: 2
        host: broker-2.myrouter.com
# ...
----

Instead of specifying the `host` property for every broker, you can also use a `hostTemplate` to generate them automatically.
The `hostTemplate` supports the following variables:

* The `{nodeId}` variable is replaced with the ID of the Kafka node to which the template is applied.
* The `{nodePodName}` variable is replaced with the Kubernetes pod name for the Kafka node where the template is applied.

The `hostTemplate` property applies only to per-broker values.
The bootstrap `host` property must always be specified.

.Example `ingress` listener with `hostTemplate` configuration
[source,yaml,subs="+attributes"]
----
#...
spec:
  kafka:
    #...
    listeners:
      #...
      - name: external2
        port: 9095
        type: ingress
        tls: true
        authentication:
          type: tls
        configuration:
          hostTemplate: broker-{nodeId}.myingress.com
          bootstrap:
            host: bootstrap.myingress.com
  #...
----

[id='property-listener-config-nodeport-{context}']
= Overriding assigned node ports

By default, the port numbers used for the bootstrap and broker services are automatically assigned by Kubernetes.
You can override the assigned node ports for `nodeport` listeners by specifying the desired port numbers.

Strimzi does not perform any validation on the requested ports.
You must ensure that they are free and available for use.

.Example `nodeport` listener configuration with overrides for node ports
[source,yaml,subs="attributes+"]
----
# ...
listeners:
  #...
  - name: external4
    port: 9094
    type: nodeport
    tls: true
    configuration:
      bootstrap:
        nodePort: 32100
      brokers:
      - broker: 0
        nodePort: 32000
      - broker: 1
        nodePort: 32001
      - broker: 2
        nodePort: 32002
# ...
----

[id='property-listener-config-lb-ip-{context}']
= Requesting a specific loadbalancer IP address 

Use the `loadBalancerIP` property to request a specific IP address when creating a loadbalancer.
This property is useful when you need to use a loadbalancer with a specific IP address.
The `loadBalancerIP` property is ignored if the cloud provider does not support this feature.

.Example `loadbalancer` listener with specific IP addresses
[source,yaml,subs="attributes+"]
----
# ...
listeners:
  #...
  - name: external3
    port: 9094
    type: loadbalancer
    tls: true
    configuration:
      bootstrap:
        loadBalancerIP: 172.29.3.10
      brokers:
      - broker: 0
        loadBalancerIP: 172.29.3.1
      - broker: 1
        loadBalancerIP: 172.29.3.2
      - broker: 2
        loadBalancerIP: 172.29.3.3
# ...
----

[id='property-listener-config-annotations-{context}']
= Adding listener annotations to Kubernetes resources 

Use the `annotations` property to add annotations to Kubernetes resources related to the listeners.
These annotations can be used, for example, to instrument DNS tooling such as {KubernetesExternalDNS}, which automatically assigns DNS names to the loadbalancer services.

.Example `loadbalancer` listener using `annotations`
[source,yaml,subs="attributes+"]
----
# ...
listeners:
  #...
  - name: external3
    port: 9094
    type: loadbalancer
    tls: true
    configuration:
      bootstrap:
        annotations:
          external-dns.alpha.kubernetes.io/hostname: kafka-bootstrap.mydomain.com.
          external-dns.alpha.kubernetes.io/ttl: "60"
      brokers:
      - broker: 0
        annotations:
          external-dns.alpha.kubernetes.io/hostname: kafka-broker-0.mydomain.com.
          external-dns.alpha.kubernetes.io/ttl: "60"
      - broker: 1
        annotations:
          external-dns.alpha.kubernetes.io/hostname: kafka-broker-1.mydomain.com.
          external-dns.alpha.kubernetes.io/ttl: "60"
      - broker: 2
        annotations:
          external-dns.alpha.kubernetes.io/hostname: kafka-broker-2.mydomain.com.
          external-dns.alpha.kubernetes.io/ttl: "60"
# ...
----