Apache Pulsar 集群管理实战：使用 pulsar-admin、REST API 与 Java Admin API 管理 Clusters

消息队列后端流处理【免费下载链接】pulsarApache Pulsar - distributed pub-sub messaging system项目地址https://gitcode.com/gh_mirrors/pulsar28/pulsar点击查看免费下载本篇技术指南以 Apache Pulsar 官方文档 admin-api-clusters.md 为核心骨架系统讲解 Pulsar 集群Cluster的完整生命周期管理从创建集群Provision、初始化集群元数据到获取配置、更新、删除、列出集群以及配置对等集群peer-clusters。读完本文你将掌握pulsar-adminCLI、/admin/v2/clustersREST API 与 Java Admin API 三种管理方式的具体用法、核心参数含义以及底层 broker 源码中这些操作的真实实现路径。Pulsar 集群的构成与管理入口一个 Pulsar 集群Cluster由三部分组成一个或多个 Pulsarbroker负责消息路由与读写服务一个或多个BookKeeper服务器又称bookie负责消息的持久化存储一个ZooKeeper集群负责提供配置管理与协调管理。在 Pulsar 的层级体系中一个instance实例可以包含多个 cluster因此集群是命名空间namespace、租户tenant之上的重要逻辑边界也是多租户与跨地域复制geo-replication的基础单元。相关术语可参考 reference-terminology.md。集群可以通过以下三种途径进行管理管理方式入口说明命令行工具pulsar-admin clusters子命令最常用见 reference-pulsar-admin.mdREST API/admin/v2/clusters端点供脚本、HTTP 客户端调用Java APIPulsarAdmin对象上的clusters()方法供 Java 应用内嵌调用从源码看REST 端点由 v2/Clusters.java 暴露声明为Path(/clusters)真正的业务逻辑全部实现在其父类 impl/ClustersBase.java 中Java Admin API 客户端侧的实现位于 internal/ClustersImpl.java。三条路径最终都指向同一套服务端逻辑。Provision创建预置新集群使用 pulsar-admin 创建集群通过pulsar-admin的clusters create子命令即可预置一个新集群$ pulsar-admin clusters create cluster-1 \ --url http://my-cluster.org.com:8080 \ --broker-url pulsar://my-cluster.org.com:6650注意该操作需要superuser 超级用户权限。clusters create的完整可用参数来源reference-pulsar-admin.md 中clusters create小节Flag描述--broker-urlbroker 服务Pulsar 二进制协议的 URL默认端口 6650--broker-url-secure用于安全连接TLS的 broker 服务 URL--url集群的 web service URL默认端口 8080--url-secure用于安全连接TLS的 web service URL使用 REST API 创建集群创建集群对应的 REST 端点为PUT /admin/v2/clusters/:cluster其中:cluster为要创建的集群名称。请求体为ClusterData的 JSON 表示。服务端 ClustersBase.java 中createCluster的 Swagger 示例给出了典型 JSON 结构{ serviceUrl: http://pulsar.example.com:8080, brokerServiceUrl: pulsar://pulsar.example.com:6651 }该端点可能的响应码包括204创建成功、403无超级用户权限、409集群已存在、412集群名称不合法、500内部错误。同时服务端还要求集群名不能包含/字符。使用 Java API 创建集群ClusterData clusterData new ClusterData( serviceUrl, serviceUrlTls, brokerServiceUrl, brokerServiceUrlTls ); admin.clusters().createCluster(clusterName, clusterData);ClusterData是集群配置的数据载体其接口定义位于 pulsar-client-admin-api 的 ClusterData.java。该接口包含的字段远不止上述四个还支持proxyServiceUrl、proxyProtocol、peerClusterNames、authenticationPlugin、authenticationParameters以及一组 broker 客户端侧的 TLS 配置brokerClientTlsEnabled、tlsAllowInsecureConnection、brokerClientTlsTrustStore、brokerClientTrustCertsFilePath、listenerName等并通过ClusterData.builder()构建器模式创建实例。这意味着集群配置天然支持后续扩展为 TLS、代理与鉴权场景。Initialize cluster metadata启动 broker 前的关键一步创建集群记录之后还需要初始化该集群的元数据metadata store 中的初始节点。初始化时需要明确指定以下所有信息集群名称--cluster该集群的本地 ZooKeeper连接串--zookeeper/--metadata-store整个 instance 的配置存储configuration store连接串--configuration-store/--configuration-metadata-store集群的web service URL--web-service-url用于与集群内 broker 交互的broker service URL--broker-service-url必须在启动任何属于该集群的 broker 之前完成元数据初始化否则 broker 将无法找到集群的元数据节点而启动失败。初始化命令使用pulsarCLI 工具而非pulsar-admin完整示例如下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 pulsarssl://pulsar.us-west.example.com:6651/其中--*-tls系列参数仅在实例启用了 TLS 认证时才需要使用可参考 security-tls-authentication.md。为什么不能用 REST API 或 Java API 做元数据初始化与 Pulsar 绝大多数管理功能不同集群元数据初始化无法通过 admin REST API 或 admin Java 客户端完成。原因在于元数据初始化需要直接与 ZooKeeper元数据存储通信、创建海量初始节点而这两类 API 都经由 broker 的 HTTP 管理端口间接转发。因此必须使用pulsarCLI 的initialize-cluster-metadata命令。参数明细与源码实现initialize-cluster-metadata的完整参数来源reference-cli-tools.md 中initialize-cluster-metadata小节Flag描述默认值-c,--cluster集群名称必填-uw,--web-service-url新集群的 web service URL必填-tw,--web-service-url-tls启用 TLS 加密的 web service URL-ub,--broker-service-url新集群的 broker service URL-tb,--broker-service-url-tls启用 TLS 加密的 broker service URL-zk,--zookeeper本地 ZooKeeper quorum 连接串-cs,--configuration-store配置存储 quorum 连接串--existing-bk-metadata-service-uri要复用的已有 BookKeeper 集群的元数据服务 URI--initial-num-stream-storage-containersBookKeeper stream storage 的存储容器数量16--initial-num-transaction-coordinators集群中分配的事务协调器数量16--zookeeper-session-timeout-ms本地 ZooKeeper 会话超时毫秒30000-h,--help显示帮助信息false该命令的底层实现位于 PulsarClusterMetadataSetup.java对应类PulsarClusterMetadataSetup。从当前仓库源码看其参数体系已随版本演进有所变化--metadata-store如zk:my-zk:2181取代了旧参数--zookeeper后者被标记为hidden--configuration-metadata-store取代了--configuration-store与--global-zookeeper后者同样被隐藏标记为弃用若同时传入新旧参数程序会报错并提示新参数supersedes the deprecated argument--bookkeeper-metadata-service-uri是--existing-bk-metadata-service-uri的兼容别名已被标记Deprecated。命令执行时会同时连接本地元数据存储local store与配置元数据存储configuration store逐项创建/clusters/name、命名空间 bundle、系统租户与命名空间等元数据节点并可选地初始化 Dlog 命名空间与 BookKeeper stream storage 容器。因此这是一次性的引导操作同一集群只需也只能执行一次。Get configuration获取集群配置已存在的集群可以在任意时刻查询其配置信息。pulsar-admin使用clusters get子命令并指定集群名$ pulsar-admin clusters get cluster-1 { serviceUrl: http://my-cluster.org.com:8080/, serviceUrlTls: null, brokerServiceUrl: pulsar://my-cluster.org.com:6650/, brokerServiceUrlTls: null peerClusterNames: null }返回的 JSON 即ClusterData的序列化结果注原文档示例中brokerServiceUrlTls行后缺少一个逗号实际输出以服务端为准。REST APIGET /admin/v2/clusters/:cluster成功时返回200与集群配置数据ClusterDataImpl404表示集群不存在。Java APIadmin.clusters().getCluster(clusterName);Update更新集群配置集群配置创建后可以随时更新。pulsar-admin使用clusters update子命令通过 flag 指定新的配置值$ pulsar-admin clusters update cluster-1 \ --url http://my-cluster.org.com:4081 \ --broker-url pulsar://my-cluster.org.com:3350REST APIPOST /admin/v2/clusters/:cluster服务端updateCluster方法会先校验集群存在404不存在再写入新配置403表示无权限或策略只读。Java APIClusterData clusterData new ClusterData( serviceUrl, serviceUrlTls, brokerServiceUrl, brokerServiceUrlTls ); admin.clusters().updateCluster(clusterName, clusterData);Delete删除集群集群可以从所在的 Pulsar instance 中删除。pulsar-admin$ pulsar-admin clusters delete cluster-1REST APIDELETE /admin/v2/clusters/:clusterJava APIadmin.clusters().deleteCluster(clusterName);实战提醒服务端deleteCluster的 Swagger 定义中列出了412响应码含义为 Cluster is not empty集群非空。也就是说当集群下仍存在命名空间、租户等资源时删除会被拒绝。正确流程是先清理该集群下的命名空间与租户再删除集群本身。List列出集群可以获取当前 Pulsar instance 中全部集群的列表。pulsar-admin$ pulsar-admin clusters list cluster-1 cluster-2REST APIGET /admin/v2/clusters返回集群名的集合服务端实现对应 ClustersBase.java 中的getClusters方法。Java APIadmin.clusters().getClusters();Update peer-cluster data配置对等集群**对等集群peer clusters**是 Pulsar 多集群 / 跨地域复制场景中的关键概念将多个集群互相声明为 peer 后这些集群可以互为对等方用于拓扑感知与故障转移场景。pulsar-admin$ pulsar-admin clusters update-peer-clusters cluster-1 --peer-clusters cluster-2原文档示例写作pulsar-admin update-peer-clusters cluster-1 --peer-clusters cluster-2按 reference-pulsar-admin.md 中clusters子命令列表正确形式应为pulsar-admin clusters update-peer-clusters ...运行时以pulsar-admin clusters --help输出为准。REST APIPOST /admin/v2/clusters/:cluster/peers请求体为 peer 集群名列表例如[ cluster-a, cluster-b ]Java APIadmin.clusters().updatePeerClusterNames(clusterName, peerClusterList);源码中的校验逻辑服务端setPeerClusterNames方法见 ClustersBase.java在写入前会执行严格校验先校验被配置的集群本身是否存在遍历传入的peerClusterNames逐一检查每个 peer 集群是否真实存在若不存在则直接返回412 Peer cluster doesnt exist校验通过后将peerClusterNames写入集群配置ClusterData.peerClusterNames并记录操作日志。也就是说--peer-clusters中出现的每一个名字都必须是在当前 instance 中已创建成功的集群否则整个操作会被拒绝。这与 ClusterData.java 中peerClusterNames字段类型为LinkedHashSetString保证顺序且去重一一对应。总结与延伸阅读集群管理是搭建 Pulsar 生产环境的第一个环节。标准操作序列是用bin/pulsar initialize-cluster-metadata初始化集群元数据一次性、必须早于 broker 启动用pulsar-admin clusters create或 REST/Java API登记集群配置用clusters get / update / list维护配置用clusters delete回收资源多集群场景下用clusters update-peer-clusters建立对等关系。如需继续深入可参阅同目录下的相关文档reference-pulsar-admin.mdpulsar-admin全部子命令与 flag 参考reference-cli-tools.mdpulsarCLI含initialize-cluster-metadata参考reference-configuration.mdbroker 等组件的完整配置项admin-api-brokers.md集群内 broker 的运维管理concepts-architecture-overview.md理解 metadata store、broker、bookie 在架构中的角色。源码层面的关键入口REST 端点 v2/Clusters.java、实现逻辑 impl/ClustersBase.java、数据模型 ClusterData.java以及元数据初始化工具 PulsarClusterMetadataSetup.java。赞分享消息队列后端流处理【免费下载链接】pulsarApache Pulsar - distributed pub-sub messaging system项目地址https://gitcode.com/gh_mirrors/pulsar28/pulsar点击查看免费下载相关推荐Apache Pulsar 集群管理完全指南pulsar-admin、REST API 与 Java Admin API 实战Apache Pulsar 集群管理完全指南pulsar admin、REST API 与 Java Admin API 实战 本指南以 admin api消息队列后端流处理Apache Pulsar 集群管理实战pulsar-admin、REST API 与 Java Admin API 全面指南Apache Pulsar 集群管理实战pulsar admin、REST API 与 Java Admin API 全面指南 本文基于 Apache Pul消息队列后端流处理Apache Pulsar 集群管理完全指南基于 pulsar-admin、REST API 与 Java Admin API 的 Clusters 资源操作Apache Pulsar 集群管理完全指南基于 pulsar admin、REST API 与 Java Admin API 的 Clusters 资源操作消息队列后端流处理上一篇从测试网到主网DEX-Arbitrage部署全流程与环境切换策略下一篇Piped数据备份教程如何导出与导入你的Piped数据创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考