This is an automated email from the ASF dual-hosted git repository.
penghui pushed a commit to branch branch-2.7
in repository https://gitbox.apache.org/repos/asf/pulsar.git
commit c00aac7838a17ac12c91a48989054ae6930085a2
Author: HuanliMeng <48...@users.noreply.github.com>
AuthorDate: Thu Dec 3 11:06:25 2020 +0800
[Doc]--Update doc for multiple advertised listeners (#8789)
Fixes #1736
### Motivation
Multiple advertised listener is introduced in Release 2.6.0 but the doc is not added or updated accordingly.
### Modifications
1: Releases 2.6.1 and 2.6.2
Update Reference > Pulsar configuration > Broker: add `advertisedListeners` and `internalListenerName` config options
**Note: because these 2 config options have been added in Release master and 2.6.0 by another TW.**
2: Release Master:
Concepts and Architecture: Add a new doc "Multiple advertised listeners".
sidebar: add the info of the new doc.
**Note: After the new doc is reviewed and approved, will add it to releases 2.6.0, 2.6.1 and 2.6.2.**
(cherry picked from commit 42b6d9844126803cfc14a9ff4733d91bffae1948)
---
.../docs/concepts-multiple-advertised-listeners.md | 38 ++++++++++++++++++++++
site2/website/sidebars.json | 3 +-
.../version-2.6.1/reference-configuration.md | 2 ++
.../version-2.6.2/reference-configuration.md | 2 ++
4 files changed, 44 insertions(+), 1 deletion(-)
diff --git a/site2/docs/concepts-multiple-advertised-listeners.md b/site2/docs/concepts-multiple-advertised-listeners.md
new file mode 100644
index 0000000..8ba0db9
--- /dev/null
+++ b/site2/docs/concepts-multiple-advertised-listeners.md
@@ -0,0 +1,38 @@
+---
+id: concepts-multiple-advertised-listeners
+title: Multiple advertised listeners
+sidebar_label: Multiple advertised listeners
+---
+
+When a Pulsar cluster is deployed in the production environment, it may require to expose multiple advertised addresses for the broker. For example, when you deploy a Pulsar cluster in Kubernetes and want other clients, which are not in the same Kubernetes cluster, to connect to the Pulsar cluster, you need to assign a broker URL to external clients. But clients in the same Kubernetes cluster can still connect to the Pulsar cluster through the internal network of Kubernetes.
+
+## Advertised listeners
+
+To ensure clients in both internal and external networks can connect to a Pulsar cluster, Pulsar introduces `advertisedListeners` and `internalListenerName` configuration options into the [broker configuration file](reference-configuration.md#broker) to ensure that the broker supports exposing multiple advertised listeners and support the separation of internal and external network traffic.
+
+- The `advertisedListeners` is used to specify multiple advertised listeners. The broker uses the listener as the broker identifier in the load manager and the bundle owner data. The `advertisedListeners` is formatted as `<listener_name>:pulsar://<host>:<port>, <listener_name>:pulsar+ssl://<host>:<port>`. You can set up the `advertisedListeners` like
+`advertisedListeners=internal:pulsar://192.168.1.11:6660,internal:pulsar+ssl://192.168.1.11:6651`.
+
+- The `internalListenerName` is used to specify the internal service URL that the broker uses. You can specify the `internalListenerName` by choosing one of the `advertisedListeners`. The broker uses the listener name of the first advertised listener as the `internalListenerName` if the `internalListenerName` is absent.
+
+After setting up the `advertisedListeners`, clients can choose one of the listeners as the service URL to create a connection to the broker as long as the network is accessible. However, if the client creates producers or consumer on a topic, the client must send a lookup requests to the broker for getting the owner broker, then connect to the owner broker to publish messages or consume messages. Therefore, You must allow the client to get the corresponding service URL with the same adve [...]
+
+## Use multiple advertised listeners
+
+This example shows how a Pulsar client uses multiple advertised listeners.
+
+1. Configure multiple advertised listeners in the broker configuration file.
+
+```shell
+advertisedListeners={listenerName}:pulsar://xxxx:6650,
+{listenerName}:pulsar+ssl://xxxx:6651
+```
+
+2. Specify the listener name for the client.
+
+```java
+PulsarClient client = PulsarClient.builder()
+ .serviceUrl("pulsar://xxxx:6650")
+ .listenerName("external")
+ .build();
+```
\ No newline at end of file
diff --git a/site2/website/sidebars.json b/site2/website/sidebars.json
index 0a446da..d75e4f5 100644
--- a/site2/website/sidebars.json
+++ b/site2/website/sidebars.json
@@ -16,7 +16,8 @@
"concepts-multi-tenancy",
"concepts-authentication",
"concepts-topic-compaction",
- "concepts-proxy-sni-routing"
+ "concepts-proxy-sni-routing",
+ "concepts-multiple-advertised-listeners"
],
"Pulsar Schema": [
"schema-get-started",
diff --git a/site2/website/versioned_docs/version-2.6.1/reference-configuration.md b/site2/website/versioned_docs/version-2.6.1/reference-configuration.md
index c0179c8..9ac5cfb 100644
--- a/site2/website/versioned_docs/version-2.6.1/reference-configuration.md
+++ b/site2/website/versioned_docs/version-2.6.1/reference-configuration.md
@@ -107,6 +107,8 @@ Pulsar brokers are responsible for handling incoming messages from producers, di
|Name|Description|Default|
|---|---|---|
+|advertisedListeners|Specify multiple advertised listeners for the broker.<br><br>The format is `<listener_name>:pulsar://<host>:<port>`.<br><br>If there are multiple listeners, separate them with commas.<br><br>**Note**: do not use this configuration with `advertisedAddress` and `brokerServicePort`. If the value of this configuration is empty, the broker uses `advertisedAddress` and `brokerServicePort`|/|
+|internalListenerName|Specify the internal listener name for the broker.<br><br>**Note**: the listener name must be contained in `advertisedListeners`.<br><br> If the value of this configuration is empty, the broker uses the first listener as the internal listener.|/|
|enablePersistentTopics| Whether persistent topics are enabled on the broker |true|
|enableNonPersistentTopics| Whether non-persistent topics are enabled on the broker |true|
|functionsWorkerEnabled| Whether the Pulsar Functions worker service is enabled in the broker |false|
diff --git a/site2/website/versioned_docs/version-2.6.2/reference-configuration.md b/site2/website/versioned_docs/version-2.6.2/reference-configuration.md
index 32ec853..c186a24 100644
--- a/site2/website/versioned_docs/version-2.6.2/reference-configuration.md
+++ b/site2/website/versioned_docs/version-2.6.2/reference-configuration.md
@@ -106,6 +106,8 @@ Pulsar brokers are responsible for handling incoming messages from producers, di
|Name|Description|Default|
|---|---|---|
+|advertisedListeners|Specify multiple advertised listeners for the broker.<br><br>The format is `<listener_name>:pulsar://<host>:<port>`.<br><br>If there are multiple listeners, separate them with commas.<br><br>**Note**: do not use this configuration with `advertisedAddress` and `brokerServicePort`. If the value of this configuration is empty, the broker uses `advertisedAddress` and `brokerServicePort`|/|
+|internalListenerName|Specify the internal listener name for the broker.<br><br>**Note**: the listener name must be contained in `advertisedListeners`.<br><br> If the value of this configuration is empty, the broker uses the first listener as the internal listener.|/|
|enablePersistentTopics| Whether persistent topics are enabled on the broker |true|
|enableNonPersistentTopics| Whether non-persistent topics are enabled on the broker |true|
|functionsWorkerEnabled| Whether the Pulsar Functions worker service is enabled in the broker |false|