What is the difference between listeners and advertised.listeners, and why does a misconfigured advertised.listeners break clients even when the broker starts fine?

Kafka's connection model has **two phases**, and the two listener configs serve those two phases. **Phase 1 — Bootstrap.** A client is configured with `bootstrap.servers`, a seed list of broker addresses. It connects to one of them just to fetch **cluster metadata**: which brokers exist, which broker leads each topic-partition, and crucially *what address to use to reach each broker*. **Phase 2 — Real traffic.** Using that metadata, the client opens **new connections directly to the leader broker** for each partition it produces to or consumes from. It does NOT keep using the bootstrap address; it uses whatever address the metadata told it. Now the two configs: - **`listeners`** — the set of endpoints the broker process actually **binds a socket to** and accepts connections on. Format: `name://host:port`, e.g. `PLAINTEXT://0.0.0.0:9092`. Binding to `0.0.0.0` means 'all local interfaces' and is fine *for binding*. - **`advertised.listeners`** — the endpoints the broker **reports in metadata** so clients know how to reach it in Phase 2. This MUST be an address that clients can actually resolve and route to. You must NOT advertise `0.0.0.0` (clients would try to connect to 0.0.0.0). If unset, it defaults to the value of `listeners` (which is why advertising 0.0.0.0 accidentally happens). **Why a broker can start fine yet clients fail:** Broker startup only validates that it can bind `listeners`. It never checks whether `advertised.listeners` is reachable from clients. So a broker advertising `kafka-internal:9092` (a Docker-internal hostname) starts perfectly. A client outside Docker bootstraps via `localhost:9092`, succeeds, receives metadata saying 'reach me at kafka-internal:9092', tries to open a Phase-2 connection, and fails to resolve or route there. Symptoms: bootstrap works, then produce/consume times out or throws connection-refused/unknown-host. **The standard solution (multi-listener):** Define separate listeners for separate networks, each advertised correctly: ``` listeners=INTERNAL://0.0.0.0:9092,EXTERNAL://0.0.0.0:9094 advertised.listeners=INTERNAL://kafka:9092,EXTERNAL://broker.example.com:9094 listener.security.protocol.map=INTERNAL:SSL,EXTERNAL:SASL_SSL inter.broker.listener.name=INTERNAL ``` Internal clients/brokers use the INTERNAL address; external clients get the routable EXTERNAL hostname. Each listener can also carry a different security protocol, hardening the externally-exposed path. **Edge cases:** In Kubernetes with NodePort/LoadBalancer per broker, you typically need per-broker advertised addresses (often templated). With NAT, the advertised address must be the public/NATed address, not the broker's private IP. Port and host in advertised.listeners can differ from the bind port (useful behind a proxy/load balancer doing port mapping).