:_mod-docs-content-type: REFERENCE

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

[id='ref-alternative-subjects-certs-for-listeners-{context}']

= Specifying SANs for custom listener certificates

[role="_abstract"]
In order to use TLS hostname verification with custom xref:proc-installing-certs-per-listener-{context}[Kafka listener certificates], you must specify the correct Subject Alternative Names (SANs) for each listener. 

The certificate SANs must specify hostnames for the following:

* All of the Kafka brokers in your cluster
* The Kafka cluster bootstrap service

You can use wildcard certificates if they are supported by your CA.

== Examples of SANs for internal listeners

Use the following examples to help you specify hostnames of the SANs in your certificates for your internal listeners.

Replace `<cluster-name>` with the name of the Kafka cluster and `<namespace>` with the Kubernetes namespace where the cluster is running.

.Wildcards example for a `type: internal` listener

[source,shell]
----
//Kafka brokers
*.<cluster_name>-kafka-brokers
*.<cluster_name>-kafka-brokers.<namespace>.svc

// Bootstrap service
<cluster_name>-kafka-bootstrap
<cluster_name>-kafka-bootstrap.<namespace>.svc
----

.Non-wildcards example for a `type: internal` listener

[source,shell]
----
// Kafka brokers
<cluster_name>-kafka-0.<cluster_name>-kafka-brokers
<cluster_name>-kafka-0.<cluster_name>-kafka-brokers.<namespace>.svc
<cluster_name>-kafka-1.<cluster_name>-kafka-brokers
<cluster_name>-kafka-1.<cluster_name>-kafka-brokers.<namespace>.svc
# ...

// Bootstrap service
<cluster_name>-kafka-bootstrap
<cluster_name>-kafka-bootstrap.<namespace>.svc
----

.Non-wildcards example for a `type: cluster-ip` listener

[source,shell]
----
// Kafka brokers
<cluster_name>-kafka-<listener-name>-0
<cluster_name>-kafka-<listener-name>-0.<namespace>.svc
<cluster_name>-kafka-_listener-name>-1
<cluster_name>-kafka-<listener-name>-1.<namespace>.svc
# ...

// Bootstrap service
<cluster_name>-kafka-<listener-name>-bootstrap
<cluster_name>-kafka-<listener-name>-bootstrap.<namespace>.svc
----

== Examples of SANs for external listeners

For external listeners which have TLS encryption enabled, the hostnames you need to specify in certificates depends on the external listener `type`.

.SANs for each type of external listener
[cols="2*",options="header",stripes="none",separator=¦]
|===

¦External listener type
¦In the SANs, specify...

m¦`ingress`
¦Addresses of all Kafka broker `Ingress` resources and the address of the bootstrap `Ingress`.

You can use a matching wildcard name.

m¦`route`
¦Addresses of all Kafka broker `Routes` and the address of the bootstrap `Route`.

You can use a matching wildcard name.

m¦`loadbalancer`
¦Addresses of all Kafka broker `loadbalancers` and the bootstrap `loadbalancer` address.

You can use a matching wildcard name.

m¦`nodeport`
¦Addresses of all Kubernetes worker nodes that the Kafka broker pods might be scheduled to.

You can use a matching wildcard name.

|===
