Apache Pulsar 命名空间权限管理实战:grant-permission 授权、查询与撤销完整指南

原创2026-09-22 21:20:491,626 阅读
文章标签:消息队列后端流处理

Apache Pulsar 命名空间权限管理实战:grant-permission 授权、查询与撤销完整指南

本篇文章聚焦 Apache Pulsar 基于命名空间(namespace)粒度的权限管理机制,系统讲解如何通过 pulsar-admin CLI、REST API 与 Java Admin API 完成角色授权(Grant)、权限查询(Get)与权限撤销(Revoke)三大操作,并深入剖析通配符授权(Wildcard Authorization)的启用前提与匹配规则。读完本文,你将能够在多租户、多集群环境下为指定角色精确配置 produce / consume 等操作权限,并能结合仓库源码理解权限管理在 Broker 与 Admin API 层面的真实实现链路。

权限模型概述:权限挂载在命名空间上

Pulsar 的权限体系以命名空间(namespace)为管理单元:权限总是被授予给某个具体角色(role),并且只对特定命名空间生效。由于命名空间天然归属在租户(tenant)之下,并被分配到某个集群(cluster),因此权限模型实际上是沿着"租户 → 命名空间 → 集群"这条链路展开的,相关术语可参考 reference-terminology.md。

这一设计带来的实际效果是:

  • 权限无法脱离命名空间单独存在,不存在"全局角色"的概念;
  • 同一个角色可以在不同命名空间拥有完全不同的权限集合;
  • 授权粒度精确到操作级别(produce、consume 等),而不是"读/写"这种粗粒度划分。

从源码结构看,命名空间权限的底层落点非常清晰:pulsar-admin 的 namespaces 命令族全部在 CmdNamespaces.java 中注册实现,其中 grant-permission、permissions、revoke-permission 三个子命令分别对应内部的 GrantPermissions、Permissions、RevokePermissions 三个 CLI 命令类,最终统一收敛到 Namespaces Admin API 接口上。

授予权限(Grant permissions)

授权操作的本质是:把一组操作(actions)授予某个角色(role),作用于某个命名空间。可授予的操作包括 produce 与 consume,这对应 Pulsar 中最核心的生产/消费两大能力。

方式一:pulsar-admin CLI

使用 namespaces grant-permission 子命令,通过 --actions 指定操作列表、--role 指定角色:

$ pulsar-admin namespaces grant-permission test-tenant/ns1 \
  --actions produce,consume \
  --role admin10

该命令执行后,角色 admin10 就获得了对 test-tenant/ns1 命名空间的 produce 和 consume 权限。

方式二:REST API

REST 层对应的端点为:

POST /admin/v2/namespaces/:tenant/:namespace/permissions/:role

请求体为要授予的操作集合(如 ["produce", "consume"]),路径中的 :role 即被授权的角色名。

方式三:Java Admin API

admin.namespaces().grantPermissionOnNamespace(namespace, role, getAuthActions(actions));

其中 getAuthActions(actions) 将字符串形式的操作列表转换为 Set<AuthAction> 枚举集合。

源码视角:授权调用的完整链路

在 CmdNamespaces.java 中,GrantPermissions 命令类明确要求三个参数:

  • tenant/namespace(位置参数,必填);
  • --role(必填,描述为 "Client role to which grant permissions");
  • --actions(必填,描述中列出了完整的可选值:produce,consume,sources,sinks,functions,packages)。

实际执行时先通过 validateNamespace(params) 校验命名空间格式,随后调用 getAdmin().namespaces().grantPermissionOnNamespace(...)。

在 Admin API 实现端 NamespacesImpl.java 中,grantPermissionOnNamespaceAsync 会构造 namespacePath(ns, "permissions", role) 路径并向其发起 POST 请求——可以看到 REST 端点与 Java Admin API 底层使用的是同一套 HTTP 接口,三者殊途同归:

pulsar-admin CLI ──→ Java Admin API(NamespacesImpl)──→ REST /admin/v2/namespaces/:tenant/:namespace/permissions/:role ──→ Broker 授权存储

通配符授权:开启与匹配规则

在实际运维中,往往需要一次性为多个结构相似的角色(如 my.role.1、my.role.2、my.role.foo)批量授权。Pulsar 通过通配符授权支持这一场景,但必须先满足一个前提条件。

前置开关:authorizationAllowWildcardsMatching

通配符匹配默认是关闭的,需要在 broker.conf 中将 authorizationAllowWildcardsMatching 设置为 true:

# broker.conf
authorizationAllowWildcardsMatching=true

该配置项定义于 ServiceConfiguration.java,默认值为 false,属于 CATEGORY_AUTHORIZATION(授权)配置分类。其源码文档明确说明了适用约束:

Allow wildcard matching in authorization (wildcard matching only applicable if wildcard-char: * presents at first or last position eg: .pulsar.service, pulsar.service.)

即:通配符 * 只允许出现在角色名的开头或结尾。这一限制也直接决定了下面几种匹配行为。

通配符在开头:匹配任意前缀

$ pulsar-admin namespaces grant-permission test-tenant/ns1 \
                        --actions produce,consume \
                        --role '*.role.my'

执行后,角色 1.role.my、2.role.my、foo.role.my、bar.role.my 等所有以 .role.my 结尾的角色均可生产与消费。

通配符在结尾:匹配任意后缀

$ pulsar-admin namespaces grant-permission test-tenant/ns1 \
                        --actions produce,consume \
                        --role 'my.role.*'

执行后,角色 my.role.1、my.role.2、my.role.foo、my.role.bar 等所有以 my.role. 开头的角色均可生产与消费。

通配符在中间:不生效

$ pulsar-admin namespaces grant-permission test-tenant/ns1 \
                        --actions produce,consume \
                        --role 'my.*.role'

由于 * 出现在角色名中间,通配符匹配不会生效,此时只有字面角色 my.*.role 本身获得权限;角色 my.1.role、my.2.role、my.foo.role、my.bar.role 等无法生产与消费。

使用建议

  • 通配符授权适用于"角色按层级命名"的组织方式(例如按部门、按环境划分角色前缀/后缀);
  • 由于通配符会影响一批角色,建议在启用 authorizationAllowWildcardsMatching 前充分评估其匹配范围,避免权限过度扩散;
  • 该开关对 Broker 生效,多 Broker 集群需要确保所有 Broker 配置一致。

查看权限(Get permissions)

授权完成后,可以随时查看某个命名空间下各角色已被授予的权限集合。

方式一:pulsar-admin CLI

使用 namespaces permissions 子命令并指定命名空间:

$ pulsar-admin namespaces permissions test-tenant/ns1
{
  "admin10": [
    "produce",
    "consume"
  ]
}

输出为 JSON 对象:键是角色名,值是该角色在该命名空间下的操作权限列表。

方式二:REST API

GET /admin/v2/namespaces/:tenant/:namespace/permissions

方式三:Java Admin API

admin.namespaces().getPermissions(namespace);

返回类型为 Map<String, Set<String>>,键为角色名、值为操作权限集合。

源码视角

在 CmdNamespaces.java 中,Permissions 命令类接收 tenant/namespace 位置参数后,直接调用 getAdmin().namespaces().getPermissions(namespace) 并将结果 print 到终端——这正是上面 JSON 输出的来源。与之对应,REST 与 Java API 的内部实现同样在 NamespacesImpl 中通过 namespacePath(ns, "permissions") 发起 GET 请求完成查询。

撤销权限(Revoke permissions)

撤销操作会移除指定角色对指定命名空间的全部权限,撤销后该角色将无法再对该命名空间执行任何被撤销的操作(包括生产与消费)。

方式一:pulsar-admin CLI

使用 namespaces revoke-permission 子命令,通过 --role 指定角色:

$ pulsar-admin namespaces revoke-permission test-tenant/ns1 \
  --role admin10

方式二:REST API

DELETE /admin/v2/namespaces/:tenant/:namespace/permissions/:role

方式三:Java Admin API

admin.namespaces().revokePermissionsOnNamespace(namespace, role);

源码视角

在 CmdNamespaces.java 中,RevokePermissions 命令类要求 tenant/namespace 与 --role 两个必填参数,执行时调用 revokePermissionsOnNamespace(namespace, role)。在 NamespacesImpl.java 中,该方法对 namespacePath(ns, "permissions", role) 发起 DELETE 请求——与授权的 POST 请求使用同一资源路径,符合 REST 语义:对同一资源执行 POST 即授予、DELETE 即撤销。

权限生命周期:从授予到验证的完整示例

将三个操作串联起来,就构成一次完整的权限管理闭环:

# 1. 创建命名空间(若尚未创建)
$ pulsar-admin namespaces create test-tenant/ns1

# 2. 为角色 admin10 授予 produce、consume 权限
$ pulsar-admin namespaces grant-permission test-tenant/ns1 \
  --actions produce,consume \
  --role admin10

# 3. 验证授权结果
$ pulsar-admin namespaces permissions test-tenant/ns1
{
  "admin10": [
    "produce",
    "consume"
  ]
}

# 4. 使用 admin10 角色完成生产/消费后,撤销其权限
$ pulsar-admin namespaces revoke-permission test-tenant/ns1 \
  --role admin10

# 5. 再次查看,确认权限已清空
$ pulsar-admin namespaces permissions test-tenant/ns1
{}

对于需要批量授权多个子角色的场景,可先确认 broker.conf 中已开启 authorizationAllowWildcardsMatching=true,然后使用前缀或后缀通配符角色(如 *.role.my 或 my.role.*)一次性完成授权。

小结

本文完整覆盖了 Apache Pulsar 命名空间权限管理的三大核心操作:

操作 pulsar-admin 子命令 REST 端点 Java Admin API 方法
授予权限 namespaces grant-permission POST /admin/v2/namespaces/:tenant/:namespace/permissions/:role grantPermissionOnNamespace
查看权限 namespaces permissions GET /admin/v2/namespaces/:tenant/:namespace/permissions getPermissions
撤销权限 namespaces revoke-permission DELETE /admin/v2/namespaces/:tenant/:namespace/permissions/:role revokePermissionsOnNamespace

关键要点回顾:

  1. 权限粒度:权限以命名空间为单元、以角色为主体、以操作为粒度,沿着"租户 → 命名空间 → 集群"的层级生效;
  2. 通配符限制:* 仅允许出现在角色名开头或结尾,且必须先在 broker.conf 中开启 authorizationAllowWildcardsMatching;
  3. 三端一致:pulsar-admin、REST API 与 Java Admin API 底层走同一套 REST 接口(见 NamespacesImpl 实现),生产环境可任选其一,或组合用于脚本化运维。

如果想进一步深入,可以阅读 CmdNamespaces.java 查看 grant-permission、permissions、revoke-permission 的命令参数定义与校验逻辑,或在 NamespacesImpl.java 中追踪三类操作的 HTTP 调用细节。

登录后查看全文
pulsar