docs: document Pulsar listenerName metadata field#5236
Conversation
Documents the listenerName field added to the Pulsar pubsub component in dapr/components-contrib#4386, which exposes the pulsar-client-go ListenerName option for advertisedListeners / multi-listener broker topologies. Ships in Dapr 1.19. Signed-off-by: Nelson Parente <nelson_parente@live.com.pt>
There was a problem hiding this comment.
Pull request overview
This PR updates the Dapr docs for the Pulsar pub/sub component to document the newly added listenerName metadata field (shipping in Dapr 1.19), which maps to the Pulsar Go client’s ClientOptions.ListenerName and supports broker redirect resolution via named advertised listeners.
Changes:
- Adds the
listenerNamemetadata entry to the Pulsar component spec metadata table. - Includes a reference link to Pulsar’s “Multiple Advertised Listeners” documentation for additional context.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
alicejgibbons
left a comment
alicejgibbons
left a comment
There was a problem hiding this comment.
Is unclear based on https://pulsar.apache.org/docs/3.0.x/concepts-multiple-advertised-listeners/
| | Field | Required | Details | Example | | ||
| |--------------------|:--------:|---------|---------| | ||
| | host | Y | Address of the Pulsar broker. Default is `"localhost:6650"` | `"localhost:6650"` OR `"http://pulsar-pj54qwwdpz4b-pulsar.ap-sg.public.pulsar.com:8080"`| | ||
| | listenerName | N | Configures the listener name the Pulsar client sends to the broker for connection redirects. Brokers configured with `advertisedListeners` resolve the redirect target using the matching named listener, enabling cross-network topologies (multi-cluster, internal/external endpoints) without a Pulsar proxy. See [Pulsar Multiple Advertised Listeners](https://pulsar.apache.org/docs/3.0.x/concepts-multiple-advertised-listeners/). When unset, behavior is unchanged. | `"external"` | |
There was a problem hiding this comment.
@nelson-parente am confused here.
Is the feature we are exposing on Pulsar advertisedListeners or internalListenerName? Based on the docs you listed (https://pulsar.apache.org/docs/3.0.x/concepts-multiple-advertised-listeners/) there are different behaviours for both. Also are users specifying the <listener_name>:pulsar://<host>:<port>, <listener_name>:pulsar+ssl://<host>:<port> format? Unclear
We also need to specify all the possible values it can be (external, internal?, any others?) as well as say "Default is ..".
Address review feedback: distinguish the client-side listenerName (a single listener name matching one in the broker's advertisedListeners) from the broker-side advertisedListeners/internalListenerName config, note that internal/external are operator-chosen conventions rather than fixed values, and state the default. Signed-off-by: Nelson Parente <nelson_parente@live.com.pt>
Description
Documents the new
listenerNamemetadata field on the Pulsar pub/sub component, added in dapr/components-contrib#4386 (merged, ships in Dapr 1.19).The field exposes the
pulsar-client-goClientOptions.ListenerNameoption. When set, the value is sent to the broker so that brokers configured withadvertisedListenersresolve connection-redirect targets using the matching named listener — enabling cross-network / multi-cluster topologies (sidecars in a separate VPC or cluster from the broker) without a Pulsar proxy. When unset, behavior is unchanged.The wording and the reference link mirror the component's
metadata.yamlentry.Issue reference
Documents the feature from dapr/components-contrib#4386 (closes dapr/components-contrib#4383).
Checklist
listenerNamerow to the Pulsar spec metadata tablev1.19(the release the feature ships in)