Deploying a multi-cluster on bare metal

提示

1. 除了最极端的情况，对于绝大多数的用例来说，单机群安装的Pulsar就能够满足要求了。 如果是创业公司或单个团队想体验下Pulsar，我们推荐使用单集群。 有关单群集的部署说明，请参阅此处。

2. 如果要在部署的 Pulsar 集群中使用所有内置的 Pulsar IO连接器。你必须先下载apache-pulsar-io-connectors安装包，然后将apache-pulsar-io-connectors安装到每台 broker 中 Pulsar 安装路径的connectors目录下。如果需要用独立的 function worker 运行Pulsar Functions，则也需要将包安装在 worker 节点的对应目录。

3. 如果要在部署的集群使用分层存储特性，你必须先下载apache-pulsar-offloaders安装包，然后将apache-pulsar-offloaders安装到每台 broker 中 Pulsar 安装路径的offloaders </1>目录下。 了解该特性的详细配置，请参考分层存储指南。

A Pulsar instance consists of multiple Pulsar clusters working in unison. 你可以跨数据中心或者跨地域部署集群，可以使用跨域复制功能在集群间复制数据。 部署群的Pulsar 实例需要包含多集以下基本步骤：

• 部署两个独立的Zookeeper集群；实例中每个集群都要有一个本地集群；一个负责实例范围任务信息存储的配置存储集群。
• 初始化每个集群的集群元数据。
• 在每个Pulsar 集群部署一个Bookeeper 集群。
• 在每个Pulsar 集群部署broker。

如果你想部署单个Pulsar 集群的实例，请看集群和broker。

本地或者 Kubernetes 运行Pulsar？

本指南向您展示了如何在非Kubernetes中部署生产环境的 Pulsar 集群。 如果你想在单台机器部署单机的 Pulsar 集群，可以参考本地集群部署指南。 如果你想在Kubernetes运行 Pulsar，可以参考 Kubernetes 部署 Pulsar 指南，指南包含了如何在 Google Kubernetes Engine 和 Amazon Web Services 的 Kubernetes 环境运行Pulsar。

系统配置要求

Currently, Pulsar is available for 64-bit *macOS, Linux, and Windows. To use Pulsar, you need to install 64-bit JRE/JDK 8 or later versions.

Note

Broker is only supported on 64-bit JVM.

安装Pulsar

开始运行Pulsar之前，请先用下列几种方式下载二进制包:

• 通过单击下面的链接并从 Apache 镜像下载该版本:

  • Pulsar 2.8.0 binary release

• Pulsar 下载页面

• Pulsar 发布页面

• 使用 wget：

  $ wget 'https://www.apache.org/dyn/mirrors/mirrors.cgi?action=download&filename=pulsar/pulsar-2.8.0/apache-pulsar-2.8.0-bin.tar.gz' -O apache-pulsar-2.8.0-bin.tar.gz

包下载完成后，解压并进入到解压后的目录:

$ tar xvfz apache-pulsar-2.8.0-bin.tar.gz
$ cd apache-pulsar-2.8.0

软件包包含的内容:

Pulsar 二进制包包含下列目录:

运行 Pulsar 会立即生成以下目录。

Deploy ZooKeeper

每个 Pulsar 实例需要两个独立的 ZooKeeper 集群。

• 本地集群负责集群级别的操作，提供集群的配置管理和协调。 每个 Pulsar 集群都需要一个专用的 ZooKeeper 集群。
• 配置集群负责实例级别的操作，提供整个系统的配置管理(跨集群)。 配置集群可以部署在独立的机器集群，也可以和本地 Zookeeper 集群部署在同一批机器。

The configuration store quorum can be provided by an independent cluster of machines or by the same machines used by local ZooKeeper.

部署本地Zookeeper

ZooKeeper 负责管理与 Pulsar 协调和配置相关的各种基本任务。

You need to stand up one local ZooKeeper cluster per Pulsar cluster for deploying a Pulsar instance.

首先，将所有 ZooKeeper 服务器添加到 conf/zookeeper.conf 指定的 quorum 配置中。 在配置文件中为每个集群节点添加一个 server.N 行，其中 N 是 ZooKeeper 节点的编号。 以下是一个三节点集群的示例：

server.1=zk1.us-west.example.com:2888:3888
server.2=zk2.us-west.example.com:2888:3888
server.3=zk3.us-west.example.com:2888:3888

你必须在每个节点的myid文件里面，为集群配置唯一的ID。默认情况下，这个文件在每台机器的data/zookeeper目录里面(你可以通过修改dataDir配置项修改这个路径)。

参考多集群安装指南的Zookeeper 文档了解更多关于myid或者其他部分的详细信息。

On a ZooKeeper server at zk1.us-west.example.com, for example, you could set the myid value like this:

$ mkdir -p data/zookeeper
$ echo 1 > data/zookeeper/myid

在 zk2.us-west.example.com 服务器上，这命令可以是：echo 2>data/zookeeper/myid。

一旦你在每台机器增加了zookeeper.conf配置文件，并且设置了myid，你能够在所有机器上使用pulsar-daemon命令去启动Zookeeper 服务(前台运行或者后台运行)。

$ bin/pulsar-daemon start zookeeper

部署配置存储集群

The ZooKeeper cluster that is configured and started up in the section above is a local ZooKeeper cluster that you can use to manage a single Pulsar cluster. 但是，除了本地集群之外，一个完整的 Pulsar 实例还需要 configuration store来处理一些实例级配置和协调任务。

如果是部署一个单集群实例，你不需要另外部署存储配置的 Zookeeper 集群。 然而，如果你是部署多集群的实例，你必须单独部署 Zookeeper 集群来存储配置任务信息。

单集群 Pulsar 实例

如果你的 Pulsar 实例只包含一个集群，你可以在同一批机器上部署本地 Zookeeper 集群和配置存储 Zookeeper 集群，此时这两个集群的 TCP 端口信息需要不一样。

要在单个集群实例中部署配置存储的 Zookeeper 集群。步骤跟部署本地 Zookeeper一样，将同一批机器(跟本地集群一样的机器列表)信息添加到配置文件conf/global_zookeeper.conf中，但是必须确保使用不同的端口(Zookeeper 默认使用2181端口)。 以下是一个使用 2184 端口的三节点ZooKeeper 集群的示例：

clientPort=2184
server.1=zk1.us-west.example.com:2185:2186
server.2=zk2.us-west.example.com:2185:2186
server.3=zk3.us-west.example.com:2185:2186

跟之前一样，在 data/global-zoocheper/myid 文件为每个服务器创建 myid 。

多集群 Pulsar 实例

当你部署一个全球性的Pulsar实例时，集群分布在不同的地理区域。配置存储必须是一个高可用和强一致的元数据存储服务，必须能够容忍整个区域的故障和分区。

这里的关键是确保 ZK 成员投票节点必须分布在3个区域，其他区域以观察员身份运行。

强调一下，因为配置存储服务负载会很低，所以可以和本地 Zookeeper 集群部署在同一批主机上。

例如，假设一个 Pulsar 实例有如下集群： us-west,us-east,us-central,eu-central,ap-south. 也假定每个群集都有自己的本地ZK服务器，其名称如下：

zk[1-3].${CLUSTER}.example.com

在这种情况下，可以从几个集群中选择投票节点，让其他所有节点成为 ZK 观察者节点。 例如，要形成7个服务器组成的投票节点，您可以从 us-west中挑选3个服务器，从 us-central 和us-east分别挑选两个。

这个方法保证即使其中一个区域无法连接，数据也可以写入配置存储服务。

所有服务器中的 ZK 配置如下：

clientPort=2184
server.1=zk1.us-west.example.com:2185:2186
server.2=zk2.us-west.example.com:2185:2186
server.3=zk3.us-west.example.com:2185:2186
server.4=zk1.us-central.example.com:2185:2186
server.5=zk2.us-central.example.com:2185:2186
server.6=zk3.us-central.example.com:2185:2186:observer
server.7=zk1.us-east.example.com:2185:2186
server.8=zk2.us-east.example.com:2185:2186
server.9=zk3.us-east.example.com:2185:2186:observer
server.10=zk1.eu-central.example.com:2185:2186:observer
server.11=zk2.eu-central.example.com:2185:2186:observer
server.12=zk3.eu-central.example.com:2185:2186:observer
server.13=zk1.ap-south.example.com:2185:2186:observer
server.14=zk2.ap-south.example.com:2185:2186:observer
server.15=zk3.ap-south.example.com:2185:2186:observer

此外，ZK 观察者节点需要配置以下参数：

peerType=observer

启动服务

配置存储服务配置完成后，你可以通过pulsar-daemon来启动集群。

$ bin/pulsar-daemon start configuration-store

初始化集群元数据

一旦实例的每个 Pulsar 集群的本地 Zookeeper 集群和全局的配置存储 Zookeeper 集群都部署完成， 你需要在实例中为每个集群写入一些元数据。 you only needs to write these metadata once.

You can initialize this metadata using the initialize-cluster-metadata command of the pulsar CLI tool. 如下所示：

$ bin/pulsar initialize-cluster-metadata \
  --cluster us-west \
  --zookeeper zk1.us-west.example.com:2181 \
  --configuration-store zk1.us-west.example.com:2184 \
  --web-service-url http://pulsar.us-west.example.com:8080/ \
  --web-service-url-tls https://pulsar.us-west.example.com:8443/ \
  --broker-service-url pulsar://pulsar.us-west.example.com:6650/ \
  --broker-service-url-tls pulsar+ssl://pulsar.us-west.example.com:6651/

从上面的示例中可以看出，您需要指定以下内容：

• 集群名称
• 集群与本地 ZooKeeper 连接的字符串
• 整个集群实例的配置存储连接字符串。
• 集群 web 服务的 URL
• Broker 服务的 URL，用于启动集群中 broker 之间的交互

如果使用TLS，你必须为集群指定一个 TLS web 服务URL，以及用于集群中 broker TLS 服务的URL。

Make sure to run initialize-cluster-metadata for each cluster in your instance.

部署 Bookkeeper

BookKeeper provides persistent message storage for Pulsar.

Each Pulsar broker needs to have its own cluster of bookies. The BookKeeper cluster shares a local ZooKeeper quorum with the Pulsar cluster.

配置 bookies

你能够通过配置文件conf/bookkeeper.conf去配置 BookKeeper bookies。 配置 bookies 最重要的一步，是要确保zkServers设置为 Pulsar 集群的的本地 Zookeeper 集群的连接信息。

启动 bookie。

您可以通过两种方式启动 bookie ：前台或后台

To start a bookie in the background, use the pulsar-daemon CLI tool:

$ bin/pulsar-daemon start bookie

你可以通过运行BookKeeper shell上的bookiesanity命令验证 bookie 是否正常工作：

$ bin/bookkeeper shell bookiesanity

这个命令会在本地的 bookie 创建一个临时的 BookKeeper ledger，往里面写一些条目，然后读取它，最后删除这个 ledger。

启动了所有的 bookie 后，你能够在任意一台bookie上，使用BookKeeper shell的simpletest命令，去校验集群内所有的 bookie 是否都已经启动。

$ bin/bookkeeper shell simpletest --ensemble <num-bookies> --writeQuorum <num-bookies> --ackQuorum <num-bookies> --numEntries <num-entries>

Bookie hosts are responsible for storing message data on disk. 为了使 bookies 能有更好的性能，必须选择合适的硬件配置。 以下是 bookie 硬件配置的关键指标。

• 硬盘 I/O 的读/写能力。
• 存储容量

Message entries written to bookies are always synced to disk before returning an acknowledgement to the Pulsar broker. To ensure low write latency, BookKeeper is designed to use multiple devices:

• A journal to ensure durability. 对于连续写入来说 ，在 bookie 机器上必须有快速的fsync操作， 通常，小而快速的固态硬盘(SSDs)就足够，或者带有RAID控制器和电池支持写入缓存的硬盘驱动器(HDDs)。 这两种方案 fsync 延时大约为0.4ms。
• A ledger storage device is where data is stored until all consumers acknowledge the message. 写入操作是在后台运行的，所以写入的 I/O 性能不是一个大问题。 大部分的读取操作是连续的。backlog 只有在没有消费者的情况下，才会被删除。 要存储大量的数据，典型的配置是多块 HDD 硬盘和 一个RAID 控制器构建硬盘阵列。

部署 broker

一旦部署了 Zookeeper，初始化了集群元数据，部署了 Bookeeper bookies 后，你就能开始部署 broker了。

Broker configuration

你能够通过conf/broker.conf配置文件配置broker。

The most important element of broker configuration is ensuring that each broker is aware of its local ZooKeeper quorum as well as the configuration store quorum. 必须确保zookeeperServers设置为本地 zookeeper 集群的地址，确保configurationStoreServers设置为配置存储集群的地址(即使配置存储集群和本地的 Zookeeper 集群是同一个，也需要配置该选项)。

You also need to specify the name of the cluster to which the broker belongs using the clusterName parameter. 此外，broker 和 web 服务的端口必须和初始化集群元数据时指定的端口是一样的(特别是当你使用了和默认值不同的端口的时候)。

下面是一个示例配置：

# Local ZooKeeper servers
zookeeperServers=zk1.us-west.example.com:2181,zk2.us-west.example.com:2181,zk3.us-west.example.com:2181
# Configuration store quorum connection string.
configurationStoreServers=zk1.us-west.example.com:2184,zk2.us-west.example.com:2184,zk3.us-west.example.com:2184
clusterName=us-west
# Broker data port
brokerServicePort=6650
# Broker data port for TLS
brokerServicePortTls=6651
# Port to use to server HTTP request
webServicePort=8080
# Port to use to server HTTPS request
webServicePortTls=8443

Broker hardware

Pulsar broker 不需要使用特殊的硬件，因为他们不使用本地硬盘。 你最好选择快速的 CPU 和 10Gbps 的 网卡 ，以便能够充分利用软件的性能。

启动 broker

你能够通过使用nohup或者pulsar-daemonCLI 工具在后台启动 broker。

$ bin/pulsar-daemon start broker

你可以使用 pulsar broker在前台启动 broker。

$ bin/pulsar broker

服务发现

客户端 需要能够使用单个 URL 与整个 Pulsar 实例进行通信。 Pulsar provides a built-in service discovery mechanism that you can set up using the instructions immediately below.

你可以使用你自己的服务发现系统。 If you use your own system, you only need to satisfy just one requirement: when a client performs an HTTP request to an endpoint for a Pulsar cluster, such as http://pulsar.us-west.example.com:8080, the client needs to be redirected to some active broker in the desired cluster, whether via DNS, an HTTP or IP redirect, or some other means.

Service discovery already provided by many scheduling systems

Many large-scale deployment systems, such as Kubernetes, have service discovery systems built in. 如果你在这样的系统上运行 Pulsar，你可能不需要自己构建服务发现系统。

Service discovery setup

Pulsar 自带的服务发现策略维护了一个活跃 broker 的列表，该列表保存在Zookeeper中，并支持通过 HTTP 和二进制协议去查询。

若需要启用 Pulsar 内置的服务发现系统，你必须修改配置文件conf/discovery.conf里面的一些参数。 通过配置项zookeeperServers配置本地 Zookeeper 集群的连接字符串，通过configurationStoreServers配置配置存储集群的连接信息。

# Zookeeper quorum connection string
zookeeperServers=zk1.us-west.example.com:2181,zk2.us-west.example.com:2181,zk3.us-west.example.com:2181
# Global configuration store connection string
configurationStoreServers=zk1.us-west.example.com:2184,zk2.us-west.example.com:2184,zk3.us-west.example.com:2184

To start the discovery service:

$ bin/pulsar-daemon start discovery

Admin 客户端和验证

At this point your Pulsar instance should be ready to use. You can now configure client machines that can serve as administrative clients for each cluster. You can use the conf/client.conf configuration file to configure admin clients.

The most important thing is that you point the serviceUrl parameter to the correct service URL for the cluster:

serviceUrl=http://pulsar.us-west.example.com:8080/

创建新租户

Pulsar 是一个内置多租户功能的系统。

If a new tenant wants to use the system, you need to create a new one. You can create a new tenant by using the pulsar-admin CLI tool:

$ bin/pulsar-admin tenants create test-tenant \
  --allowed-clusters us-west \
  --admin-roles test-admin-role

在这个命令中，使用test-admin-role角色的用户可以管理租户test-tenant的配置。 租户test-tenant只能在集群us-west内使用。 从现在起，这个租户能够管理其他的资源了。

一旦你创建了一个租户，你必须为该租户的主题创建命名空间

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.

$ bin/pulsar-admin namespaces create test-tenant/ns1

测试生产和消费

Everything is now ready to send and receive messages. The quickest way to test the system is through the pulsar-perf client tool.

You can use a topic in the namespace that you have just created. Topics are automatically created the first time when a producer or a consumer tries to use them.

The topic name in this case could be:

persistent://test-tenant/ns1/my-topic

开始创建主题订阅并等待消息的消费者：

$ bin/pulsar-perf consume persistent://test-tenant/ns1/my-topic

创建一个以固定速度发布消息的生产者，并每10秒报告统计数据：

$ bin/pulsar-perf produce persistent://test-tenant/ns1/my-topic

To report the topic stats:

$ bin/pulsar-admin topics stats persistent://test-tenant/ns1/my-topic