Apache Pulsar 命名空间权限管理实战:grant-permission 授权、查询与撤销完整指南
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 |
关键要点回顾:
- 权限粒度:权限以命名空间为单元、以角色为主体、以操作为粒度,沿着"租户 → 命名空间 → 集群"的层级生效;
- 通配符限制:
*仅允许出现在角色名开头或结尾,且必须先在broker.conf中开启authorizationAllowWildcardsMatching; - 三端一致:
pulsar-admin、REST API 与 Java Admin API 底层走同一套 REST 接口(见NamespacesImpl实现),生产环境可任选其一,或组合用于脚本化运维。
如果想进一步深入,可以阅读 CmdNamespaces.java 查看 grant-permission、permissions、revoke-permission 的命令参数定义与校验逻辑,或在 NamespacesImpl.java 中追踪三类操作的 HTTP 调用细节。