Configure Listeners in Kubernetes
You can fine-tune client interactions with Redpanda by customizing internal and external listener configurations.
Anatomy of a listener
Listeners are gateways for client communications in Redpanda. Redpanda uses TCP sockets for client connections, where each TCP socket consists of:
-
IP address or DNS name: The unique network identifier of the Redpanda server. This can be a local address or a public address for cloud-based services.
-
Port: A specific entry point for network traffic. Redpanda listens on designated ports for client connections.
Clients must specify both the IP address or DNS name and port for a successful connection, such as 203.0.113.5:9093.
The Redpanda Helm chart defines two listeners by default:
| Listener | Description |
|---|---|
|
Internal connections. These endpoints use internal addresses assigned to brokers by Kubernetes through the headless ClusterIP Service. |
|
External connections. These endpoints are accessible through addresses configured in the |
Prefer external.domain for clusters that you expect to scale. Because external.addresses is a static list, extending it to add a broker forces a rolling restart of every existing broker. See Scale without restarting brokers.
|
For example, these are the default settings for the internal Kafka API listener:
listeners:
kafka:
port: 9093
authenticationMethod:
tls:
enabled: true
cert: default
requireClientAuth: false
-
listeners.kafka.port: The container port for internal client connections. -
listeners.kafka.authenticationMethod: The authentication method to use when the top-levelauth.sasl.enabledsetting istrue. Default issasl. -
listeners.kafka.tls.enabled: Whether TLS is enabled for this listener when the top-leveltls.enabledsetting istruefor all listeners. -
listeners.kafka.tls.cert: The TLS certificates that this listener should use to secure client connections. TLS certificates are defined intls.certs. -
listeners.kafka.tls.requireClientAuth: Whether mTLS is enabled.
These are the settings for the external Kafka API listener:
listeners:
kafka:
external:
default:
enabled: true
port: 9094
# -- If undefined, `listeners.kafka.external.default.port` is used.
advertisedPorts:
- 31092
tls:
enabled: true
cert: external
# default is "sasl"
authenticationMethod:
-
listeners.kafka.external.default.port: The container port for external client connections. -
listeners.kafka.external.default.advertisedPorts: The node port that is routed tolisteners.kafka.external.default.port. This port is opened in Kubernetes Services whenexternal.service.enabledistrue. -
listeners.kafka.external.default.authenticationMethod: The authentication method to use when the top-levelauth.sasl.enabledsetting istrue. Default issasl. -
listeners.kafka.external.default.tls.enabled: Whether TLS is enabled for this listener when the top-leveltls.enabledsetting istruefor all listeners. -
listeners.kafka.external.default.tls.cert: The TLS certificates that this listener should use to secure client connections. TLS certificates are defined intls.certs.
Schema Registry and HTTP Proxy connect to Redpanda over the Kafka API. If you configure a TLS listener for the Kafka API, you must configure listeners.schemaRegistry.tls and listeners.http.tls. All APIs, except the internal RPC port, support multiple listeners.
Choose a listener configuration
Listener settings fall into four groups: how clients reach the brokers, what address and port the brokers advertise, how each listener is secured, and which listeners are enabled. Find your goal in the tables below.
All settings are Helm values. With the Redpanda Operator, set the same keys under spec.clusterSpec in the Redpanda resource.
Exposure: how clients reach the brokers
| Goal | Settings | Where |
|---|---|---|
Expose brokers through a node port on each worker node (default) |
|
|
Give each broker its own cloud load balancer |
|
|
Route all brokers through one Gateway address by TLS SNI |
|
|
Bring your own Services or an external proxy |
|
Addresses: what brokers advertise
| Goal | Settings | Where |
|---|---|---|
Advertise your own domain, with hostnames derived from Pod names |
|
|
Advertise an explicit hostname or IP address per broker |
|
|
Add brokers without restarting the existing ones |
|
|
Advertise a different hostname on each external listener, such as one listener per network or proxy |
|
|
Change the port that clients connect to |
|
Security: TLS and authentication per listener
| Goal | Settings | Where |
|---|---|---|
Use a different TLS certificate on some listeners |
|
|
Require client certificates (mTLS) |
|
|
Use a different authentication method on an external listener |
|
Listeners: which endpoints exist
| Goal | Settings | Where |
|---|---|---|
Offer more than one external listener, each with its own port, certificate, and authentication |
Additional entries under |
Advertise a different address for each external listener for a worked example |
Turn external access off for all listeners |
|
|
Turn external access off for one listener |
|
Scale without restarting brokers
Because the value of external.addresses is part of the checksum that determines whether Pods must restart, editing the list to add a broker rolls every existing broker. If you can’t use external.domain alone, choose one of the following patterns to keep the list unchanged when you scale.
Advertise a pattern instead of a list
If your addresses differ only by something each broker can work out for itself, such as its position in the cluster, set external.prefixTemplate to an expression and give external.addresses the single entry $PREFIX_TEMPLATE. Each broker evaluates the expression when it starts, so one entry serves every broker and the list never changes when you scale.
external.prefixTemplate is a shell expression, not a Helm template. It’s evaluated in the broker’s init container, where the following variables are available:
| Variable | Description |
|---|---|
|
The broker’s StatefulSet ordinal, such as |
|
The broker’s Pod name, such as |
|
The name of the worker node running the broker. |
|
The IP address of the worker node running the broker. |
Command substitution works too, so you can derive a prefix rather than name it.
Replace <custom-hostname> with your hostname and <custom-domain> with your domain.
-
Operator
-
Helm
redpanda-cluster.yamlapiVersion: cluster.redpanda.com/v1alpha2
kind: Redpanda
metadata:
name: redpanda
spec:
chartRef: {}
clusterSpec:
external:
enabled: true
type: NodePort
domain: <custom-domain>
prefixTemplate: <custom-hostname>-$POD_ORDINAL
addresses:
- $PREFIX_TEMPLATE
kubectl apply -f redpanda-cluster.yaml --namespace <namespace>
prefix-template.yamlexternal:
enabled: true
type: NodePort
domain: <custom-domain>
prefixTemplate: <custom-hostname>-$POD_ORDINAL
addresses:
- $PREFIX_TEMPLATE
helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
--values prefix-template.yaml --reuse-values --wait
Each broker advertises <custom-hostname>-<pod-ordinal>.<custom-domain>. Setting external.domain also adds <custom-domain> and *.<custom-domain> to the SAN list of the chart’s TLS certificates, so this pattern works with TLS enabled.
Unlike setting fullnameOverride, this pattern doesn’t rename your Pods or Services. Use it when the hostname you advertise must differ from the name of the underlying Kubernetes resources.
|
The prefix is evaluated when a broker starts, not when the chart is rendered, so
|
Reserve addresses for brokers you haven’t added yet
If your addresses don’t follow a pattern, list an address for every broker you expect to run, not just the brokers running now. Entries beyond the current replica count are ignored, so scaling up to any broker you’ve already listed adds only the new broker and leaves the rest untouched.
statefulset:
replicas: 3
external:
enabled: true
type: NodePort
addresses:
- <hostname-for-broker-0>
- <hostname-for-broker-1>
- <hostname-for-broker-2>
# Reserved for future brokers
- <hostname-for-broker-3>
- <hostname-for-broker-4>
- <hostname-for-broker-5>
Create the DNS records for the reserved addresses when you scale, not in advance.
Never set statefulset.replicas higher than the number of entries in external.addresses. The chart fails to render with an index out of range error.
|
Both patterns require you to know each broker’s address before the broker exists. If your addresses are assigned dynamically, such as the IP addresses of LoadBalancer Services that you don’t reserve in advance, reserve them up front if your platform supports it. Otherwise, scaling the cluster restarts every broker.
Advertise a different address for each external listener
A single external listener advertises the same hostname to every client. Some environments need more than one external Kafka API listener, each advertising its own hostnames and secured with its own certificate. For example:
-
A production listener and a management listener on separate networks, each behind its own SNI proxy or TCP ingress, each terminating TLS with a certificate from a different authority.
-
Two client populations that must not be able to reach each other’s endpoint, enforced by a firewall or proxy in front of each listener.
The Redpanda Helm chart and the Redpanda Operator support multiple external listeners under listeners.kafka.external.<listener-name>. Each listener has its own container port, advertised ports, TLS certificate, and authentication method. Advertised hostnames, however, come from the global external.addresses list, which is shared by all listeners.
To give each listener its own hostnames, combine the global $PREFIX_TEMPLATE placeholder with a prefixTemplate on each listener:
-
Set
external.addressesto the single entry$PREFIX_TEMPLATE. -
Set
prefixTemplateon every external listener to the hostname that listener should advertise. Use$POD_ORDINALso that each broker advertises its own hostname. The same variables asexternal.prefixTemplateare available. -
Set
external.prefixTemplateas the fallback for external listeners that you don’t set individually, such as the external HTTP Proxy listener that the chart enables by default. A listener with noprefixTemplateand no fallback advertises an empty address. -
Leave
external.domainunset. If you set it, the chart appends it to every advertised address.
Each broker evaluates the templates when it starts, so adding a broker doesn’t change the configuration of the existing brokers and doesn’t restart them.
This example advertises redpanda-broker-<pod-ordinal>.prod.example.com:443 on the default listener and redpanda-broker-<pod-ordinal>.mngmt.example.com:443 on the mngmt listener. The brokers listen on ports 9094 and 9095, and the proxies in front of them accept connections on port 443. Because an external proxy routes the traffic, the example disables the chart’s NodePort Service. The external HTTP Proxy listener uses the fallback external.prefixTemplate, so it advertises the production hostnames. To route it through a different proxy, give listeners.http.external.default its own prefixTemplate.
-
Operator
-
Helm
redpanda-cluster.yamlapiVersion: cluster.redpanda.com/v1alpha2
kind: Redpanda
metadata:
name: redpanda
spec:
chartRef: {}
clusterSpec:
external:
enabled: true
service:
enabled: false
prefixTemplate: "redpanda-broker-$POD_ORDINAL.prod.example.com"
addresses:
- "$PREFIX_TEMPLATE"
listeners:
kafka:
external:
default:
port: 9094
advertisedPorts:
- 443
prefixTemplate: "redpanda-broker-$POD_ORDINAL.prod.example.com"
tls:
enabled: true
cert: external-prod
requireClientAuth: true
mngmt:
port: 9095
advertisedPorts:
- 443
prefixTemplate: "redpanda-broker-$POD_ORDINAL.mngmt.example.com"
tls:
enabled: true
cert: external-mngmt
requireClientAuth: true
tls:
certs:
external-prod:
caEnabled: true
secretRef:
name: redpanda-external-prod-cert
external-mngmt:
caEnabled: true
secretRef:
name: redpanda-external-mngmt-cert
kubectl apply -f redpanda-cluster.yaml --namespace <namespace>
per-listener-addresses.yamlexternal:
enabled: true
service:
enabled: false
prefixTemplate: "redpanda-broker-$POD_ORDINAL.prod.example.com"
addresses:
- "$PREFIX_TEMPLATE"
listeners:
kafka:
external:
default:
port: 9094
advertisedPorts:
- 443
prefixTemplate: "redpanda-broker-$POD_ORDINAL.prod.example.com"
tls:
enabled: true
cert: external-prod
requireClientAuth: true
mngmt:
port: 9095
advertisedPorts:
- 443
prefixTemplate: "redpanda-broker-$POD_ORDINAL.mngmt.example.com"
tls:
enabled: true
cert: external-mngmt
requireClientAuth: true
tls:
certs:
external-prod:
caEnabled: true
secretRef:
name: redpanda-external-prod-cert
external-mngmt:
caEnabled: true
secretRef:
name: redpanda-external-mngmt-cert
helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
--values per-listener-addresses.yaml --reuse-values --wait
Broker redpanda-2 then advertises the following, which clients see in metadata responses:
advertised_kafka_api:
- name: internal
address: redpanda-2.redpanda.<namespace>.svc.cluster.local.
port: 9093
- name: default
address: redpanda-broker-2.prod.example.com
port: 443
- name: mngmt
address: redpanda-broker-2.mngmt.example.com
port: 443
|
Customize the advertised ports
Each external listener has two ports: port, the container port the broker listens on, and advertisedPorts, the port that brokers tell clients to connect to. What advertisedPorts has to match depends on how you expose the cluster:
-
NodePort Service: the node port that the chart opens for the listener. This is the default, so
advertisedPortsare often called node ports. -
LoadBalancer Service: the port the load balancer listens on.
-
Custom Services or an external proxy: the port that your Service or proxy accepts connections on, such as
443for an SNI proxy. See Use a Custom Service for External Access. -
Gateway API: not used. Brokers advertise
external.gateway.advertisedPortinstead. See Configure External Access through Gateway API.
advertisedPorts takes a list. With one entry, every broker advertises that port. With one entry per broker, broker N advertises entry N, which lets each broker use a different port behind a single address. The chart’s NodePort Service opens only the first entry, so a per-broker list requires custom Services or an external proxy.
To customize the advertised port for a listener, replace <port> with the port that you want to use.
|
Redpanda doesn’t validate the configured port numbers. Make sure to verify the following:
|
For the default ports, see the Redpanda Helm Chart Specification
For example, to customize the advertised port for the external Kafka API listener:
custom-kafka-port.yamllisteners:
kafka:
external:
default:
advertisedPorts:
- <port>
Configure TLS certificates
A Redpanda cluster provides granular control over the TLS certificates used by different listeners. This level of flexibility enables you to ensure the required level of security for each listener. For example, you can use a self-signed certificate for the internal RPC listener, while using a public certificate authority (CA) certificate for other listeners such as the Kafka API.
| All listeners must use the same certificate if mTLS is enabled. Redpanda on Kubernetes does not support configuring different TLS certificates for mTLS-enabled listeners, or mixed configurations where some listeners use mTLS and others do not. |
-
Internal listeners: By default, all internal listeners use the self-signed certificate defined globally in the
tls.certs.defaultconfiguration. To customize the certificates for each internal listener, you can edit thelisteners.<listener-name>.tls.certsetting. -
External listeners: By default, all external listeners use the self-signed certificate defined globally in the
tls.certs.externalconfiguration. To customize the certificates for each external listener, you can edit thelisteners.<listener-name>.external.default.tls.certsetting.
Here’s an example that configures two certificates:
-
public-ca-cert: This certificate is configured with an Issuer managed by cert-manager. -
private-ca-cert. This certificate is configured with an Opaque Secret containing thetls.crt,tls.key, andca.crtfiles.
The external Admin API listener is configured with the public-ca-cert certificate. The internal Kafka API listener is configured with the private-ca-cert certificate, and the other listeners are configured with the default self-signed certificate.
multiple-certs-tls.yamltls:
enabled: true
certs:
public-ca-cert:
issuerRef:
name: <issuer-name>
kind: Issuer
caEnabled: false
private-ca-cert:
secretRef:
name: <secret-name>
caEnabled: true
default:
caEnabled: true
listeners:
admin:
external:
default:
tls:
cert: public-ca-cert
kafka:
tls:
cert: private-ca-cert
http:
tls:
cert: default
rpc:
tls:
cert: default
schemaRegistry:
tls:
cert: default
Disable external access
You can disable external access for all listeners or for individual listeners.
To disable external access for all listeners:
disable-external-access.yamlexternal:
enabled: false
To disable external access for a specific listener, set listeners.<listener-name>.external.default to false. For example, to disable external access to the Kafka API listener:
disable-external-kafka-api.yamllisteners:
kafka:
external:
default:
enabled: false