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

[id='proc-installing-certs-per-listener-{context}']
= Providing your own Kafka listener certificates for TLS encryption

[role="_abstract"]
Listeners provide client access to Kafka brokers.
Configure listeners in the `Kafka` resource, including the configuration required for client access using TLS.

By default, the listeners use certificates signed by the internal CA (certificate authority) certificates generated by Strimzi.
A CA certificate is generated by the Cluster Operator when it creates a Kafka cluster.
When you configure a client for TLS, you add the CA certificate to its truststore configuration to verify the Kafka cluster.
You can also xref:installing-your-own-ca-certificates-str[install and use your own CA certificates]. 
Or you can configure a listener using `brokerCertChainAndKey` properties and use a custom server certificate.

The `brokerCertChainAndKey` properties allow you to access Kafka brokers using your own custom certificates at the listener-level.
You create a secret with your own private key and server certificate, then specify the key and certificate in the listener's `brokerCertChainAndKey` configuration.
You can use a certificate signed by a public (external) CA or a private CA.
If signed by a public CA, you usually won't need to add it to a client's truststore configuration.  
Custom certificates are not managed by Strimzi, so you need to renew them manually. 

NOTE: Listener certificates are used for TLS encryption and server authentication only.
They are not used for TLS client authentication.
If you want to use your own certificate for TLS client authentication as well, you must xref:installing-your-own-ca-certificates-str[install and use your own clients CA]. 

.Prerequisites

* The Cluster Operator is running.
* Each listener requires the following:
** A compatible server certificate signed by an external CA. (Provide an X.509 certificate in PEM format.)
+
You can use one listener certificate for multiple listeners.
** Subject Alternative Names (SANs) are specified in the certificate for each listener.
For more information, see xref:ref-alternative-subjects-certs-for-listeners-{context}[].

If you are not using a self-signed certificate, you can provide a certificate that includes the whole CA chain in the certificate.

You can only use the `brokerCertChainAndKey` properties if TLS encryption (`tls: true`) is configured for the listener.

NOTE: Strimzi does not support the use of encrypted private keys for TLS. The private key stored in the secret must be unencrypted for this to work.

.Procedure

. Create a `Secret` containing your private key and server certificate:
+
[source,shell,subs="+quotes"]
----
kubectl create secret generic _my-secret_ --from-file=_my-listener-key.key_ --from-file=_my-listener-certificate.crt_
----

. Edit the `Kafka` resource for your cluster. 
+
Configure the listener to use your `Secret`, certificate file, and private key file in the `configuration.brokerCertChainAndKey` property.
+
.Example configuration for a `loadbalancer` external listener with TLS encryption enabled
[source,yaml,subs="attributes+"]
----
# ...
listeners:
  - name: plain
    port: 9092
    type: internal
    tls: false
  - name: external3
    port: 9094
    type: loadbalancer
    tls: true
    configuration:
      brokerCertChainAndKey:
        secretName: my-secret
        certificate: my-listener-certificate.crt
        key: my-listener-key.key
# ...
----
+
.Example configuration for a TLS listener
[source,yaml,subs="attributes+"]
----
# ...
listeners:
  - name: plain
    port: 9092
    type: internal
    tls: false
  - name: tls
    port: 9093
    type: internal
    tls: true
    configuration:
      brokerCertChainAndKey:
        secretName: my-secret
        certificate: my-listener-certificate.crt
        key: my-listener-key.key
# ...
----

. Apply the new configuration to create or update the resource:
+
[source,shell,subs="+quotes"]
----
kubectl apply -f _kafka.yaml_
----
+
The Cluster Operator starts a rolling update of the Kafka cluster, which updates the configuration of the listeners.
+
NOTE: A rolling update is also started if you update a Kafka listener certificate in a `Secret` that is already used by a listener.
