lakeFS 授权体系简化设计:从 PBAC 策略走向基于 ACL 的组权限模型
lakeFS 授权体系简化设计:从 PBAC 策略走向基于 ACL 的组权限模型
本文围绕 lakeFS 仓库中 RBAC 到 ACL 的授权简化设计文档 展开:先讲清设计目标与四个核心概念(Permission、Scope、Grant、默认组),再说明 GUI 与 lakectl 的新交互形态,以及升级脚本的完整迁移规则与底层 ui 子对象到 PBAC statement 的物化机制,帮助读者理解 lakeFS 如何把复杂策略引擎收敛为可维护的访问控制列表(ACL)。
设计目标:用 ACL 替换 PBAC,但保留策略引擎
lakeFS 当前的授权实现是一套基于策略的访问控制(PBAC)引擎,功能强大但对普通用户来说配置门槛高。该设计文档(位于 design/open/acl/rbac-to-acl.md)提出的目标是:
- 对外简化:用 ACL(组 + 权限 + 仓库范围)取代面向用户的 PBAC 策略配置,并提供一个简单 GUI,让管理员只需把用户放入组、为每个组配置允许访问的范围;
- 对内不变:lakeFS 授权执行的"基石"仍然是策略引擎本身——这是一个久经考验的方案。高级用户如果部署并配置了外部授权服务器,仍然可以保留完整的策略(Policy)能力;但 lakeFS 自身不再内置授权服务器;
- 明确退出项:从 GUI 中移除策略(Policy)页面及所有策略引用,从
lakectl中移除所有策略相关命令,API 也不再支持这些操作——调用时返回 [405 Method Not Allowed] 或 [501 Unimplemented],即 auth 相关 API 变为"部分实现"状态。
从源码结构看,这一"基石保留"的说法与仓库现状一致:策略的存储模型(含 Statement、Effect 等字段)仍定义在 pkg/auth/model/model.go,权限判定逻辑仍在 pkg/auth/policy_filter.go 中,例如 CheckPermission 函数遍历用户的策略语句,先解析资源 ARN 并做通配匹配,遇到 Deny 语句立即返回拒绝(Deny 优先),否则只要存在匹配的 Allow 语句即放行。ACL 方案不替换这条执行链路,只是改变了策略的生产方式。
核心概念:Permissions、Scopes 与 Grants
Permissions:四个系统预定义权限
Permission 允许一组用户(group)执行某些操作。用户不能自行创建权限,lakeFS 只提供以下四种:
| Permission | 允许的操作 | 对应现有内置组 |
|---|---|---|
| Read | 读操作、创建访问密钥 | Viewers |
| Write | 所有数据的读写操作 | Developers |
| Super | 除 auth 之外的所有操作 | SuperUsers(有调整) |
| Admin | 所有操作 | Admins |
在现有 RBAC 术语下,非管理员拥有的权限都位于 fs:* 前缀之下,此外还有管理自身凭据的权限(AuthManageOwnCredentials),后者会授予所有用户。文档特别指出:部分服务作业(如 GC)必须使用具有 Admin 权限的用户来运行。
四种权限与现有默认组的映射关系,正对应仓库中授权模块的既有概念——内置组名(Viewers / Developers / SuperUsers / Admins)在 pkg/api/controller.go 等 API 层代码中已有出现,说明 ACL 方案是复用既有组结构而非另起炉灶。
Scopes:权限作用域
被授予组时,Read、Write、Super 三种权限可以被"限定范围"(scoped),即只作用于某个仓库集合;而 Admin 不可被限定范围——它包含跨仓库的全局能力,且可以修改已授予的权限本身。
Grants:一次一个"权限 × 范围"的授予
一个组在一个范围内只被授予单一权限。"Admin" 权限没有范围(在 GUI 中显示为置灰,覆盖所有仓库)。
界面形态:Groups 页面的权限下拉框
ACL 模式下,Groups 页面中每个组按如下列展示:
| Group ID | Permission | Created at | Repositories |
|---|---|---|---|
<name> |
权限下拉框 | 时间 | <仓库数量> |
设计文档附带了该界面的示意图(图中 Admins 组 Repository 数为 3、Developers 为 6、SuperUsers 显示 "All",每个组的 Permission 列都是一个可编辑的下拉框):
这张图展示了组信息与权限编辑入口:管理员可以直接在列表中修改组的权限。存在 4 个默认组,以四种权限命名,且每个组都是全局的(适用于所有仓库)。
点击某个组进入其子页面,包含两个标签页:
- Members:即当前的 "Group Memberships" 标签,管理组成员;
- Repositories:已配置仓库的列表。该标签页顶部有一个 "all" 开关。若权限是 "Admin",该开关被强制打开且不可更改;否则它控制仓库的选择,使用与今天管理组成员(以及,颇具讽刺意味地,管理策略)相同的 GUI 机制。
文档同时承诺会为 lakectl 增加相应的选项,以在新粒度上控制策略。
升级路径:启动检查与升级脚本
启动时的升级检查
启动时 lakeFS 会检查 KV 的 schema 版本。如果尚未升级到 ACL,lakeFS 会检查是否需要升级:
- 若 4 个基础策略(basic policies)未被修改、没有定义过其他策略、也没有任何用户直接附加过策略:无需升级,lakeFS 仅升级 KV schema 版本即可;
- 否则,lakeFS 拒绝启动,直到升级脚本被执行。
升级脚本的行为与规则
管理员在 lakeFS 要求时(或者出于谨慎,例如存在多个 lakeFS 实例并发运行的竞态场景)运行升级脚本。脚本通过 --yes 标志强制要求管理员先做一次 dry run:不带该标志时,脚本只打印计划中的变更,不实际执行。
升级脚本会确保(ensure) 4 个默认全局组存在,并修改(modify) 现有组以适配新的 ACL 方案。具体规则如下:
- 创建默认组时的命名冲突:如果已存在同名组,升级会将其重命名为原名加 ".orig" 后缀。升级完成后,4 个默认全局组以这些已知名字存在;
- 对任意组,配置策略的升级遵循以下规则(注意:这可能会"扩大"访问范围):
- 所有 "Deny" 规则被剥离,并打印警告;
- 补加 "管理自身凭据" 权限;
- 若策略允许了
fs:之外的任何 action,该组直接变为 Admin 组,打印警告,且不再应用后续规则; - 仓库统一(unify repositories):如果某权限通过通配符作用于一组仓库,则统一为 所有 仓库;否则统一为"所有策略中出现过的仓库的并集列表";
- action 统一(unify actions):在 Read、Write、Super 中选择能包含全部已允许 action 的最低权限。即使某个已允许的 action 本身含通配符,该选择仍有意义;
- 所有警告都附带指向 support@ 和 Slack 的链接;
- 升级脚本最后打印每个组的新权限。文档的脚注解释:即便用 JSON-diff 也无法详细报告变更,因为许多策略会被合并为单一策略。
这些规则的共同特点是只升不降:Deny 被剥离、通配仓库被放大为全仓库、action 被归并到覆盖集,因此升级是有损语义(放宽访问)的,这也是文档要求 dry run 并打印警告的原因。
外部授权服务器下的 PBAC 用户体验
如果 lakeFS 挂载了外部授权服务器,现有的 PBAC GUI 可以继续保留使用。但不能同时使用两种 GUI:从 PBAC 迁移到简化模式只能执行一次,且会丢失配置。
实现机制:ui 子对象与 statement 的物化关系
lakeFS 的强制(enforcement)执行仍然由 PBAC 支撑。实现方式是给策略增加一个 ui 字段,其中保存支撑 UI 的结构。设计文档给出了两个并列示例——"Read 所有仓库"与"Read 仅限 foo、bar 仓库":
"Read 所有仓库"对应的策略对象:
{
"statement": [
{
"action": ["fs:List*", "fs:Read*"],
"effect": "allow",
"resource": "*"
}
],
"ui": {
"permission": "Read",
"repositories": { "all": true }
}
}
"Read 仓库 foo 与 bar"对应的策略对象:
{
"statement": [
{
"action": ["fs:List*", "fs:Read*"],
"effect": "allow",
"resource": "foo"
}, {
"action": ["fs:List*", "fs:Read*"],
"effect": "allow",
"resource": "bar"
}
],
"ui": {
"permission": "Read",
"repositories": { "list": ["foo", "bar"] }
}
}
注意两个示例中 ui.permission 都是 "Read",与 statement 中 fs:List* + fs:Read* 两个 action 的组合一一对应:UI 层只暴露抽象的 permission 名,而 statement 层保存的是执行引擎真正消费的具体 action 通配式与资源。
关键机制在于:UI 只接收并编辑 ui 子对象;当 UI 把修改后的对象提交回来时,lakeFS 再把它翻译回 statement。也就是说,PBAC statement 实际上是 ui 子对象的物化形式(materialized form)——用户在 GUI 里改的是权限下拉框和仓库范围,落库的却是标准策略语句,授权判定路径完全不变。这与前述 CheckPermission(pkg/auth/policy_filter.go)等执行代码无需改动的结论互相印证。
里程碑
设计文档最后列出了四个实施里程碑:
- 评审并接受设计;
- 服务端支持:添加
ui子对象以及ui -> statement的翻译; lakectl对简化模式的支持;- GUI 实现。
小结
这份设计是 lakeFS 在"授权表达"与"授权执行"之间做的一次解耦:对用户和 API 暴露的不再是自由组合的 PBAC 语句,而是 Read / Write / Super / Admin 四种权限加仓库范围这一有限词汇表;而存储与判定层继续复用久经考验的策略引擎,ui 子对象与 statement 之间的双向翻译保证了向后兼容与平滑升级。升级脚本"只放宽、不收紧、全程可 dry run"的迁移规则,以及"迁移到简化模式不可逆、会丢失配置"的明确警示,共同构成了这一方案的运维边界。对于需要细粒度 Deny 或条件语句(conditions)的用户,文档给出的出路是部署外部授权服务器,继续沿用完整 PBAC 能力。
