sijie closed pull request #2243: [website] add a terminology page and replace
popovers with hyperlinks
URL: https://github.com/apache/incubator-pulsar/pull/2243
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/site2/docs/admin-api-brokers.md b/site2/docs/admin-api-brokers.md
index 35ff69fbeb..9cc3023898 100644
--- a/site2/docs/admin-api-brokers.md
+++ b/site2/docs/admin-api-brokers.md
@@ -6,10 +6,10 @@ sidebar_label: Brokers
Pulsar brokers consist of two components:
-1. An HTTP server exposing a [REST interface](reference-rest-api.md)
administration and {% popover topic %} lookup.
-2. A dispatcher that handles all Pulsar {% popover message %} transfers.
+1. An HTTP server exposing a [REST interface](reference-rest-api.md)
administration and [topic](reference-terminology.md#topic) lookup.
+2. A dispatcher that handles all Pulsar
[message](reference-terminology.md#message) transfers.
-{% popover Brokers %} can be managed via:
+[Brokers](reference-terminology.md#broker) can be managed via:
* The [`brokers`](reference-pulsar-admin.md#brokers) command of the
[`pulsar-admin`](reference-pulsar-admin.md) tool
* The `/admin/v2/brokers` endpoint of the admin [REST
API](reference-rest-api.md)
@@ -80,9 +80,9 @@ admin.brokers().getOwnedNamespaces(cluster,brokerUrl);
### Dynamic broker configuration
-One way to configure a Pulsar {% popover broker %} is to supply a
[configuration](reference-configuration.md#broker) when the broker is [started
up](reference-cli-tools.md#pulsar-broker).
+One way to configure a Pulsar [broker](reference-terminology.md#broker) is to
supply a [configuration](reference-configuration.md#broker) when the broker is
[started up](reference-cli-tools.md#pulsar-broker).
-But since all broker configuration in Pulsar is stored in {% popover ZooKeeper
%}, configuration values can also be dynamically updated *while the broker is
running*. When you update broker configuration dynamically, ZooKeeper will
notify the broker of the change and the broker will then override any existing
configuration values.
+But since all broker configuration in Pulsar is stored in ZooKeeper,
configuration values can also be dynamically updated *while the broker is
running*. When you update broker configuration dynamically, ZooKeeper will
notify the broker of the change and the broker will then override any existing
configuration values.
* The [`brokers`](reference-pulsar-admin.md#brokers) command for the
[`pulsar-admin`](reference-pulsar-admin.md) tool has a variety of subcommands
that enable you to manipulate a broker's configuration dynamically, enabling
you to [update config values](#update-dynamic-configuration) and more.
* In the Pulsar admin [REST API](reference-rest-api.md), dynamic configuration
is managed through the `/admin/v2/brokers/configuration` endpoint.
diff --git a/site2/docs/admin-api-clusters.md b/site2/docs/admin-api-clusters.md
index e625ae1e75..9f0d23eab9 100644
--- a/site2/docs/admin-api-clusters.md
+++ b/site2/docs/admin-api-clusters.md
@@ -4,7 +4,8 @@ title: Managing Clusters
sidebar_label: Clusters
---
-Pulsar clusters consist of one or more Pulsar {% popover brokers %}, one or
more {% popover BookKeeper %} servers (aka {% popover bookies %}), and a {%
popover ZooKeeper %} cluster that provides configuration and coordination
management.
+Pulsar clusters consist of one or more Pulsar
[brokers](reference-terminology.md#broker), one or more
[BookKeeper](reference-terminology.md#bookkeeper)
+servers (aka [bookies](reference-terminology.md#bookie)), and a
[ZooKeeper](https://zookeeper.apache.org) cluster that provides configuration
and coordination management.
Clusters can be managed via:
@@ -56,7 +57,7 @@ When provision a new cluster, you need to initialize that
cluster's [metadata](g
* The local ZooKeeper connection string for the cluster
* The global ZooKeeper connection string for the entire instance
* The web service URL for the cluster
-* A broker service URL enabling interaction with the {% popover brokers %} in
the cluster
+* A broker service URL enabling interaction with the
[brokers](reference-terminology.md#broker) in the cluster
You must initialize cluster metadata *before* starting up any
[brokers](admin-api-brokers.md) that will belong to the cluster.
@@ -147,7 +148,7 @@ admin.clusters().updateCluster(clusterName, clusterData);
### Delete
-Clusters can be deleted from a Pulsar {% popover instance %}.
+Clusters can be deleted from a Pulsar
[instance](reference-terminology.md#instance).
#### pulsar-admin
@@ -171,7 +172,7 @@ admin.clusters().deleteCluster(clusterName);
### List
-You can fetch a list of all clusters in a Pulsar {% popover instance %}.
+You can fetch a list of all clusters in a Pulsar
[instance](reference-terminology.md#instance).
#### pulsar-admin
@@ -197,7 +198,7 @@ admin.clusters().getClusters();
### Update peer-cluster data
-Peer clusters can be configured for a given cluster in a Pulsar {% popover
instance %}.
+Peer clusters can be configured for a given cluster in a Pulsar
[instance](reference-terminology.md#instance).
#### pulsar-admin
diff --git a/site2/docs/admin-api-namespaces.md
b/site2/docs/admin-api-namespaces.md
index 6d95aaf030..9ebd77029a 100644
--- a/site2/docs/admin-api-namespaces.md
+++ b/site2/docs/admin-api-namespaces.md
@@ -4,7 +4,7 @@ title: Managing Namespaces
sidebar_label: Namespaces
---
-Pulsar {% popover namespaces %} are logical groupings of {% popover topics %}.
+Pulsar [namespaces](reference-terminology.md#namespace) are logical groupings
of [topics](reference-terminology.md#topic).
Namespaces can be managed via:
@@ -16,7 +16,7 @@ Namespaces can be managed via:
### Create
-You can create new namespaces under a given {% popover tenant %}.
+You can create new namespaces under a given
[tenant](reference-terminology.md#tenant).
#### pulsar-admin
@@ -85,7 +85,7 @@ admin.namespaces().getPolicies(namespace);
### List namespaces within a tenant
-You can list all namespaces within a given Pulsar {% popover tenant %}.
+You can list all namespaces within a given Pulsar
[tenant](reference-terminology.md#tenant).
#### pulsar-admin
@@ -631,7 +631,7 @@ Coming soon.
### Unloading from a broker
-You can unload a namespace, or a {% popover namespace bundle %}, from the
Pulsar {% popover broker %} that is currently responsible for it.
+You can unload a namespace, or a [namespace
bundle](reference-terminology.md#namespace-bundle), from the Pulsar
[broker](reference-terminology.md#broker) that is currently responsible for it.
#### pulsar-admin
diff --git a/site2/docs/admin-api-overview.md b/site2/docs/admin-api-overview.md
index f85752df8e..2220418825 100644
--- a/site2/docs/admin-api-overview.md
+++ b/site2/docs/admin-api-overview.md
@@ -4,11 +4,11 @@ title: The Pulsar admin interface
sidebar_label: Overview
---
-The Pulsar admin interface enables you to manage all of the important entities
in a Pulsar {% popover instance %}, such as {% popover properties %}, {%
popover topics %}, and {% popover namespaces %}.
+The Pulsar admin interface enables you to manage all of the important entities
in a Pulsar [instance](reference-terminology.md#instance), such as
[tenants](reference-terminology.md#tenant),
[topics](reference-terminology.md#topic), and
[namespaces](reference-terminology.md#namespace).
You can currently interact with the admin interface via:
-- Making HTTP calls against the admin [REST API](reference-rest-api.md)
provided by Pulsar {% popover brokers %}. For some restful apis, they might be
redirected to topic owner brokers for serving
+- Making HTTP calls against the admin [REST API](reference-rest-api.md)
provided by Pulsar [brokers](reference-terminology.md#broker). For some restful
apis, they might be redirected to topic owner brokers for serving
with [`307 Temporary
Redirect`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307), hence
the HTTP callers should handle `307 Temporary Redirect`. If you are using
`curl`, you should specify `-L`
to handle redirections.
- The `pulsar-admin` CLI tool, which is available in the `bin` folder of your
[Pulsar installation](getting-started-standalone.md):
@@ -28,7 +28,7 @@ In this document, examples from each of the three available
interfaces will be s
## Admin setup
-Each of Pulsar's three admin interfaces---the
[`pulsar-admin`](reference-pulsar-admin.md) CLI tool, the [Java admin
API](/api/admin), and the [REST API](reference-rest-api.md)---requires some
special setup if you have
[authentication](security-overview.md#authentication-providers) enabled in your
Pulsar {% popover instance %}.
+Each of Pulsar's three admin interfaces---the
[`pulsar-admin`](reference-pulsar-admin.md) CLI tool, the [Java admin
API](/api/admin), and the [REST API](reference-rest-api.md)---requires some
special setup if you have
[authentication](security-overview.md#authentication-providers) enabled in your
Pulsar [instance](reference-terminology.md#instance).
### pulsar-admin
@@ -46,11 +46,11 @@ If you have
[authentication](security-overview.md#authentication-providers) enab
### REST API
-You can find documentation for the REST API exposed by Pulsar {% popover
brokers %} in [this reference document](reference-rest-api.md).
+You can find documentation for the REST API exposed by Pulsar
[brokers](reference-terminology.md#broker) in [this reference
document](reference-rest-api.md).
### Java admin client
-To use the Java admin API, instantiate a {% javadoc PulsarAdmin admin
org.apache.pulsar.client.admin.PulsarAdmin %} object, specifying a URL for a
Pulsar {% popover broker %} and a {% javadoc ClientConfiguration admin
org.apache.pulsar.client.admin.ClientConfiguration %}. Here's a minimal example
using `localhost`:
+To use the Java admin API, instantiate a {% javadoc PulsarAdmin admin
org.apache.pulsar.client.admin.PulsarAdmin %} object, specifying a URL for a
Pulsar [broker](reference-terminology.md#broker) and a {% javadoc
ClientConfiguration admin org.apache.pulsar.client.admin.ClientConfiguration
%}. Here's a minimal example using `localhost`:
```java
URL url = new URL("http://localhost:8080";);
diff --git a/site2/docs/admin-api-tenants.md b/site2/docs/admin-api-tenants.md
index da2e9195c3..fdd63bf61a 100644
--- a/site2/docs/admin-api-tenants.md
+++ b/site2/docs/admin-api-tenants.md
@@ -15,7 +15,7 @@ Tenants, like namespaces, can be managed using the [admin
API](admin-api-overvie
#### pulsar-admin
-You can list all of the tenants associated with an {% popover instance %}
using the [`list`](reference-pulsar-admin.md#tenants-list) subcommand:
+You can list all of the tenants associated with an
[instance](reference-terminology.md#instance) using the
[`list`](reference-pulsar-admin.md#tenants-list) subcommand:
```shell
$ pulsar-admin tenants list
diff --git a/site2/docs/administration-dashboard.md
b/site2/docs/administration-dashboard.md
index 427f355281..9305f1e2d6 100644
--- a/site2/docs/administration-dashboard.md
+++ b/site2/docs/administration-dashboard.md
@@ -4,7 +4,7 @@ title: The Pulsar dashboard
sidebar_label: Dashboard
---
-The Pulsar dashboard is a web application that enables users to monitor
current stats for all {% popover topics %} in tabular form.
+The Pulsar dashboard is a web application that enables users to monitor
current stats for all [topics](reference-terminology.md#topic) in tabular form.
The dashboard is a data collector that polls stats from all the brokers in a
Pulsar instance (across multiple clusters) and stores all the information in a
[PostgreSQL](https://www.postgresql.org/) database.
diff --git a/site2/docs/administration-geo.md b/site2/docs/administration-geo.md
index fb5a8b654c..1093323bf8 100644
--- a/site2/docs/administration-geo.md
+++ b/site2/docs/administration-geo.md
@@ -44,7 +44,7 @@ All messages produced in any cluster will be delivered to all
subscriptions in a
## Configuring replication
-As stated [above](#geo-replication-and-pulsar-properties), geo-replication in
Pulsar is managed at the {% popover property %} level.
+As stated [above](#geo-replication-and-pulsar-properties), geo-replication in
Pulsar is managed at the [tenant](reference-terminology.md#tenant) level.
### Granting permissions to properties
diff --git a/site2/docs/administration-zk-bk.md
b/site2/docs/administration-zk-bk.md
index 54d00eaeee..7f8c69c8d9 100644
--- a/site2/docs/administration-zk-bk.md
+++ b/site2/docs/administration-zk-bk.md
@@ -245,7 +245,7 @@ In Pulsar, you can set *persistence policies*, at the
namespace level, that dete
### Set persistence policies
-You can set persistence policies for BookKeeper at the {% popover namespace %}
level.
+You can set persistence policies for BookKeeper at the
[namespace](reference-terminology.md#namespace) level.
#### pulsar-admin
@@ -254,7 +254,7 @@ Use the
[`set-persistence`](reference-pulsar-admin.md#namespaces-set-persistence
Flag | Description | Default
:----|:------------|:-------
`-a`, `--bookkeeper-ack-quorom` | The number of acks (guaranteed copies) to
wait on for each entry | 0
-`-e`, `--bookkeeper-ensemble` | The number of {% popover bookies %} to use for
topics in the namespace | 0
+`-e`, `--bookkeeper-ensemble` | The number of
[bookies](reference-terminology.md#bookie) to use for topics in the namespace | 0
`-w`, `--bookkeeper-write-quorum` | How many writes to make for each entry | 0
`-r`, `--ml-mark-delete-max-rate` | Throttling rate for mark-delete operations
(0 means no throttle) | 0
diff --git a/site2/docs/client-libraries-go.md
b/site2/docs/client-libraries-go.md
index 92a88df336..687fcd44e9 100644
--- a/site2/docs/client-libraries-go.md
+++ b/site2/docs/client-libraries-go.md
@@ -85,8 +85,8 @@ The following configurable parameters are available for
Pulsar clients:
Parameter | Description | Default
:---------|:------------|:-------
`URL` | The connection URL for the Pulsar cluster. See [above](#urls) for more
info |
-`IOThreads` | The number of threads to use for handling connections to Pulsar
{% popover brokers %} | 1
-`OperationTimeoutSeconds` | The timeout for some Go client operations
(creating producers, subscribing to and unsubscribing from {% popover topics
%}). Retries will occur until this threshold is reached, at which point the
operation will fail. | 30
+`IOThreads` | The number of threads to use for handling connections to Pulsar
[brokers](reference-terminology.md#broker) | 1
+`OperationTimeoutSeconds` | The timeout for some Go client operations
(creating producers, subscribing to and unsubscribing from
[topics](reference-terminology.md#topic)). Retries will occur until this
threshold is reached, at which point the operation will fail. | 30
`MessageListenerThreads` | The number of threads used by message listeners
([consumers](#consumers) and [readers](#readers)) | 1
`ConcurrentLookupRequests` | The number of concurrent lookup requests that can
be sent on each broker connection. Setting a maximum helps to keep from
overloading brokers. You should set values over the default of 5000 only if the
client needs to produce and/or subscribe to thousands of Pulsar topics. | 5000
`Logger` | A custom logger implementation for the client (as a function that
takes a log level, file path, line number, and message). All info, warn, and
error messages will be routed to this function. | `nil`
@@ -129,7 +129,7 @@ Pulsar Go producers have the following methods available:
Method | Description | Return type
:------|:------------|:-----------
-`Topic()` | Fetches the producer's {% popover topic %} | `string`
+`Topic()` | Fetches the producer's [topic](reference-terminology.md#topic)|
`string`
`Name()` | Fetchs the producer's name | `string`
`Send(context.Context, ProducerMessage) error` | Publishes a
[message](#messages) to the producer's topic. This call will block until the
message is successfully acknowledged by the Pulsar broker, or an error will be
thrown if the timeout set using the `SendTimeout` in the producer's
[configuration](#producer-configuration) is exceeded. | `error`
`SendAsync(context.Context, ProducerMessage, func(ProducerMessage, error))` |
Publishes a [message](#messages) to the producer's topic asynchronously. The
third argument is a callback function that specifies what happens either when
the message is acknowledged or an error is thrown. |
@@ -193,10 +193,10 @@ func main() {
Parameter | Description | Default
:---------|:------------|:-------
-`Topic` | The Pulsar {% popover topic %} to which the producer will publish
messages |
+`Topic` | The Pulsar [topic](reference-terminology.md#topic) to which the
producer will publish messages |
`Name` | A name for the producer. If you don't explicitly assign a name,
Pulsar will automatically generate a globally unique name that you can access
later using the `Name()` method. If you choose to explicitly assign a name, it
will need to be unique across *all* Pulsar clusters, otherwise the creation
operation will throw an error. |
-`SendTimeout` | When publishing a message to a topic, the producer will wait
for an acknowledgment from the responsible Pulsar {% popover broker %}. If a
message is not acknowledged within the threshold set by this parameter, an
error will be thrown. If you set `SendTimeout` to -1, the timeout will be set
to infinity (and thus removed). Removing the send timeout is recommended when
using Pulsar's [message de-duplication](cookbooks-deduplication.md) feature. |
30 seconds
-`MaxPendingMessages` | The maximum size of the queue holding pending messages
(i.e. messages waiting to receive an acknowledgment from the {% popover broker
%}). By default, when the queue is full all calls to the `Send` and `SendAsync`
methods will fail *unless* `BlockIfQueueFull` is set to `true`. |
+`SendTimeout` | When publishing a message to a topic, the producer will wait
for an acknowledgment from the responsible Pulsar
[broker](reference-terminology.md#broker). If a message is not acknowledged
within the threshold set by this parameter, an error will be thrown. If you set
`SendTimeout` to -1, the timeout will be set to infinity (and thus removed).
Removing the send timeout is recommended when using Pulsar's [message
de-duplication](cookbooks-deduplication.md) feature. | 30 seconds
+`MaxPendingMessages` | The maximum size of the queue holding pending messages
(i.e. messages waiting to receive an acknowledgment from the
[broker](reference-terminology.md#broker)). By default, when the queue is full
all calls to the `Send` and `SendAsync` methods will fail *unless*
`BlockIfQueueFull` is set to `true`. |
`MaxPendingMessagesAcrossPartitions` | |
`BlockIfQueueFull` | If set to `true`, the producer's `Send` and `SendAsync`
methods will block when the outgoing message queue is full rather than failing
and throwing an error (the size of that queue is dictated by the
`MaxPendingMessages` parameter); if set to `false` (the default), `Send` and
`SendAsync` operations will fail and throw a `ProducerQueueIsFullError` when
the queue is full. | `false`
`MessageRoutingMode` | The message routing logic (for producers on
[partitioned
topics](getting-started-concepts-and-architecture.md#partitioned-topics)). This
logic is applied only when no key is set on messages. The available options
are: round robin (`pulsar.RoundRobinDistribution`, the default), publishing all
messages to a single partition (`pulsar.UseSinglePartition`), or a custom
partitioning scheme (`pulsar.CustomPartition`). |
`pulsar.RoundRobinDistribution`
@@ -246,13 +246,13 @@ Pulsar Go consumers have the following methods available:
Method | Description | Return type
:------|:------------|:-----------
-`Topic()` | Returns the consumer's {% popover topic %} | `string`
+`Topic()` | Returns the consumer's [topic](reference-terminology.md#topic) |
`string`
`Subscription()` | Returns the consumer's subscription name | `string`
`Unsubcribe()` | Unsubscribes the consumer from the assigned topic. Throws an
error if the unsubscribe operation is somehow unsuccessful. | `error`
`Receive(context.Context)` | Receives a single message from the topic. This
method blocks until a message is available. | `(Message, error)`
-`Ack(Message)` | {% popover Acknowledges %} a message to the Pulsar {% popover
broker %} | `error`
-`AckID(MessageID)` | {% popover Acknowledges %} a message to the Pulsar {%
popover broker %} by message ID | `error`
-`AckCumulative(Message)` | {% popover Acknowledges %} *all* the messages in
the stream, up to and including the specified message. The `AckCumulative`
method will block until the ack has been sent to the broker. After that, the
messages will *not* be redelivered to the consumer. Cumulative acking can only
be used with a [shared](getting-started-concepts-and-architecture.md#shared)
subscription type.
+`Ack(Message)` | [Acknowledges](reference-terminology.md#acknowledgment-ack) a
message to the Pulsar [broker](reference-terminology.md#broker) | `error`
+`AckID(MessageID)` |
[Acknowledges](reference-terminology.md#acknowledgment-ack) a message to the
Pulsar [broker](reference-terminology.md#broker) by message ID | `error`
+`AckCumulative(Message)` |
[Acknowledges](reference-terminology.md#acknowledgment-ack) *all* the messages
in the stream, up to and including the specified message. The `AckCumulative`
method will block until the ack has been sent to the broker. After that, the
messages will *not* be redelivered to the consumer. Cumulative acking can only
be used with a [shared](getting-started-concepts-and-architecture.md#shared)
subscription type.
`Close()` | Closes the consumer, disabling its ability to receive messages
from the broker | `error`
`RedeliverUnackedMessages()` | Redelivers *all* unacknowledged messages on the
topic. In [failover](getting-started-concepts-and-architecture.md#failover)
mode, this request is ignored if the consumer isn't active on the specified
topic; in [shared](getting-started-concepts-and-architecture.md#shared) mode,
redelivered messages are distributed across all consumers connected to the
topic. **Note**: this is a *non-blocking* operation that doesn't throw an
error. |
@@ -305,7 +305,7 @@ func main() {
Parameter | Description | Default
:---------|:------------|:-------
-`Topic` | The Pulsar {% popover topic %} on which the consumer will establish
a subscription and listen for messages |
+`Topic` | The Pulsar [topic](reference-terminology.md#topic) on which the
consumer will establish a subscription and listen for messages |
`SubscriptionName` | The subscription name for this consumer |
`Name` | The name of the consumer |
`AckTimeout` | | 0
@@ -335,7 +335,7 @@ Pulsar Go readers have the following methods available:
Method | Description | Return type
:------|:------------|:-----------
-`Topic()` | Returns the reader's {% popover topic %} | `string`
+`Topic()` | Returns the reader's [topic](reference-terminology.md#topic) |
`string`
`Next(context.Context)` | Receives the next message on the topic (analogous to
the `Receive` method for [consumers](#consumer-operations)). This method blocks
until a message is available. | `(Message, error)`
`Close()` | Closes the reader, disabling its ability to receive messages from
the broker | `error`
@@ -396,7 +396,7 @@ reader, err := client.CreateReader(pulsar.ReaderOptions{
Parameter | Description | Default
:---------|:------------|:-------
-`Topic` | The Pulsar {% popover topic %} on which the reader will establish a
subscription and listen for messages |
+`Topic` | The Pulsar [topic](reference-terminology.md#topic) on which the
reader will establish a subscription and listen for messages |
`Name` | The name of the reader |
`StartMessageID` | THe initial reader position, i.e. the message at which the
reader begins processing messages. The options are `pulsar.EarliestMessage`
(the earliest available message on the topic), `pulsar.LatestMessage` (the
latest available message on the topic), or a `MessageID` object for a position
that isn't earliest or latest. |
`MessageChannel` | The Go channel used by the reader. Messages that arrive
from the Pulsar topic(s) will be passed to this channel. |
diff --git a/site2/docs/client-libraries-java.md
b/site2/docs/client-libraries-java.md
index 97a1ef1b76..1913bea142 100644
--- a/site2/docs/client-libraries-java.md
+++ b/site2/docs/client-libraries-java.md
@@ -71,7 +71,7 @@ pulsar+ssl://pulsar.us-west.example.com:6651
## Client configuration
-You can instantiate a {% javadoc PulsarClient client
org.apache.pulsar.client.api.PulsarClient %} object using just a URL for the
target Pulsar {% popover cluster %}, like this:
+You can instantiate a {% javadoc PulsarClient client
org.apache.pulsar.client.api.PulsarClient %} object using just a URL for the
target Pulsar [cluster](reference-terminology.md#cluster), like this:
```java
PulsarClient client = PulsarClient.builder()
@@ -89,7 +89,7 @@ Check out the Javadoc for the {% javadoc PulsarClient client
org.apache.pulsar.c
## Producers
-In Pulsar, producers write messages to topics. Once you've instantiated a {%
javadoc PulsarClient client org.apache.pulsar.client.api.PulsarClient %} object
(as in the section [above](#client-configuration)), you can create a {% javadoc
Producer client org.apache.pulsar.client.api.Producer %} for a specific Pulsar
{% popover topic %}.
+In Pulsar, producers write messages to topics. Once you've instantiated a {%
javadoc PulsarClient client org.apache.pulsar.client.api.PulsarClient %} object
(as in the section [above](#client-configuration)), you can create a {% javadoc
Producer client org.apache.pulsar.client.api.Producer %} for a specific Pulsar
[topic](reference-terminology.md#topic).
```java
Producer<byte[]> producer = client.newProducer()
@@ -176,9 +176,9 @@ get a future returned.
## Consumers
-In Pulsar, consumers subscribe to topics and handle messages that producers
publish to those topics. You can instantiate a new {% popover consumer %} by
first instantiating a {% javadoc PulsarClient client
org.apache.pulsar.client.api.PulsarClient %} object and passing it a URL for a
Pulsar broker (as [above](#client-configuration)).
+In Pulsar, consumers subscribe to topics and handle messages that producers
publish to those topics. You can instantiate a new
[consumer](reference-terminology.md#consumer) by first instantiating a {%
javadoc PulsarClient client org.apache.pulsar.client.api.PulsarClient %} object
and passing it a URL for a Pulsar broker (as [above](#client-configuration)).
-Once you've instantiated a {% javadoc PulsarClient client
org.apache.pulsar.client.api.PulsarClient %} object, you can create a {%
javadoc Consumer client org.apache.pulsar.client.api.Consumer %} by specifying
a {% popover topic %} and a
[subscription](getting-started-concepts-and-architecture.md#subscription-modes).
+Once you've instantiated a {% javadoc PulsarClient client
org.apache.pulsar.client.api.PulsarClient %} object, you can create a {%
javadoc Consumer client org.apache.pulsar.client.api.Consumer %} by specifying
a [topic](reference-terminology.md#topic) and a
[subscription](getting-started-concepts-and-architecture.md#subscription-modes).
```java
Consumer consumer = client.newConsumer()
@@ -187,7 +187,7 @@ Consumer consumer = client.newConsumer()
.subscribe();
```
-The `subscribe` method will automatically subscribe the consumer to the
specified topic and subscription. One way to make the consumer listen on the
topic is to set up a `while` loop. In this example loop, the consumer listens
for messages, prints the contents of any message that's received, and then {%
popover acknowledges %} that the message has been processed:
+The `subscribe` method will automatically subscribe the consumer to the
specified topic and subscription. One way to make the consumer listen on the
topic is to set up a `while` loop. In this example loop, the consumer listens
for messages, prints the contents of any message that's received, and then
[acknowledges](reference-terminology.md#acknowledgment-ack) that the message
has been processed:
```java
do {
@@ -335,7 +335,7 @@ Producer<byte[]> producer = client.newProducer()
.create();
```
-The producer above is equivalent to a `Producer<byte[]>` (in fact, you should
*always* explicitly specify the type). If you'd like to use a producer for a
different type of data, you'll need to specify a **schema** that informs Pulsar
which data type will be transmitted over the {% popover topic %}.
+The producer above is equivalent to a `Producer<byte[]>` (in fact, you should
*always* explicitly specify the type). If you'd like to use a producer for a
different type of data, you'll need to specify a **schema** that informs Pulsar
which data type will be transmitted over the
[topic](reference-terminology.md#topic).
### Schema example
diff --git a/site2/docs/client-libraries-websocket.md
b/site2/docs/client-libraries-websocket.md
index 575841ba8a..794f9da419 100644
--- a/site2/docs/client-libraries-websocket.md
+++ b/site2/docs/client-libraries-websocket.md
@@ -28,7 +28,7 @@ webSocketServiceEnabled=true
### As a separate component
-In this mode, the WebSocket service will be run from a Pulsar {% popover
broker %} as a separate service. Configuration for this mode is handled in the
[`conf/websocket.conf`](reference-configuration.md#websocket) configuration
file. You'll need to set *at least* the following parameters:
+In this mode, the WebSocket service will be run from a Pulsar
[broker](reference-terminology.md#broker) as a separate service. Configuration
for this mode is handled in the
[`conf/websocket.conf`](reference-configuration.md#websocket) configuration
file. You'll need to set *at least* the following parameters:
*
[`globalZookeeperServers`](reference-configuration.md#websocket-globalZookeeperServers)
* [`webServicePort`](reference-configuration.md#websocket-webServicePort)
@@ -96,7 +96,7 @@ Key | Type | Required? | Explanation
`properties` | key-value pairs | no | Application-defined properties
`context` | string | no | Application-defined request identifier
`key` | string | no | For partitioned topics, decides which partition to use
-`replicationClusters` | array | no | Restrict replication to this list of {%
popover clusters %}, specified by name
+`replicationClusters` | array | no | Restrict replication to this list of
[clusters](reference-terminology.md#cluster), specified by name
##### Example success response
@@ -268,7 +268,7 @@ You can also download it from
[PyPI](https://pypi.python.org/pypi/websocket-clie
#### Python producer
-Here's an example Python producer that sends a simple message to a Pulsar {%
popover topic %}:
+Here's an example Python producer that sends a simple message to a Pulsar
[topic](reference-terminology.md#topic):
```python
import websocket, base64, json
diff --git a/site2/docs/cookbooks-deduplication.md
b/site2/docs/cookbooks-deduplication.md
index 651c1ff0e4..77b0feb8ef 100644
--- a/site2/docs/cookbooks-deduplication.md
+++ b/site2/docs/cookbooks-deduplication.md
@@ -24,7 +24,7 @@ You can configure message deduplication in Pulsar using the
[`broker.conf`](refe
Parameter | Description | Default
:---------|:------------|:-------
-`brokerDeduplicationEnabled` | Sets the default behavior for message
deduplication in the Pulsar {% popover broker %}. If set to `true`, message
deduplication will be enabled by default on all namespaces; if set to `false`
(the default), deduplication will have to be [enabled](#enabling) and
[disabled](#disabling) on a per-namespace basis. | `false`
+`brokerDeduplicationEnabled` | Sets the default behavior for message
deduplication in the Pulsar [broker](reference-terminology.md#broker). If set
to `true`, message deduplication will be enabled by default on all namespaces;
if set to `false` (the default), deduplication will have to be
[enabled](#enabling) and [disabled](#disabling) on a per-namespace basis. |
`false`
`brokerDeduplicationMaxNumberOfProducers` | The maximum number of producers
for which information will be stored for deduplication purposes. | `10000`
`brokerDeduplicationEntriesInterval` | The number of entries after which a
deduplication informational snapshot is taken. A larger interval will lead to
fewer snapshots being taken, though this would also lengthen the topic recovery
time (the time required for entries published after the snapshot to be
replayed). | `1000`
`brokerDeduplicationProducerInactivityTimeoutMinutes` | The time of inactivity
(in minutes) after which the broker will discard deduplication information
related to a disconnected producer. | `360` (6 hours)
diff --git a/site2/docs/cookbooks-message-queue.md
b/site2/docs/cookbooks-message-queue.md
index a4da5b4dbe..81e0cfa5d8 100644
--- a/site2/docs/cookbooks-message-queue.md
+++ b/site2/docs/cookbooks-message-queue.md
@@ -9,19 +9,19 @@ Message queues are essential components of many large-scale
data architectures.
Pulsar is a great choice for a message queue because:
* it was built with [persistent message
storage](getting-started-concepts-and-architecture.md#persistent-storage) in
mind
-* it offers automatic load balancing across {% popover consumers %} for
messages on a topic (or custom load balancing if you wish)
+* it offers automatic load balancing across
[consumers](reference-terminology.md#consumer) for messages on a topic (or
custom load balancing if you wish)
> You can use the same Pulsar installation to act as a real-time message bus
> and as a message queue if you wish (or just one or the other). You can set
> aside some topics for real-time purposes and other topics for message queue
> purposes (or use specific namespaces for either purpose if you wish).
# Client configuration changes
-To use a Pulsar popover topic as a message queue, you should distribute the
receiver load on that topic across several consumers (the optimal number of
consumers will depend on the load). Each consumer must:
+To use a Pulsar [topic](reference-terminology.md#topic) as a message queue,
you should distribute the receiver load on that topic across several consumers
(the optimal number of consumers will depend on the load). Each consumer must:
* Establish a [shared
subscription](getting-started-concepts-and-architecture.md#shared) and use the
same subscription name as the other consumers (otherwise the subscription is
not shared and the consumers can't act as a processing ensemble)
-* If you'd like to have tight control over message dispatching across
consumers, set the consumers' **receiver queue** size very low (potentially
even to 0 if necessary). Each Pulsar {% popover consumer %} has a receiver
queue that determines how many messages the consumer will attempt to fetch at a
time. A receiver queue of 1000 (the default), for example, means that the
consumer will attempt to process 1000 messages from the topic's backlog upon
connection. Setting the receiver queue to zero essentially means ensuring that
each consumer is only doing one thing at a time.
+* If you'd like to have tight control over message dispatching across
consumers, set the consumers' **receiver queue** size very low (potentially
even to 0 if necessary). Each Pulsar
[consumer](reference-terminology.md#consumer) has a receiver queue that
determines how many messages the consumer will attempt to fetch at a time. A
receiver queue of 1000 (the default), for example, means that the consumer will
attempt to process 1000 messages from the topic's backlog upon connection.
Setting the receiver queue to zero essentially means ensuring that each
consumer is only doing one thing at a time.
- The downside to restricting the receiver queue size of consumers is that
that limits the potential throughput of those consumers and cannot be used with
{% popover partitioned topics %}. Whether the performance/control trade-off is
worthwhile will depend on your use case.
+ The downside to restricting the receiver queue size of consumers is that
that limits the potential throughput of those consumers and cannot be used with
[partitioned topics](reference-terminology.md#partitioned-topic). Whether the
performance/control trade-off is worthwhile will depend on your use case.
## Java clients
diff --git a/site2/docs/cookbooks-non-persistent.md
b/site2/docs/cookbooks-non-persistent.md
index 64eb454c2d..0c595ed6f2 100644
--- a/site2/docs/cookbooks-non-persistent.md
+++ b/site2/docs/cookbooks-non-persistent.md
@@ -14,7 +14,7 @@ sidebar_label: Non-persistent messaging
By default, Pulsar persistently stores *all* unacknowledged messages on
multiple [BookKeeper](#persistent-storage) bookies (storage nodes). Data for
messages on persistent topics can thus survive broker restarts and subscriber
failover.
-Pulsar also, however, supports **non-persistent topics**, which are topics on
which messages are *never* persisted to disk and live only in memory. When
using non-persistent delivery, killing a Pulsar {% popover broker %} or
disconnecting a subscriber to a topic means that all in-transit messages are
lost on that (non-persistent) topic, meaning that clients may see message loss.
+Pulsar also, however, supports **non-persistent topics**, which are topics on
which messages are *never* persisted to disk and live only in memory. When
using non-persistent delivery, killing a Pulsar
[broker](reference-terminology.md#broker) or disconnecting a subscriber to a
topic means that all in-transit messages are lost on that (non-persistent)
topic, meaning that clients may see message loss.
Non-persistent topics have names of this form (note the `non-persistent` in
the name):
diff --git a/site2/docs/cookbooks-partitioned.md
b/site2/docs/cookbooks-partitioned.md
index 61db75f412..82c8885687 100644
--- a/site2/docs/cookbooks-partitioned.md
+++ b/site2/docs/cookbooks-partitioned.md
@@ -10,7 +10,7 @@ You can [publish](#publishing-to-partitioned-topics) to
partitioned topics using
## Publishing to partitioned topics
-When publishing to partitioned topics, the only difference from
non-partitioned topics is that you need to specify a [routing
mode](getting-started-concepts-and-architecture.md#routing-modes) when you
create a new {% popover producer %}. Examples for [Java](#java) are below.
+When publishing to partitioned topics, the only difference from
non-partitioned topics is that you need to specify a [routing
mode](getting-started-concepts-and-architecture.md#routing-modes) when you
create a new [producer](reference-terminology.md#producer). Examples for
[Java](#java) are below.
### Java
diff --git a/site2/docs/cookbooks-retention-expiry.md
b/site2/docs/cookbooks-retention-expiry.md
index 3564c8cf9d..d961b25182 100644
--- a/site2/docs/cookbooks-retention-expiry.md
+++ b/site2/docs/cookbooks-retention-expiry.md
@@ -35,7 +35,7 @@ size retention.
### Defaults
-There are two configuration parameters that you can use to set {% popover
instance %}-wide defaults for message retention:
[`defaultRetentionTimeInMinutes=0`](reference-configuration.md#broker-defaultRetentionTimeInMinutes)
and
[`defaultRetentionSizeInMB=0`](reference-configuration.md#broker-defaultRetentionSizeInMB).
+There are two configuration parameters that you can use to set
[instance](reference-terminology.md#instance)-wide defaults for message
retention:
[`defaultRetentionTimeInMinutes=0`](reference-configuration.md#broker-defaultRetentionTimeInMinutes)
and
[`defaultRetentionSizeInMB=0`](reference-configuration.md#broker-defaultRetentionSizeInMB).
Both of these parameters are in the
[`broker.conf`](reference-configuration.md#broker) configuration file.
@@ -130,7 +130,7 @@ admin.namespaces().getRetention(namespace);
You can control the allowable size of backlogs, at the namespace level, using
*backlog quotas*. Setting a backlog quota involves setting:
* an allowable *size threshold* for each topic in the namespace
-* a *retention policy* that determines which action the {% popover broker %}
takes if the threshold is exceeded.
+* a *retention policy* that determines which action the
[broker](reference-terminology.md#broker) takes if the threshold is exceeded.
The following retention policies are available:
@@ -149,7 +149,7 @@ Backlog quotas are handled at the namespace level. They can
be managed via:
### Set size thresholds and backlog retention policies
-You can set a size threshold and backlog retention policy for all of the
topics in a {% popover namespace %} by specifying the namespace, a size limit,
and a policy by name.
+You can set a size threshold and backlog retention policy for all of the
topics in a [namespace](reference-terminology.md#namespace) by specifying the
namespace, a size limit, and a policy by name.
#### pulsar-admin
diff --git a/site2/docs/deploy-aws.md b/site2/docs/deploy-aws.md
index f533e99b7d..1ef3cc3db0 100644
--- a/site2/docs/deploy-aws.md
+++ b/site2/docs/deploy-aws.md
@@ -6,7 +6,7 @@ sidebar_label: Amazon Web Services
> For instructions on deploying a single Pulsar cluster manually rather than
> using Terraform and Ansible, see [Deploying a Pulsar cluster on bare
> metal](deploy-bare-metal.md). For instructions on manually deploying a
> multi-cluster Pulsar instance, see [Deploying a Pulsar instance on bare
> metal](deploy-bare-metal-multi-cluster.md).
-One of the easiest ways to get a Pulsar {% popover cluster %} running on
[Amazon Web Services](https://aws.amazon.com/) (AWS) is to use the the
[Terraform](https://terraform.io) infrastructure provisioning tool and the
[Ansible](https://www.ansible.com) server automation tool. Terraform can create
the resources necessary to run the Pulsar
cluster---[EC2](https://aws.amazon.com/ec2/) instances, networking and security
infrastructure, etc.---while Ansible can install and run Pulsar on the
provisioned resources.
+One of the easiest ways to get a Pulsar
[cluster](reference-terminology.md#cluster) running on [Amazon Web
Services](https://aws.amazon.com/) (AWS) is to use the the
[Terraform](https://terraform.io) infrastructure provisioning tool and the
[Ansible](https://www.ansible.com) server automation tool. Terraform can create
the resources necessary to run the Pulsar
cluster---[EC2](https://aws.amazon.com/ec2/) instances, networking and security
infrastructure, etc.---while Ansible can install and run Pulsar on the
provisioned resources.
## Requirements and setup
@@ -102,7 +102,7 @@ When you run the Ansible playbook, the following AWS
resources will be used:
* 6 total [Elastic Compute Cloud](https://aws.amazon.com/ec2) (EC2) instances
running the [ami-9fa343e7](https://access.redhat.com/articles/3135091) Amazon
Machine Image (AMI), which runs [Red Hat Enterprise Linux (RHEL)
7.4](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html-single/7.4_release_notes/index).
By default, that includes:
* 3 small VMs for ZooKeeper
([t2.small](https://www.ec2instances.info/?selected=t2.small) instances)
- * 3 larger VMs for Pulsar {% popover brokers %} and BookKeeper {% popover
bookies %} ([i3.4xlarge](https://www.ec2instances.info/?selected=i3.4xlarge)
instances)
+ * 3 larger VMs for Pulsar [brokers](reference-terminology.md#broker) and
BookKeeper [bookies](reference-terminology.md#bookie)
([i3.4xlarge](https://www.ec2instances.info/?selected=i3.4xlarge) instances)
* An EC2 [security
group](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html)
* A [virtual private cloud](https://aws.amazon.com/vpc/) (VPC) for security
* An [API Gateway](https://aws.amazon.com/api-gateway/) for connections from
the outside world
diff --git a/site2/docs/deploy-bare-metal-multi-cluster.md
b/site2/docs/deploy-bare-metal-multi-cluster.md
index d20047efc7..d2bb62a5db 100644
--- a/site2/docs/deploy-bare-metal-multi-cluster.md
+++ b/site2/docs/deploy-bare-metal-multi-cluster.md
@@ -209,7 +209,7 @@ As you can see from the example above, the following needs
to be specified:
* The local ZooKeeper connection string for the cluster
* The configuration store connection string for the entire instance
* The web service URL for the cluster
-* A broker service URL enabling interaction with the {% popover brokers %} in
the cluster
+* A broker service URL enabling interaction with the
[brokers](reference-terminology.md#broker) in the cluster
If you're using [TLS](security-tls.md), you'll also need to specify a TLS web
service URL for the cluster as well as a TLS broker service URL for the brokers
in the cluster.
@@ -268,7 +268,7 @@ Brokers can be configured using the
[`conf/broker.conf`](reference-configuration
The most important element of broker configuration is ensuring that each
broker is aware of its local ZooKeeper quorum as well as the global ZooKeeper
quorum. Make sure that you set the
[`zookeeperServers`](reference-configuration.md#broker-zookeeperServers)
parameter to reflect the local quorum and the
[`configurationStoreServers`](reference-configuration.md#broker-configurationStoreServers)
parameter to reflect the configuration store quorum (although you'll need to
specify only those ZooKeeper servers located in the same cluster).
-You also need to specify the name of the {% popover cluster %} to which the
broker belongs using the
[`clusterName`](reference-configuration.md#broker-clusterName) parameter.
+You also need to specify the name of the
[cluster](reference-terminology.md#cluster) to which the broker belongs using
the [`clusterName`](reference-configuration.md#broker-clusterName) parameter.
Here's an example configuration:
@@ -314,7 +314,8 @@ You can also use your own service discovery system if you'd
like. If you use you
The service discovery mechanism included with Pulsar maintains a list of
active brokers, stored in ZooKeeper, and supports lookup using HTTP and also
Pulsar's [binary protocol](developing-binary-protocol.md).
-To get started setting up Pulsar's built-in service discovery, you need to
change a few parameters in the
[`conf/discovery.conf`](reference-configuration.md#service-discovery)
configuration file. Set the
[`zookeeperServers`](reference-configuration.md#service-discovery-zookeeperServers)
parameter to the cluster's ZooKeeper quorum connection string and the
[`configurationStoreServers`](reference-configuration.md#service-discovery-configurationStoreServers)
setting to the {% popover configuration store %} quorum connection string.
+To get started setting up Pulsar's built-in service discovery, you need to
change a few parameters in the
[`conf/discovery.conf`](reference-configuration.md#service-discovery)
configuration file. Set the
[`zookeeperServers`](reference-configuration.md#service-discovery-zookeeperServers)
parameter to the cluster's ZooKeeper quorum connection string and the
[`configurationStoreServers`](reference-configuration.md#service-discovery-configurationStoreServers)
setting to the [configuration
+store](reference-terminology.md#configuration-store) quorum connection string.
```properties
# Zookeeper quorum connection string
@@ -356,7 +357,7 @@ $ bin/pulsar-admin tenants create test-tentant \
This will allow users who identify with role `test-admin-role` to administer
the configuration for the tenant `test` which will only be allowed to use the
cluster `us-west`. From now on, this tenant will be able to self-manage its
resources.
-Once a tenant has been created, you will need to create {% popover namespaces
%} for topics within that tenant.
+Once a tenant has been created, you will need to create
[namespaces](reference-terminology.md#namespace) for topics within that tenant.
The first step is to create a namespace. A namespace is an administrative unit
that can contain many topics. A common practice is to create a namespace for
each different use case from a single tenant.
diff --git a/site2/docs/deploy-dcos.md b/site2/docs/deploy-dcos.md
index 64b3d962b5..6d6f53f6f3 100644
--- a/site2/docs/deploy-dcos.md
+++ b/site2/docs/deploy-dcos.md
@@ -39,8 +39,8 @@ $ dcos marathon group add PulsarGroups.json
This command will deploy Docker container instances in three groups, which
together comprise a Pulsar cluster:
-* 3 bookies (1 {% popover bookie %} on each agent node and 1 [bookie
recovery](http://bookkeeper.apache.org/docs/latest/admin/autorecovery/)
instance)
-* 3 Pulsar {% popover brokers %} (1 broker on each node and 1 admin instance)
+* 3 bookies (1 [bookie](reference-terminology.md#bookie) on each agent node
and 1 [bookie
recovery](http://bookkeeper.apache.org/docs/latest/admin/autorecovery/)
instance)
+* 3 Pulsar [brokers](reference-terminology.md#broker) (1 broker on each node
and 1 admin instance)
* 1 [Prometheus](http://prometheus.io/) instance and 1
[Grafana](https://grafana.com/) instance
@@ -58,7 +58,7 @@ To monitor the status of the BookKeeper cluster deployment,
click on the **bookk
-At this point, 3 {% popover bookies %} should be shown as green, which means
that they have been deployed successfully and are now running.
+At this point, 3 [bookies](reference-terminology.md#bookie) should be shown as
green, which means that they have been deployed successfully and are now
running.
diff --git a/site2/docs/deploy-kubernetes.md b/site2/docs/deploy-kubernetes.md
index 1bdd1b4162..39dc06aa76 100644
--- a/site2/docs/deploy-kubernetes.md
+++ b/site2/docs/deploy-kubernetes.md
@@ -38,7 +38,8 @@ To get started, you'll need:
You can create a new GKE cluster using the [`container clusters
create`](https://cloud.google.com/sdk/gcloud/reference/container/clusters/create)
command for `gcloud`. This command enables you to specify the number of nodes
in the cluster, the machine types of those nodes, and more.
-As an example, we'll create a new GKE cluster for Kubernetes version
[1.6.4](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG.md#v164)
in the
[us-central1-a](https://cloud.google.com/compute/docs/regions-zones/regions-zones#available)
zone. The cluster will be named `pulsar-gke-cluster` and will consist of three
VMs, each using two locally attached SSDs and running on
[n1-standard-8](https://cloud.google.com/compute/docs/machine-types) machines.
These SSDs will be used by {% popover bookie %} instances, one for the
BookKeeper
[journal](getting-started-concepts-and-architecture.md#journal-storage) and the
other for storing the actual message data.
+As an example, we'll create a new GKE cluster for Kubernetes version
[1.6.4](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG.md#v164)
in the
[us-central1-a](https://cloud.google.com/compute/docs/regions-zones/regions-zones#available)
zone. The cluster will be named `pulsar-gke-cluster` and will consist of three
VMs, each using two locally attached SSDs and running on
[n1-standard-8](https://cloud.google.com/compute/docs/machine-types) machines.
These SSDs will be used by
+[bookie](reference-terminology.md#bookie) instances, one for the BookKeeper
[journal](getting-started-concepts-and-architecture.md#journal-storage) and the
other for storing the actual message data.
```bash
$ gcloud container clusters create pulsar-gke-cluster \
@@ -161,7 +162,7 @@ This step may take several minutes, as Kubernetes needs to
download the Docker i
#### Initialize cluster metadata
-Once ZooKeeper is running, you need to [initialize the
metadata](#cluster-metadata-initialization) for the Pulsar cluster in
ZooKeeper. This includes system metadata for {% popover BookKeeper %} and
Pulsar more broadly. There is a Kubernetes
[job](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/)
in the `cluster-metadata.yaml` file that you only need to run once:
+Once ZooKeeper is running, you need to [initialize the
metadata](#cluster-metadata-initialization) for the Pulsar cluster in
ZooKeeper. This includes system metadata for
[BookKeeper](reference-terminology.md#bookkeeper) and Pulsar more broadly.
There is a Kubernetes
[job](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/)
in the `cluster-metadata.yaml` file that you only need to run once:
```bash
$ kubectl apply -f cluster-metadata.yaml
@@ -235,7 +236,7 @@ Now that you have a namespace and property set up, you can
move on to [experimen
#### Experimenting with your cluster
-Now that a property and namespace have been created, you can begin
experimenting with your running Pulsar cluster. Using the same `pulsar-admin`
pod via an alias, as in the section above, you can use
[`pulsar-perf`](reference-cli-tools.md#pulsar-perf) to create a test {% popover
producer %} to publish 10,000 messages a second on a topic in the {% popover
property %} and {% popover namespace %} you created.
+Now that a property and namespace have been created, you can begin
experimenting with your running Pulsar cluster. Using the same `pulsar-admin`
pod via an alias, as in the section above, you can use
[`pulsar-perf`](reference-cli-tools.md#pulsar-perf) to create a test
[producer](reference-terminology.md#producer) to publish 10,000 messages a
second on a topic in the [tenant](reference-terminology.md#tenant) and
[namespace](reference-terminology.md#namespace) you created.
First, create an alias to use the `pulsar-perf` tool via the admin pod:
@@ -250,7 +251,7 @@ $ pulsar-perf produce persistent://public/default/my-topic \
--rate 10000
```
-Similarly, you can start a {% popover consumer %} to subscribe to and receive
all the messages on that topic:
+Similarly, you can start a [consumer](reference-terminology.md#consumer) to
subscribe to and receive all the messages on that topic:
```bash
$ pulsar-perf consume persistent://public/default/my-topic \
@@ -273,7 +274,7 @@ All Pulsar metrics in Kubernetes are collected by a
[Prometheus](https://prometh
#### Grafana
-In your Kubernetes cluster, you can use [Grafana](https://grafana.com) to view
dashbaords for Pulsar {% popover namespaces %} (message rates, latency, and
storage), JVM stats, {% popover ZooKeeper %}, and {% popover BookKeeper %}. You
can get access to the pod serving Grafana using `kubectl`'s
[`port-forward`](https://kubernetes.io/docs/tasks/access-application-cluster/port-forward-access-application-cluster)
command:
+In your Kubernetes cluster, you can use [Grafana](https://grafana.com) to view
dashbaords for Pulsar [namespaces](reference-terminology.md#namespace) (message
rates, latency, and storage), JVM stats,
[ZooKeeper](https://zookeeper.apache.org), and
[BookKeeper](reference-terminology.md#bookkeeper). You can get access to the
pod serving Grafana using `kubectl`'s
[`port-forward`](https://kubernetes.io/docs/tasks/access-application-cluster/port-forward-access-application-cluster)
command:
```bash
$ kubectl port-forward \
@@ -284,7 +285,7 @@ You can then access the dashboard in your web browser at
[localhost:3000](http:/
#### Pulsar dashboard
-While Grafana and Prometheus are used to provide graphs with historical data,
[Pulsar dashboard](administration-dashboard.md) reports more detailed current
data for individual {% popover topics %}.
+While Grafana and Prometheus are used to provide graphs with historical data,
[Pulsar dashboard](administration-dashboard.md) reports more detailed current
data for individual [topics](reference-terminology.md#topic).
For example, you can have sortable tables showing all namespaces, topics, and
broker stats, with details on the IP address for consumers, how long they've
been connected, and much more.
diff --git a/site2/docs/developing-binary-protocol.md
b/site2/docs/developing-binary-protocol.md
index 1dd6c48534..380e492037 100644
--- a/site2/docs/developing-binary-protocol.md
+++ b/site2/docs/developing-binary-protocol.md
@@ -60,7 +60,7 @@ Message metadata is stored alongside the
application-specified payload as a seri
| `sequence_id` | The sequence ID of the message,
assigned by producer}
|
| `publish_time` | The publish timestamp in Unix time
(i.e. as the number of milliseconds since January 1st, 1970 in UTC)
|
| `properties` | A sequence of key/value pairs (using
the
[`KeyValue`](https://github.com/apache/incubator-pulsar/blob/master/pulsar-common/src/main/proto/PulsarApi.proto#L32)
message). These are application-defined keys and values with no special
meaning to Pulsar. |
-| `replicated_from` *(optional)* | Indicates that the message has been
replicated and specifies the name of the {% popover cluster %} where the
message was originally published
|
+| `replicated_from` *(optional)* | Indicates that the message has been
replicated and specifies the name of the
[cluster](reference-terminology.md#cluster) where the message was originally
published
|
| `partition_key` *(optional)* | While publishing on a partition
topic, if the key is present, the hash of the key is used to determine which
partition to choose
|
| `compression` *(optional)* | Signals that payload has been
compressed and with which compression library
|
| `uncompressed_size` *(optional)* | If compression is used, the producer
must fill the uncompressed size field with the original payload size
|
diff --git a/site2/docs/functions-api.md b/site2/docs/functions-api.md
index f0f4f8c325..b26183797d 100644
--- a/site2/docs/functions-api.md
+++ b/site2/docs/functions-api.md
@@ -103,7 +103,7 @@ Both the [Java](#java-sdk) and [Python](#python-sdk) SDKs
provide access to a **
* The name of the topic on which the message was sent
* The names of all input topics as well as the output topic associated with
the function
* The name of the class used for [SerDe](#serde)
-* The {% popover tenant %} and namespace associated with the function
+* The [tenant](reference-terminology.md#tenant) and namespace associated with
the function
* The ID of the Pulsar Functions instance running the function
* The version of the function
* The [logger object](#logging) used by the function, which can be used to
create function log messages
@@ -518,7 +518,7 @@ Regardless of which [deployment
mode](functions-deploying.md) you're using, you'
* grpcio
* grpcio-tools
-That could be your local machine for [local run
mode](functions-deploying.md#local-run) or a machine running a Pulsar {%
popover broker %} for [cluster mode](functions-deploying.md#cluster-mode). To
install those libraries using pip:
+That could be your local machine for [local run
mode](functions-deploying.md#local-run) or a machine running a Pulsar
[broker](reference-terminology.md#broker) for [cluster
mode](functions-deploying.md#cluster-mode). To install those libraries using
pip:
```bash
$ pip install pulsar-client protobuf futures grpcio grpcio-tools
@@ -577,7 +577,7 @@ Method | What it provides
`record_metric` | Records a per-key [metric](#python-metrics)
`publish` | Publishes a message to the specified Pulsar topic
`get_output_serde_class_name` | The name of the output [SerDe](#python-serde)
class
-`ack` | {% popover Acks %} the message being processed to Pulsar
+`ack` | [Acks](reference-terminology.md#acknowledgment-ack) the message being
processed to Pulsar
### Python SerDe
diff --git a/site2/docs/functions-deploying.md
b/site2/docs/functions-deploying.md
index 82c4228b7c..1bd6d1f5c6 100644
--- a/site2/docs/functions-deploying.md
+++ b/site2/docs/functions-deploying.md
@@ -21,7 +21,7 @@ In order to deploy and manage Pulsar Functions, you need to
have a Pulsar cluste
* You can run a [standalone cluster](getting-started-standalone.md) locally on
your own machine
* You can deploy a Pulsar cluster on [Kubernetes](deploy-kubernetes.md),
[Amazon Web Services](deploy-aws.md), [bare metal](deploy-bare-metal.md),
[DC/OS](deploy-dcos.md), and more
-If you're running a non-{% popover standalone %} cluster, you'll need to
obtain the service URL for the cluster. How you obtain the service URL will
depend on how you deployed your Pulsar cluster.
+If you're running a non-[standalone](reference-terminology.md#standalone)
cluster, you'll need to obtain the service URL for the cluster. How you obtain
the service URL will depend on how you deployed your Pulsar cluster.
## Command-line interface
@@ -76,7 +76,7 @@ $ bin/pulsar-admin functions localrun \
--output persistent://public/default/output-1
```
-By default, the function will connect to a Pulsar cluster running on the same
machine, via a local {% popover broker %} service URL of
`pulsar://localhost:6650`. If you'd like to use local run mode to run a
function but connect it to a non-local Pulsar cluster, you can specify a
different broker URL using the `--brokerServiceUrl` flag. Here's an example:
+By default, the function will connect to a Pulsar cluster running on the same
machine, via a local [broker](reference-terminology.md#broker) service URL of
`pulsar://localhost:6650`. If you'd like to use local run mode to run a
function but connect it to a non-local Pulsar cluster, you can specify a
different broker URL using the `--brokerServiceUrl` flag. Here's an example:
```bash
$ bin/pulsar-admin functions localrun \
@@ -230,7 +230,7 @@ This function has been triggered with a value of hello world
Pulsar supports three different [subscription
types](getting-started-concepts-and-architecture.md#subscription-modes) (or
subscription modes) for Pulsar clients:
-* With [exclusive](getting-started-concepts-and-architecture.md#exclusive)
subscriptions, only a single {% popover consumer %} is allowed to attach to the
subscription.
+* With [exclusive](getting-started-concepts-and-architecture.md#exclusive)
subscriptions, only a single [consumer](reference-terminology.md#consumer) is
allowed to attach to the subscription.
* With [shared](getting-started-concepts-and-architecture.md#shared) . Please
note that strict message ordering is *not* guaranteed with shared subscriptions.
* With [failover](getting-started-concepts-and-architecture.md#failover)
subscriptions
diff --git a/site2/docs/functions-overview.md b/site2/docs/functions-overview.md
index d7c2b505ad..da2591dba4 100644
--- a/site2/docs/functions-overview.md
+++ b/site2/docs/functions-overview.md
@@ -54,7 +54,7 @@ Pulsar Functions could be described as
The core programming model behind Pulsar Functions is very simple:
-* Functions receive messages from one or more **input {% popover topics %}**.
Every time a message is received, the function can do a variety of things:
+* Functions receive messages from one or more **input
[topics](reference-teminology.md#topic)**. Every time a message is received,
the function can do a variety of things:
* Apply some processing logic to the input and write output to:
* An **output topic** in Pulsar
* [Apache BookKeeper](#state-storage)
@@ -268,7 +268,7 @@ The Pulsar Functions feature was built to support a variety
of deployment option
Deployment mode | Description
:---------------|:-----------
[Local run mode](#local-run) | The function runs in your local environment,
for example on your laptop
-[Cluster mode](#cluster-run) | The function runs *inside of* your Pulsar
cluster, on the same machines as your Pulsar popover brokers
+[Cluster mode](#cluster-run) | The function runs *inside of* your Pulsar
cluster, on the same machines as your Pulsar
[brokers](reference-terminology.md#broker)
### Local run mode
diff --git a/site2/docs/functions-quickstart.md
b/site2/docs/functions-quickstart.md
index e8a9c4ddb0..d50ae9c417 100644
--- a/site2/docs/functions-quickstart.md
+++ b/site2/docs/functions-quickstart.md
@@ -4,7 +4,7 @@ title: Getting started with Pulsar Functions
sidebar_label: Getting started
---
-This tutorial will walk you through running a {% popover standalone %} Pulsar
{% popover cluster %} on your machine and then running your first Pulsar
Functions using that cluster. The first function will run in local run mode
(outside your Pulsar {% popover cluster %}), while the second will run in
cluster mode (inside your cluster).
+This tutorial will walk you through running a
[standalone](reference-teminology.md#standalone) Pulsar
[cluster](reference-teminology.md#cluster) on your machine and then running
your first Pulsar Functions using that cluster. The first function will run in
local run mode (outside your Pulsar
[cluster](reference-teminology.md#cluster)), while the second will run in
cluster mode (inside your cluster).
> In local run mode, your Pulsar Function will communicate with your Pulsar
> cluster but will run outside of the cluster.
@@ -14,7 +14,7 @@ In order to follow along with this tutorial, you'll need to
have [Maven](https:/
## Run a standalone Pulsar cluster
-In order to run our Pulsar Functions, we'll need to run a Pulsar cluster
locally first. The easiest way to do that is to run Pulsar in {% popover
standalone %} mode. Follow these steps to start up a standalone cluster:
+In order to run our Pulsar Functions, we'll need to run a Pulsar cluster
locally first. The easiest way to do that is to run Pulsar in
[standalone](reference-teminology.md#standalone) mode. Follow these steps to
start up a standalone cluster:
```bash
$ wget
https://repository.apache.org/content/repositories/snapshots/org/apache/pulsar/distribution/2.0.0-incubating-SNAPSHOT/distribution-2.0.0-incubating-{{
site.preview_version_id }}-bin.tar.gz
diff --git a/site2/docs/getting-started-concepts-and-architecture.md
b/site2/docs/getting-started-concepts-and-architecture.md
index 14eb69f16d..ec99f27c32 100644
--- a/site2/docs/getting-started-concepts-and-architecture.md
+++ b/site2/docs/getting-started-concepts-and-architecture.md
@@ -40,7 +40,7 @@ Once a subscription has been created, all messages will be
[retained](#persisten
### Producers
-A producer is a process that attaches to a topic and publishes messages to a
Pulsar {% popover broker %} for processing.
+A producer is a process that attaches to a topic and publishes messages to a
Pulsar [broker](reference-terminology.md#broker) for processing.
#### Send modes
@@ -68,7 +68,7 @@ A consumer is a process that attaches to a topic via a
subscription and then rec
#### Receive modes
-Messages can be received from {% popover brokers %} either synchronously
(sync) or asynchronously (async).
+Messages can be received from [brokers](reference-terminology.md#broker)
either synchronously (sync) or asynchronously (async).
| Mode | Description
|
|:--------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -90,7 +90,7 @@ Client libraries can provide their own listener
implementations for consumers. T
### Topics
-As in other pub-sub systems, topics in Pulsar are named channels for
transmitting messages from {% popover producers %} to {% popover consumers %}.
Topic names are URLs that have a well-defined structure:
+As in other pub-sub systems, topics in Pulsar are named channels for
transmitting messages from [producers](reference-terminology.md#producer) to
[consumers](reference-terminology.md#consumer). Topic names are URLs that have
a well-defined structure:
```http
{persistent|non-persistent}://tenant/namespace/topic
@@ -334,7 +334,7 @@ Pulsar uses a system called [Apache
BookKeeper](http://bookkeeper.apache.org/) f
* It's horizontally scalable in both capacity and throughput. Capacity can be
immediately increased by adding more bookies to a cluster.
* Bookies are designed to handle thousands of ledgers with concurrent reads
and writes. By using multiple disk devices---one for journal and another for
general storage--bookies are able to isolate the effects of read operations
from the latency of ongoing write operations.
-In addition to message data, *cursors* are also persistently stored in
BookKeeper. Cursors are {% popover subscription %} positions for {% popover
consumers %}. BookKeeper enables Pulsar to store consumer position in a
scalable fashion.
+In addition to message data, *cursors* are also persistently stored in
BookKeeper. Cursors are [subscription](reference-terminology.md#subscription)
positions for [consumers](reference-terminology.md#consumer). BookKeeper
enables Pulsar to store consumer position in a scalable fashion.
At the moment, Pulsar only supports persistent message storage. This accounts
for the `persistent` in all topic names. Here's an example:
@@ -419,7 +419,7 @@ In the second scenario at the bottom, the producer
publishes message 1, which is
### Producer idempotency
-The other available approach to message deduplication is to ensure that each
message is *only produced once*. This approach is typically called **producer
idempotency**. The drawback of this approach is that it defers the work of
message deduplication to the application. In Pulsar, this is handled at the {%
popover broker %} level, which means that you don't need to modify your Pulsar
client code. Instead, you only need to make administrative changes (see the
[Managing message deduplication](cookbooks-deduplication.md) cookbook for a
guide).
+The other available approach to message deduplication is to ensure that each
message is *only produced once*. This approach is typically called **producer
idempotency**. The drawback of this approach is that it defers the work of
message deduplication to the application. In Pulsar, this is handled at the
[broker](reference-terminology.md#broker) level, which means that you don't
need to modify your Pulsar client code. Instead, you only need to make
administrative changes (see the [Managing message
deduplication](cookbooks-deduplication.md) cookbook for a guide).
### Deduplication and effectively-once semantics
@@ -445,7 +445,7 @@ As you can see, the tenant is the most basic unit of
categorization for topics (
To each tenant in a Pulsar instance you can assign:
* An [authorization](security-authorization.md) scheme
-* The set of {% popover clusters %} to which the tenant's configuration applies
+* The set of [clusters](reference-terminology.md#cluster) to which the
tenant's configuration applies
### Namespaces
@@ -533,7 +533,7 @@ client = Client('pulsar://pulsar-cluster.acme.com:6650')
## Reader interface
-In Pulsar, the "standard" [consumer interface](#consumers) involves using
consumers to listen on {% popover topics %}, process incoming messages, and
finally acknowledge those messages when they've been processed. Whenever a
consumer connects to a topic, it automatically begins reading from the earliest
un-acked message onward because the topic's cursor is automatically managed by
Pulsar.
+In Pulsar, the "standard" [consumer interface](#consumers) involves using
consumers to listen on [topics](reference-terminology.md#topic), process
incoming messages, and finally acknowledge those messages when they've been
processed. Whenever a consumer connects to a topic, it automatically begins
reading from the earliest un-acked message onward because the topic's cursor is
automatically managed by Pulsar.
The **reader interface** for Pulsar enables applications to manually manage
cursors. When you use a reader to connect to a topic---rather than a
consumer---you need to specify *which* message the reader begins reading from
when it connects to a topic. When connecting to a topic, the reader interface
enables you to begin with:
@@ -613,7 +613,7 @@ When topic compaction is triggered [via the
CLI](cookbooks-compaction.md), Pulsa
After that, the broker will create a new [BookKeeper ledger](#ledgers) and
make a second iteration through each message on the topic. For each message, if
the key matches the latest occurrence of that key, then the key's data payload,
message ID, and metadata will be written to the newly created ledger. If the
key doesn't match the latest then the message will be skipped and left alone.
If any given message has an empty payload, it will be skipped and considered
deleted (akin to the concept of
[tombstones](https://en.wikipedia.org/wiki/Tombstone_(data_store)) in key-value
databases). At the end of this second iteration through the topic, the newly
created BookKeeper ledger is closed and two things are written to the topic's
metadata: the ID of the BookKeeper ledger and the message ID of the last
compacted message (this is known as the **compaction horizon** of the topic).
Once this metadata is written compaction is complete.
-After the initial compaction operation, the Pulsar {% popover broker %} that
owns the topic is notified whenever any future changes are made to the
compaction horizon and compacted backlog. When such changes occur:
+After the initial compaction operation, the Pulsar
[broker](reference-terminology.md#broker) that owns the topic is notified
whenever any future changes are made to the compaction horizon and compacted
backlog. When such changes occur:
* Clients (consumers and readers) that have read compacted enabled will
attempt to read messages from a topic and either:
* Read from the topic like normal (if the message ID is greater than or
equal to the compaction horizon) or
diff --git a/site2/docs/reference-terminology.md
b/site2/docs/reference-terminology.md
new file mode 100644
index 0000000000..d236b36aa6
--- /dev/null
+++ b/site2/docs/reference-terminology.md
@@ -0,0 +1,161 @@
+---
+id: reference-terminology
+title: Pulsar Terminology
+sidebar_label: Terminology
+---
+
+Here is a glossary of terms related to Apache Pulsar:
+
+### Concepts
+
+#### Pulsar
+
+Pulsar is a distributed messaging system originally created by Yahoo but now
under the stewardship of the Apache Software Foundation.
+
+#### Message
+
+Messages are the basic unit of Pulsar. They're what [producers](#producer)
publish to [topics](#topic)
+and what [consumers](#consumer) then consume from topics.
+
+#### Topic
+
+A named channel used to pass messages published by [producers](#producer) to
[consumers](#consumer) who
+process those [messages](#message).
+
+#### Partitioned Topic
+
+A topic that is served by multiple Pulsar [brokers](#broker), which enables
higher throughput.
+
+#### Namespace
+
+A grouping mechanism for related [topics](#topic).
+
+#### Namespace Bundle
+
+A virtual group of [topics](#topic) that belong to the same
[namespace](#namespace). A namespace bundle
+is defined as a range between two 32-bit hashes, such as 0x00000000 and
0xffffffff.
+
+#### Tenant
+
+An administrative unit for allocating capacity and enforcing an
authentication/authorization scheme.
+
+#### Subscription
+
+A lease on a [topic](#topic) established by a group of [consumers](#consumer).
Pulsar has three subscription
+modes (exclusive, shared, and failover).
+
+#### Pub-Sub
+
+A messaging pattern in which [producer](#producer) proccesses publish messages
on [topics](#topic) that
+are then consumed (processed) by [consumer](#consumer) processes.
+
+#### Producer
+
+A process that publishes [messages](#message) to a Pulsar [topic](#topic).
+
+#### Consumer
+
+A process that establishes a subscription to a Pulsar [topic](#topic) and
processes messages published
+to that topic by [producers](#producer).
+
+#### Reader
+
+Pulsar readers are message processors much like Pulsar [consumers](#consumer)
but with two crucial differences:
+
+- you can specify *where* on a topic readers begin processing messages
(consumers always begin with the latest
+ available unacked message);
+- readers don't retain data or acknowledge messages.
+
+#### Cursor
+
+The subscription position for a [consumer](#consumer).
+
+#### Acknowledgment (ack)
+
+A message sent to a Pulsar broker by a [consumer](#consumer) that a message
has been successfully processed.
+An acknowledgement (ack) is Pulsar's way of knowing that the message can be
deleted from the system;
+if no acknowledgement, then the message will be retained until it's processed.
+
+#### Unacknowledged
+
+A message that has been delivered to a consumer for processing but not yet
confirmed as processed by the consumer.
+
+#### Retention Policy
+
+Size and/or time limits that you can set on a [namespace](#namespace) to
configure retention of [messages](#message)
+that have already been [acknowledged](#acknowledgement-ack).
+
+#### Multi-Tenancy
+
+The ability to isolate [namespaces](#namespace), specify quotas, and configure
authentication and authorization
+on a per-[tenant](#tenant) basis.
+
+### Architecture
+
+#### Standalone
+
+A lightweight Pulsar broker in which all components run in a single Java
Virtual Machine (JVM) process. Standalone
+clusters can be run on a single machine and are useful for development
purposes.
+
+#### Cluster
+
+A set of Pulsar [brokers](#broker) and [BookKeeper](#bookkeeper) servers (aka
[bookies](#bookie)).
+Clusters can reside in different geographical regions and replicate messages
to one another
+in a process called [geo-replication](#geo-replication).
+
+#### Instance
+
+A group of Pulsar [clusters](#cluster) that act together as a single unit.
+
+#### Geo-Replication
+
+Replication of messages across Pulsar [clusters](#cluster), potentially in
different datacenters
+or geographical regions.
+
+#### Configuration Store
+
+Pulsar's configuration store (previously known as global ZooKeeper) is a
ZooKeeper quorum that
+is used for configuration-specific tasks. A multi-cluster Pulsar installation
requires just one
+configuration store across all [clusters](#cluster).
+
+#### Topic Lookup
+
+A service provided by Pulsar [brokers](#broker) that enables connecting
clients to automatically determine
+which Pulsar [cluster](#cluster) is responsible for a [topic](#topic) (and
thus where message traffic for
+the topic needs to be routed).
+
+#### Service Discovery
+
+A mechanism provided by Pulsar that enables connecting clients to use just a
single URL to interact
+with all the [brokers](#broker) in a [cluster](#cluster).
+
+#### Broker
+
+A stateless component of Pulsar [clusters](#cluster) that runs two other
components: an HTTP server
+exposing a REST interface for administration and topic lookup and a
[dispatcher](#dispatcher) that
+handles all message transfers. Pulsar clusters typically consist of multiple
brokers.
+
+#### Dispatcher
+
+An asynchronous TCP server used for all data transfers in-and-out a Pulsar
[broker](#broker). The Pulsar
+dispatcher uses a custom binary protocol for all communications.
+
+### Storage
+
+#### BookKeeper
+
+[Apache BookKeeper](http://bookkeeper.apache.org/) is a scalable, low-latency
persistent log storage
+service that Pulsar uses to store data.
+
+#### Bookie
+
+Bookie is the name of an individual BookKeeper server. It is effectively the
storage server of Pulsar.
+
+#### Ledger
+
+An append-only data structure in [BookKeeper](#bookkeeper) that is used to
persistently store messages in Pulsar [topics](#topic).
+
+### Functions
+
+Pulsar Functions are lightweight functions that can consume messages from
Pulsar topics, apply custom processing logic, and, if desired, publish results
to topics.
+
diff --git a/site2/docs/security-athenz.md b/site2/docs/security-athenz.md
index 27b84a31f7..3b881b2948 100644
--- a/site2/docs/security-athenz.md
+++ b/site2/docs/security-athenz.md
@@ -10,17 +10,17 @@ sidebar_label: Authentication using Athenz
In a [decentralized Athenz
system](https://github.com/yahoo/athenz/blob/master/docs/dev_decentralized_access.md)
there is both an [authori**Z**ation **M**anagement
**S**ystem](https://github.com/yahoo/athenz/blob/master/docs/setup_zms.md)
(ZMS) server and an [authori**Z**ation **T**oken
**S**ystem](https://github.com/yahoo/athenz/blob/master/docs/setup_zts.md)
(ZTS) server.
-To begin, you need to set up Athenz service access control. You should create
domains for the *provider* (which provides some resources to other services
with some authentication/authorization policies) and the *tenant* (which is
provisioned to access some resources in a provider). In this case, the provider
corresponds to the Pulsar service itself and the tenant corresponds to each
application using Pulsar (typically, a {% popover property %} in Pulsar).
+To begin, you need to set up Athenz service access control. You should create
domains for the *provider* (which provides some resources to other services
with some authentication/authorization policies) and the *tenant* (which is
provisioned to access some resources in a provider). In this case, the provider
corresponds to the Pulsar service itself and the tenant corresponds to each
application using Pulsar (typically, a
[tenant](reference-terminology.md#tenant) in Pulsar).
### Create the tenant domain and service
-On the {% popover tenant %} side, you need to:
+On the [tenant](reference-terminology.md#tenant) side, you need to:
1. Create a domain, such as `shopping`
2. Generate a private/public key pair
3. Create a service, such as `some_app`, on the domain with the public key
-Note that the private key generated in step 2 needs to be specified when the
Pulsar client connects to the {% popover broker %} (see client configuration
examples for [Java](client-libraries-java.md#tls-authentication) and
[C++](client-libraries-cpp.md#tls-authentication)).
+Note that the private key generated in step 2 needs to be specified when the
Pulsar client connects to the [broker](reference-terminology.md#broker) (see
client configuration examples for
[Java](client-libraries-java.md#tls-authentication) and
[C++](client-libraries-cpp.md#tls-authentication)).
For more specific steps involving the Athenz UI, please refer to [this
doc](https://github.com/yahoo/athenz/blob/master/docs/example_service_athenz_setup.md#client-tenant-domain).
diff --git a/site2/docs/security-authorization.md
b/site2/docs/security-authorization.md
index 8fa50a912f..433f35051f 100644
--- a/site2/docs/security-authorization.md
+++ b/site2/docs/security-authorization.md
@@ -7,7 +7,7 @@ sidebar_label: Authorization and ACLs
In Pulsar, the [authentication
provider](security-overview.md#authentication-providers) is charged with
properly identifying clients and
associating them with [role tokens](security-overview.md#role-tokens).
*Authorization* is the process that determines *what* clients are able to do.
-Authorization in Pulsar is managed at the {% popover tenant %} level, which
means that you can have multiple authorization schemes active
+Authorization in Pulsar is managed at the
[tenant](reference-terminology.md#tenant) level, which means that you can have
multiple authorization schemes active
in a single Pulsar instance. You could, for example, create a `shopping`
tenant that has one set of [roles](security-overview.md#role-tokens)
and applies to a shopping application used by your company, while an
`inventory` tenant would be used only by an inventory application.
@@ -16,7 +16,7 @@ and applies to a shopping application used by your company,
while an `inventory`
## Creating a new tenant
-A Pulsar {% popover tenant %} is typically provisioned by Pulsar {% popover
instance %} administrators or by some kind of self-service portal.
+A Pulsar [tenant](reference-terminology.md#tenant) is typically provisioned by
Pulsar [instance](reference-terminology.md#instance) administrators or by some
kind of self-service portal.
Tenants are managed using the [`pulsar-admin`](reference-pulsar-admin.md)
tool. Here's an example tenant creation command:
diff --git a/site2/docs/security-tls.md b/site2/docs/security-tls.md
index fb197f63ec..190b5c8f06 100644
--- a/site2/docs/security-tls.md
+++ b/site2/docs/security-tls.md
@@ -88,7 +88,7 @@ For the client common name, you need to use a string that you
intend to use as t
## Configure the broker for TLS
-To configure a Pulsar {% popover broker %} to use TLS authentication, you'll
need to make some changes to the `broker.conf` configuration file, which is
located in the `conf` directory of your [Pulsar
installation](getting-started-standalone.md).
+To configure a Pulsar [broker](reference-terminology.md#broker) to use TLS
authentication, you'll need to make some changes to the `broker.conf`
configuration file, which is located in the `conf` directory of your [Pulsar
installation](getting-started-standalone.md).
Add these values to the configuration file (substituting the appropriate
certificate paths where necessary):
@@ -110,7 +110,7 @@
authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationPr
## Configure the discovery service
-The {% popover discovery %} service used by Pulsar brokers needs to redirect
all HTTPS requests, which means that it needs to be trusted by the client as
well. Add this configuration in `conf/discovery.conf` in your Pulsar
installation:
+The [discovery service](reference-terminology.md#service-discovery) used by
Pulsar brokers needs to redirect all HTTPS requests, which means that it needs
to be trusted by the client as well. Add this configuration in
`conf/discovery.conf` in your Pulsar installation:
```properties
tlsEnabled=true
diff --git a/site2/website/sidebars.json b/site2/website/sidebars.json
index 0dffa73388..660df1c523 100644
--- a/site2/website/sidebars.json
+++ b/site2/website/sidebars.json
@@ -83,6 +83,7 @@
"develop-cpp"
],
"Reference": [
+ "reference-terminology",
"reference-rest-api",
"reference-cli-tools",
"pulsar-admin",
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
With regards,
Apache Git Services
