You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by li...@apache.org on 2021/12/30 01:48:53 UTC
[pulsar] branch master updated: [Doc] add docs for client, security, geo (#13556)
This is an automated email from the ASF dual-hosted git repository.
liuyu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new 6a4cbf7 [Doc] add docs for client, security, geo (#13556)
6a4cbf7 is described below
commit 6a4cbf7900f319aebc37b6df668ffa0b0cb12d96
Author: Anonymitaet <50...@users.noreply.github.com>
AuthorDate: Thu Dec 30 09:45:36 2021 +0800
[Doc] add docs for client, security, geo (#13556)
---
site2/docs/security-tls-keystore.md | 2 +
.../version-2.7.4/security-tls-keystore.md | 15 +++++
.../version-2.8.2/client-libraries-websocket.md | 64 ++++++++++++++++-----
.../version-2.8.2/security-tls-keystore.md | 15 +++++
.../version-2.9.0/client-libraries-websocket.md | 63 ++++++++++++++++-----
.../version-2.9.1/administration-geo.md | 36 ++++++++++--
.../version-2.9.1/client-libraries-websocket.md | 65 +++++++++++++++++-----
7 files changed, 212 insertions(+), 48 deletions(-)
diff --git a/site2/docs/security-tls-keystore.md b/site2/docs/security-tls-keystore.md
index c5cf097..4adfdc1 100644
--- a/site2/docs/security-tls-keystore.md
+++ b/site2/docs/security-tls-keystore.md
@@ -132,6 +132,7 @@ brokerClientTlsTrustStorePassword=clientpw
NOTE: it is important to restrict access to the store files via filesystem permissions.
If you have configured TLS on the broker, to disable non-TLS ports, you can set the values of the following configurations to empty as below.
+
```
brokerServicePort=
webServicePort=
@@ -143,6 +144,7 @@ brokerClientTlsEnabled=true // Set this to true
brokerClientTlsEnabledWithKeyStore=true // Set this to true
brokerClientTlsTrustStore= // Set this to your desired value
brokerClientTlsTrustStorePassword= // Set this to your desired value
+```
Optional settings that may worth consider:
diff --git a/site2/website/versioned_docs/version-2.7.4/security-tls-keystore.md b/site2/website/versioned_docs/version-2.7.4/security-tls-keystore.md
index 5c125a1..aec7b3f 100644
--- a/site2/website/versioned_docs/version-2.7.4/security-tls-keystore.md
+++ b/site2/website/versioned_docs/version-2.7.4/security-tls-keystore.md
@@ -132,6 +132,21 @@ brokerClientTlsTrustStorePassword=clientpw
NOTE: it is important to restrict access to the store files via filesystem permissions.
+If you have configured TLS on the broker, to disable non-TLS ports, you can set the values of the following configurations to empty as below.
+
+```
+brokerServicePort=
+webServicePort=
+```
+In this case, you need to set the following configurations.
+
+```conf
+brokerClientTlsEnabled=true // Set this to true
+brokerClientTlsEnabledWithKeyStore=true // Set this to true
+brokerClientTlsTrustStore= // Set this to your desired value
+brokerClientTlsTrustStorePassword= // Set this to your desired value
+```
+
Optional settings that may worth consider:
1. tlsClientAuthentication=false: Enable/Disable using TLS for authentication. This config when enabled will authenticate the other end
diff --git a/site2/website/versioned_docs/version-2.8.2/client-libraries-websocket.md b/site2/website/versioned_docs/version-2.8.2/client-libraries-websocket.md
index 7264ae6..881868b 100644
--- a/site2/website/versioned_docs/version-2.8.2/client-libraries-websocket.md
+++ b/site2/website/versioned_docs/version-2.8.2/client-libraries-websocket.md
@@ -181,22 +181,58 @@ Server will push messages on the WebSocket session:
```json
{
- "messageId": "CAAQAw==",
- "payload": "SGVsbG8gV29ybGQ=",
- "properties": {"key1": "value1", "key2": "value2"},
- "publishTime": "2016-08-30 16:45:57.785",
- "redeliveryCount": 4
-}
+ "messageId": "CAMQADAA",
+ "payload": "hvXcJvHW7kOSrUn17P2q71RA5SdiXwZBqw==",
+ "properties": {},
+ "publishTime": "2021-10-29T16:01:38.967-07:00",
+ "redeliveryCount": 0,
+ "encryptionContext": {
+ "keys": {
+ "client-rsa.pem": {
+ "keyValue": "jEuwS+PeUzmCo7IfLNxqoj4h7txbLjCQjkwpaw5AWJfZ2xoIdMkOuWDkOsqgFmWwxiecakS6GOZHs94x3sxzKHQx9Oe1jpwBg2e7L4fd26pp+WmAiLm/ArZJo6JotTeFSvKO3u/yQtGTZojDDQxiqFOQ1ZbMdtMZA8DpSMuq+Zx7PqLo43UdW1+krjQfE5WD+y+qE3LJQfwyVDnXxoRtqWLpVsAROlN2LxaMbaftv5HckoejJoB4xpf/dPOUqhnRstwQHf6klKT5iNhjsY4usACt78uILT0pEPd14h8wEBidBz/vAlC/zVMEqiDVzgNS7dqEYS4iHbf7cnWVCn3Hxw==",
+ "metadata": {}
+ }
+ },
+ "param": "Tfu1PxVm6S9D3+Hk",
+ "compressionType": "NONE",
+ "uncompressedMessageSize": 0,
+ "batchSize": {
+ "empty": false,
+ "present": true
+ }
+ }
```
-Key | Type | Required? | Explanation
-:---|:-----|:----------|:-----------
-`messageId` | string | yes | Message ID
-`payload` | string | yes | Base-64 encoded payload
-`publishTime` | string | yes | Publish timestamp
-`redeliveryCount` | number | yes | Number of times this message was already delivered
-`properties` | key-value pairs | no | Application-defined properties
-`key` | string | no | Original routing key set by producer
+Below are the parameters in the WebSocket consumer response.
+
+- General parameters
+
+ Key | Type | Required? | Explanation
+ :---|:-----|:----------|:-----------
+ `messageId` | string | yes | Message ID
+ `payload` | string | yes | Base-64 encoded payload
+ `publishTime` | string | yes | Publish timestamp
+ `redeliveryCount` | number | yes | Number of times this message was already delivered
+ `properties` | key-value pairs | no | Application-defined properties
+ `key` | string | no | Original routing key set by producer
+ `encryptionContext` | EncryptionContext | no | Encryption context that consumers can use to decrypt received messages
+ `param` | string | no | Initialization vector for cipher (Base64 encoding)
+ `batchSize` | string | no | Number of entries in a message (if it is a batch message)
+ `uncompressedMessageSize` | string | no | Message size before compression
+ `compressionType` | string | no | Algorithm used to compress the message payload
+
+- `encryptionContext` related parameter
+
+ Key | Type | Required? | Explanation
+ :---|:-----|:----------|:-----------
+ `keys` |key-EncryptionKey pairs | yes | Key in `key-EncryptionKey` pairs is an encryption key name. Value in `key-EncryptionKey` pairs is an encryption key object.
+
+- `encryptionKey` related parameters
+
+ Key | Type | Required? | Explanation
+ :---|:-----|:----------|:-----------
+ `keyValue` | string | yes | Encryption key (Base64 encoding)
+ `metadata` | key-value pairs | no | Application-defined metadata
#### Acknowledging the message
diff --git a/site2/website/versioned_docs/version-2.8.2/security-tls-keystore.md b/site2/website/versioned_docs/version-2.8.2/security-tls-keystore.md
index cff3bbd..4d4ba1a 100644
--- a/site2/website/versioned_docs/version-2.8.2/security-tls-keystore.md
+++ b/site2/website/versioned_docs/version-2.8.2/security-tls-keystore.md
@@ -132,6 +132,21 @@ brokerClientTlsTrustStorePassword=clientpw
NOTE: it is important to restrict access to the store files via filesystem permissions.
+If you have configured TLS on the broker, to disable non-TLS ports, you can set the values of the following configurations to empty as below.
+
+```
+brokerServicePort=
+webServicePort=
+```
+In this case, you need to set the following configurations.
+
+```conf
+brokerClientTlsEnabled=true // Set this to true
+brokerClientTlsEnabledWithKeyStore=true // Set this to true
+brokerClientTlsTrustStore= // Set this to your desired value
+brokerClientTlsTrustStorePassword= // Set this to your desired value
+```
+
Optional settings that may worth consider:
1. tlsClientAuthentication=false: Enable/Disable using TLS for authentication. This config when enabled will authenticate the other end
diff --git a/site2/website/versioned_docs/version-2.9.0/client-libraries-websocket.md b/site2/website/versioned_docs/version-2.9.0/client-libraries-websocket.md
index f829296..bf9031c 100644
--- a/site2/website/versioned_docs/version-2.9.0/client-libraries-websocket.md
+++ b/site2/website/versioned_docs/version-2.9.0/client-libraries-websocket.md
@@ -181,22 +181,59 @@ Server will push messages on the WebSocket session:
```json
{
- "messageId": "CAAQAw==",
- "payload": "SGVsbG8gV29ybGQ=",
- "properties": {"key1": "value1", "key2": "value2"},
- "publishTime": "2016-08-30 16:45:57.785",
- "redeliveryCount": 4
+"messageId": "CAMQADAA",
+ "payload": "hvXcJvHW7kOSrUn17P2q71RA5SdiXwZBqw==",
+ "properties": {},
+ "publishTime": "2021-10-29T16:01:38.967-07:00",
+ "redeliveryCount": 0,
+ "encryptionContext": {
+ "keys": {
+ "client-rsa.pem": {
+ "keyValue": "jEuwS+PeUzmCo7IfLNxqoj4h7txbLjCQjkwpaw5AWJfZ2xoIdMkOuWDkOsqgFmWwxiecakS6GOZHs94x3sxzKHQx9Oe1jpwBg2e7L4fd26pp+WmAiLm/ArZJo6JotTeFSvKO3u/yQtGTZojDDQxiqFOQ1ZbMdtMZA8DpSMuq+Zx7PqLo43UdW1+krjQfE5WD+y+qE3LJQfwyVDnXxoRtqWLpVsAROlN2LxaMbaftv5HckoejJoB4xpf/dPOUqhnRstwQHf6klKT5iNhjsY4usACt78uILT0pEPd14h8wEBidBz/vAlC/zVMEqiDVzgNS7dqEYS4iHbf7cnWVCn3Hxw==",
+ "metadata": {}
+ }
+ },
+ "param": "Tfu1PxVm6S9D3+Hk",
+ "compressionType": "NONE",
+ "uncompressedMessageSize": 0,
+ "batchSize": {
+ "empty": false,
+ "present": true
+ }
+ }
}
```
-Key | Type | Required? | Explanation
-:---|:-----|:----------|:-----------
-`messageId` | string | yes | Message ID
-`payload` | string | yes | Base-64 encoded payload
-`publishTime` | string | yes | Publish timestamp
-`redeliveryCount` | number | yes | Number of times this message was already delivered
-`properties` | key-value pairs | no | Application-defined properties
-`key` | string | no | Original routing key set by producer
+Below are the parameters in the WebSocket consumer response.
+
+- General parameters
+
+ Key | Type | Required? | Explanation
+ :---|:-----|:----------|:-----------
+ `messageId` | string | yes | Message ID
+ `payload` | string | yes | Base-64 encoded payload
+ `publishTime` | string | yes | Publish timestamp
+ `redeliveryCount` | number | yes | Number of times this message was already delivered
+ `properties` | key-value pairs | no | Application-defined properties
+ `key` | string | no | Original routing key set by producer
+ `encryptionContext` | EncryptionContext | no | Encryption context that consumers can use to decrypt received messages
+ `param` | string | no | Initialization vector for cipher (Base64 encoding)
+ `batchSize` | string | no | Number of entries in a message (if it is a batch message)
+ `uncompressedMessageSize` | string | no | Message size before compression
+ `compressionType` | string | no | Algorithm used to compress the message payload
+
+- `encryptionContext` related parameter
+
+ Key | Type | Required? | Explanation
+ :---|:-----|:----------|:-----------
+ `keys` |key-EncryptionKey pairs | yes | Key in `key-EncryptionKey` pairs is an encryption key name. Value in `key-EncryptionKey` pairs is an encryption key object.
+
+- `encryptionKey` related parameters
+
+ Key | Type | Required? | Explanation
+ :---|:-----|:----------|:-----------
+ `keyValue` | string | yes | Encryption key (Base64 encoding)
+ `metadata` | key-value pairs | no | Application-defined metadata
#### Acknowledging the message
diff --git a/site2/website/versioned_docs/version-2.9.1/administration-geo.md b/site2/website/versioned_docs/version-2.9.1/administration-geo.md
index bdfa2f7..387ca49 100644
--- a/site2/website/versioned_docs/version-2.9.1/administration-geo.md
+++ b/site2/website/versioned_docs/version-2.9.1/administration-geo.md
@@ -44,8 +44,6 @@ All messages produced in any of the three clusters are delivered to all subscrip
## Configure replication
-As stated in [Geo-replication and Pulsar properties](#geo-replication-and-pulsar-properties) section, geo-replication in Pulsar is managed at the [tenant](reference-terminology.md#tenant) level.
-
The following example connects three clusters: **us-east**, **us-west**, and **us-cent**.
### Connect replication clusters
@@ -99,7 +97,11 @@ $ bin/pulsar-admin tenants create my-tenant \
To update permissions of an existing tenant, use `update` instead of `create`.
-### Enable geo-replication namespaces
+### Enable geo-replication
+
+You can enable geo-replication at **namespace** or **topic** level.
+
+#### Enable geo-replication at namespace level
You can create a namespace with the following command sample.
@@ -114,7 +116,19 @@ $ bin/pulsar-admin namespaces set-clusters my-tenant/my-namespace \
--clusters us-west,us-east,us-cent
```
-You can change the replication clusters for a namespace at any time, without disruption to ongoing traffic. Replication channels are immediately set up or stopped in all clusters as soon as the configuration changes.
+#### Enable geo-replication at topic level
+
+You can set geo-replication at topic level using the command `pulsar-admin topics set-replication-clusters`. For the latest and complete information about `Pulsar admin`, including commands, flags, descriptions, and more information, see [Pulsar admin doc](https://pulsar.apache.org/tools/pulsar-admin/).
+
+```shell
+$ bin/pulsar-admin topics set-replication-clusters --clusters us-west,us-east,us-cent my-tenant/my-namespace/my-topic
+```
+
+> **Tip**
+>
+> - You can change the replication clusters for a namespace at any time, without disruption to ongoing traffic. Replication channels are immediately set up or stopped in all clusters as soon as the configuration changes.
+>
+> - Once you create a geo-replication namespace, any topics that producers or consumers create within that namespace are replicated across clusters. Typically, each application uses the `serviceUrl` for the local cluster.
### Use topics with geo-replication
@@ -144,12 +158,22 @@ producer.newMessage()
#### Topic stats
-Topic-specific statistics for geo-replication topics are available via the [`pulsar-admin`](reference-pulsar-admin.md) tool and {@inject: rest:REST:/} API:
+You can check topic-specific statistics for geo-replication topics using one of the following methods.
+
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
+
+Use the [`pulsar-admin topics stats`](https://pulsar.apache.org/tools/pulsar-admin/) command.
```shell
-$ bin/pulsar-admin persistent stats persistent://my-tenant/my-namespace/my-topic
+$ bin/pulsar-admin topics stats persistent://my-tenant/my-namespace/my-topic
```
+<!--REST API-->
+{@inject: endpoint|GET|/admin/v2/:schema/:tenant/:namespace/:topic/stats|operation/getStats?version=[[pulsar:version_number]]}
+
+<!--END_DOCUSAURUS_CODE_TABS-->
+
Each cluster reports its own local stats, including the incoming and outgoing replication rates and backlogs.
#### Delete a geo-replication topic
diff --git a/site2/website/versioned_docs/version-2.9.1/client-libraries-websocket.md b/site2/website/versioned_docs/version-2.9.1/client-libraries-websocket.md
index 2837da0..5ea8937 100644
--- a/site2/website/versioned_docs/version-2.9.1/client-libraries-websocket.md
+++ b/site2/website/versioned_docs/version-2.9.1/client-libraries-websocket.md
@@ -180,23 +180,58 @@ even if the client doesn't consume on the WebSocket.
Server will push messages on the WebSocket session:
```json
-{
- "messageId": "CAAQAw==",
- "payload": "SGVsbG8gV29ybGQ=",
- "properties": {"key1": "value1", "key2": "value2"},
- "publishTime": "2016-08-30 16:45:57.785",
- "redeliveryCount": 4
-}
+"messageId": "CAMQADAA",
+ "payload": "hvXcJvHW7kOSrUn17P2q71RA5SdiXwZBqw==",
+ "properties": {},
+ "publishTime": "2021-10-29T16:01:38.967-07:00",
+ "redeliveryCount": 0,
+ "encryptionContext": {
+ "keys": {
+ "client-rsa.pem": {
+ "keyValue": "jEuwS+PeUzmCo7IfLNxqoj4h7txbLjCQjkwpaw5AWJfZ2xoIdMkOuWDkOsqgFmWwxiecakS6GOZHs94x3sxzKHQx9Oe1jpwBg2e7L4fd26pp+WmAiLm/ArZJo6JotTeFSvKO3u/yQtGTZojDDQxiqFOQ1ZbMdtMZA8DpSMuq+Zx7PqLo43UdW1+krjQfE5WD+y+qE3LJQfwyVDnXxoRtqWLpVsAROlN2LxaMbaftv5HckoejJoB4xpf/dPOUqhnRstwQHf6klKT5iNhjsY4usACt78uILT0pEPd14h8wEBidBz/vAlC/zVMEqiDVzgNS7dqEYS4iHbf7cnWVCn3Hxw==",
+ "metadata": {}
+ }
+ },
+ "param": "Tfu1PxVm6S9D3+Hk",
+ "compressionType": "NONE",
+ "uncompressedMessageSize": 0,
+ "batchSize": {
+ "empty": false,
+ "present": true
+ }
+ }
```
-Key | Type | Required? | Explanation
-:---|:-----|:----------|:-----------
-`messageId` | string | yes | Message ID
-`payload` | string | yes | Base-64 encoded payload
-`publishTime` | string | yes | Publish timestamp
-`redeliveryCount` | number | yes | Number of times this message was already delivered
-`properties` | key-value pairs | no | Application-defined properties
-`key` | string | no | Original routing key set by producer
+Below are the parameters in the WebSocket consumer response.
+
+- General parameters
+
+ Key | Type | Required? | Explanation
+ :---|:-----|:----------|:-----------
+ `messageId` | string | yes | Message ID
+ `payload` | string | yes | Base-64 encoded payload
+ `publishTime` | string | yes | Publish timestamp
+ `redeliveryCount` | number | yes | Number of times this message was already delivered
+ `properties` | key-value pairs | no | Application-defined properties
+ `key` | string | no | Original routing key set by producer
+ `encryptionContext` | EncryptionContext | no | Encryption context that consumers can use to decrypt received messages
+ `param` | string | no | Initialization vector for cipher (Base64 encoding)
+ `batchSize` | string | no | Number of entries in a message (if it is a batch message)
+ `uncompressedMessageSize` | string | no | Message size before compression
+ `compressionType` | string | no | Algorithm used to compress the message payload
+
+- `encryptionContext` related parameter
+
+ Key | Type | Required? | Explanation
+ :---|:-----|:----------|:-----------
+ `keys` |key-EncryptionKey pairs | yes | Key in `key-EncryptionKey` pairs is an encryption key name. Value in `key-EncryptionKey` pairs is an encryption key object.
+
+- `encryptionKey` related parameters
+
+ Key | Type | Required? | Explanation
+ :---|:-----|:----------|:-----------
+ `keyValue` | string | yes | Encryption key (Base64 encoding)
+ `metadata` | key-value pairs | no | Application-defined metadata
#### Acknowledging the message