|
4 | 4 | :page-aliases: cluster-administration:listener-configuration.adoc |
5 | 5 | :page-categories: Management, Security |
6 | 6 |
|
| 7 | +Apache Kafka® client libraries must be able to connect to every Redpanda broker instance. If the client and broker are on different subnets, advertise the location of the broker in the Redpanda configuration file so other brokers in the cluster can be found. If not, clients connecting to brokers outside their local network experience connectivity issues. |
7 | 8 |
|
8 | | -Apache Kafka® client libraries must be able to connect to every Redpanda broker |
9 | | -instance. If the client and broker are on different subnets, advertise the location of the broker in the Redpanda configuration file so other brokers in |
10 | | -the cluster can be found. If not, clients connecting to brokers outside |
11 | | -their local network experience connectivity issues. |
12 | | - |
13 | | -To try out Redpanda, see the |
14 | | -xref:get-started:quick-start.adoc[Redpanda Quickstart]. |
| 9 | +To try out Redpanda, see the xref:get-started:quick-start.adoc[Redpanda quickstart]. |
15 | 10 |
|
16 | 11 | == Anatomy of a listener |
17 | 12 |
|
18 | | -Clients must connect to Redpanda with a TCP socket. A TCP socket is described by an IP address of an interface and a port on the machine that Redpanda runs on. For example: |
| 13 | +Clients connect to Redpanda over TCP. A listener is defined by an interface address and port on the machine running Redpanda. For example: |
| 14 | + |
| 15 | +[cols="1,1"] |
| 16 | +|=== |
| 17 | +|Configuration | Description |
| 18 | + |
| 19 | +|`address: 0.0.0.0` |
| 20 | +|Listens on all available interfaces. |
| 21 | + |
| 22 | +|`port: 9092` |
| 23 | +|TCP port for Kafka clients. |
| 24 | + |
| 25 | +|=== |
19 | 26 |
|
20 | | -[,yaml] |
| 27 | +[source,yaml] |
21 | 28 | ---- |
22 | 29 | redpanda: |
23 | 30 | kafka_api: |
24 | 31 | - address: 0.0.0.0 |
25 | 32 | port: 9092 |
26 | 33 | ---- |
27 | 34 |
|
28 | | -An address of `0.0.0.0` means that Redpanda listens on all interfaces. |
29 | | - |
30 | 35 | == Advertise a listener |
31 | 36 |
|
32 | | -By default, the advertised address is the address the listener is bound to, but this is not usually an externally-routable address. Set the advertised address to an address the client can use to connect to the instance of Redpanda. |
33 | | - |
34 | | -NOTE: Ensure that any configuration option with the `advertise_*` prefix uses a valid hostname or IP address. Do not use `0.0.0.0`. Invalid configurations, including the use of `0.0.0.0`, will cause the broker to fail during startup validation. |
| 37 | +By default, the advertised address is the same as the bound address. For clients outside the local host or subnet, you must set an externally reachable address or hostname. Invalid settings—including `0.0.0.0`—will fail startup validation. |
35 | 38 |
|
36 | | -If the client exists on another subnet, then it needs to know how to reach Redpanda. Do this by configuring the advertised address of the Kafka API in `redpanda.yaml`. For example, if Redpanda is running on the subnet `192.168.4.0/24` with IP address `192.168.4.1`, and the clients are running on the subnet `192.168.5.0/24`, then the client machine needs a gateway configured to route requests to `192.168.4.1`: |
37 | | - |
38 | | -[,yaml] |
| 39 | +[source,yaml] |
39 | 40 | ---- |
40 | 41 | redpanda: |
41 | 42 | advertised_kafka_api: |
42 | | - - address: 192.168.4.1 |
| 43 | + - address: 192.168.4.1 # Broker’s routable IP or FQDN |
43 | 44 | port: 9092 |
44 | 45 | ---- |
45 | 46 |
|
46 | | -It's also possible to advertise a host name, provided the client can resolve the DNS and has a route to the host. |
| 47 | +[NOTE] |
| 48 | +==== |
| 49 | +* Use a valid hostname or IP. Do not use `0.0.0.0`. |
| 50 | +* When using a DNS hostname, ensure clients can resolve it and that it matches any TLS certificate SAN. |
| 51 | +==== |
47 | 52 |
|
48 | 53 | == Multiple listeners |
49 | 54 |
|
50 | | -Sometimes it's useful to have multiple configurations for accessing Redpanda with multiple routes. |
51 | | - |
52 | | -Do this by creating multiple listeners, and providing a name for the listener. The name is used to connect the listener and its advertised address. For example: |
| 55 | +You can define multiple Kafka API listeners to support different interfaces, ports, or authentication methods. Each listener must have a unique `name` property, and the same `name` property must be used in the corresponding `advertised_kafka_api` stanza. |
53 | 56 |
|
54 | | -[,yaml] |
| 57 | +[source,yaml] |
55 | 58 | ---- |
56 | 59 | redpanda: |
57 | 60 | kafka_api: |
58 | | - - name: local |
| 61 | + - name: local # Unique listener name |
59 | 62 | address: 127.0.0.1 |
60 | 63 | port: 9092 |
| 64 | +
|
61 | 65 | - name: subnet |
62 | 66 | address: 192.168.4.1 |
63 | 67 | port: 9093 |
| 68 | +
|
64 | 69 | advertised_kafka_api: |
65 | | - - name: local |
| 70 | + - name: local # Must match the listener name |
66 | 71 | address: 127.0.0.1 |
67 | 72 | port: 9092 |
| 73 | +
|
68 | 74 | - name: subnet |
69 | 75 | address: 192.168.4.1 |
70 | 76 | port: 9093 |
71 | 77 | ---- |
72 | 78 |
|
73 | | -You can also create additional listeners for different configurations of TLS or authentication. |
| 79 | +== TLS listeners and DNS hostnames |
| 80 | + |
| 81 | +For encrypted connections, you typically advertise a DNS name matching your TLS certificate. Always include a `name` property for the TLS listener and use it in both `kafka_api` and `advertised_kafka_api`. |
| 82 | + |
| 83 | +[source,yaml] |
| 84 | +---- |
| 85 | +redpanda: |
| 86 | + kafka_api: |
| 87 | + - name: tls_listener |
| 88 | + address: 0.0.0.0 |
| 89 | + port: 9094 |
| 90 | + authentication_method: mtls_identity |
| 91 | +
|
| 92 | + advertised_kafka_api: |
| 93 | + - name: tls_listener |
| 94 | + address: https://kafka.example.com |
| 95 | + port: 9094 |
| 96 | +
|
| 97 | + kafka_api_tls: |
| 98 | + - name: tls_listener |
| 99 | + enabled: true |
| 100 | + key_file: /etc/redpanda/tls/broker.key |
| 101 | + cert_file: /etc/redpanda/tls/broker.crt |
| 102 | + truststore_file: /etc/redpanda/tls/ca.crt |
| 103 | + require_client_auth: true |
| 104 | +---- |
| 105 | + |
| 106 | +Ensure `kafka.example.com` matches the SAN in `broker.crt` and that clients trust the `ca.crt`. |
74 | 107 |
|
75 | 108 | == Mixed-mode authentication with multiple listeners |
76 | 109 |
|
77 | | -Redpanda supports using both SASL and mTLS principal extraction authentication methods using multiple listeners. This supports a variety of Kafka clients using various authentication schemes all connecting to your cluster. For example: |
| 110 | +Redpanda supports running multiple authentication schemes side by side. Each listener can specify its method, and must define a `name:`. |
78 | 111 |
|
79 | | -[,yaml] |
| 112 | +[source,yaml] |
80 | 113 | ---- |
81 | 114 | redpanda: |
82 | 115 | kafka_api: |
83 | | - - address: 0.0.0.0 |
| 116 | + - name: sasl_listener |
| 117 | + address: 0.0.0.0 |
84 | 118 | port: 9092 |
85 | | - name: sasl_listener |
86 | 119 | authentication_method: sasl |
87 | | - - address: 0.0.0.0 |
| 120 | +
|
| 121 | + - name: mtls_listener |
| 122 | + address: 0.0.0.0 |
88 | 123 | port: 9192 |
89 | | - name: mtls_listener |
90 | 124 | authentication_method: mtls_identity |
| 125 | +
|
91 | 126 | kafka_api_tls: |
92 | 127 | - name: mtls_listener |
93 | 128 | key_file: mtls_broker.key |
94 | 129 | cert_file: mtls_broker.crt |
95 | 130 | truststore_file: mtls_ca.crt |
96 | | - enabled: true |
97 | 131 | require_client_auth: true |
98 | 132 | ---- |
99 | 133 |
|
100 | 134 | == Listeners that can be advertised |
101 | 135 |
|
102 | | -* `kafka_api` \-> `advertised_kafka_api`: The address that Kafka clients connect to, for each listener. |
103 | | -* `rpc_server` \-> `advertised_rpc_api`: The address that other Redpanda instances connect to. |
104 | | -* `pandaproxy_api` \-> `advertised_pandaproxy_api`: The address that HTTP clients connect to, for each listener. |
| 136 | +* `kafka_api` → `advertised_kafka_api`: Kafka clients connect here. |
| 137 | +* `rpc_server` → `advertised_rpc_api`: Other Redpanda brokers connect here. |
| 138 | +* `pandaproxy_api` → `advertised_pandaproxy_api`: HTTP clients connect here. |
| 139 | + |
| 140 | +For each advertised block, match the `name:` of the corresponding listener and provide a valid address and port. |
| 141 | + |
0 commit comments