尧图网页设计 
Loki 标签级访问控制LBAC实战指南基于 X-Prom-Label-Policy 的多租户日志查询隔离【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki导读标签级访问控制Label-Based Access ControlLBAC是 Lokiv3.7.3 起提供实验特性提供的一种细粒度查询隔离机制它允许运维方为每个租户绑定一组 Prometheus 标签选择器label selector使该租户发起的查询只能命中与任一选择器匹配的日志流从而实现租户内再分权的数据可见性边界。本文将基于 lbac.md 官方文档结合 pkg/labelaccess 与 pkg/loki/labelaccess.go 的源码实现完整讲解 LBAC 的安全模型、启用方式、标签策略头格式、多选择器组合、作用范围与边界限制并给出可直接落地的网关侧配置示例。什么是标签级访问控制LBACLBAC 的核心思想非常直接把租户能看哪些数据从整个租户的数据细化为满足若干标签选择器之一的数据。每个策略由一组标准的 Prometheus 标签选择器构成一个租户可以关联多个选择器选择器之间按OR析取组合查询执行时只有至少匹配其中一个选择器的日志流才会被返回其余日志流在查询阶段即被过滤掉由于选择器之间是 OR 关系整个策略体系等价于析取范式Disjunctive Normal Form, DNF。源码中 pkg/labelaccess/types/label.go 的LabelPolicy结构体正是用一个Selector []*LabelMatcher表达同一选择器内多个匹配器 AND而LabelPolicySetmap[string][]*types.LabelPolicy见 pkg/labelaccess/propagation.go则通过每个租户挂多个 Policy表达选择器之间 OR。从源码结构可以推断这套 DNF 语义最终落在过滤器的ShouldFilter方法上pkg/labelaccess/request_chunk_filterer.go遍历该租户的每个LabelPolicy在单个 Policy 内所有LabelMatcher必须全部匹配AND只要任意一个Policy 匹配就返回false不过滤该 chunk/stream即放行全部 Policy 都不匹配才返回true过滤掉。注意LBAC 建立在 Loki 多租户机制之上策略按租户隔离因此必须运行在多租户模式下。安全模型信任边界与网关前置Loki 本身不包含认证层。无论是租户标识还是标签策略都来源于 HTTP 请求头请求头含义X-Scope-OrgID租户tenant / org标识Loki 多租户的标准头X-Prom-Label-Policy标签策略格式为tenant:URL-encoded selector官方文档对此给出了一条硬性警告绝不直接将 Loki API 暴露给客户端。任何能直接触达 Loki 的客户端都可以自行伪造X-Scope-OrgID与X-Prom-Label-Policy头从而完全绕过标签级访问控制。必须在 Loki 前方部署认证网关由网关完成请求认证、设置租户并附加正确的标签策略。因此推荐架构为Client ──► Auth Gateway ──► Loki │ ├─ 1. 认证客户端身份 ├─ 2. 剥离用户提交的 X-Scope-OrgID / X-Prom-Label-Policy └─ 3. 依据认证后的身份写入正确的 X-Scope-OrgID 与 X-Prom-Label-Policy网关必须负责剥离用户自带的两个头并以认证身份推导出的值替换之。官方文档提及的开源网关参考实现为 grafana/db-auth-gateway更通用的认证反向代理部署指引可参考仓库内 authentication 文档若存在。这一信任边界在源码中同样成立Loki 侧只是信任X-Prom-Label-Policy头并解析执行见 pkg/labelaccess/middleware.go 中NewLabelAccessMiddleware的注释——parses the X-Prom-Label-Policy header and injects the parsed label selectors into the request context。启用标签级访问控制1. 确保多租户模式多租户模式默认开启显式配置为auth_enabled: true只有开启auth_enabled请求才会携带租户标识LBAC 才有按租户锚定策略的基础。2. 开启 LBAClbac: enabled: true对应配置结构体见 pkg/labelaccess/config.go其中Enabled字段被标记为category:experimental默认false。也可以通过命令行参数启用-lbac.enabledtrue该 flag 的官方描述为Enables label based access control through the X-Prom-Label-Policy header。3. 启用后发生什么开启后Loki 会在请求链路上解析X-Prom-Label-Policy头并强制执行其中的策略。从 pkg/loki/labelaccess.go 的setupLBAC()可以看到LBAC 是一个贯穿几乎全部查询路径的横切特性它注册了十余个内部模块并注入依赖AuthMiddleware合并labelaccess.NewLabelAccessMiddleware到 HTTP 认证中间件链负责解析策略头并注入请求上下文pkg/loki/labelaccess.goLabelAccessStoreWrapper / LabelAccessIngesterWrapper / Filterers分别包装 Store、Ingester并为 Ingester 配置 ChunkFilterer实现存储与内存侧过滤LabelAccessV2Engine为 V2 查询引擎设置RequestStreamFilterer实现数据对象上的流级过滤pkg/loki/labelaccess.go对应实现 pkg/labelaccess/request_stream_filterer.goLabelAccessInterceptors为 Ingester / IndexGateway 的 gRPC 服务端与客户端追加 LBAC 拦截器保证策略在 gRPC 链路上不丢失LabelAccessTripperware / LabelAccessUserIDTransformer处理查询前端中间件与缓存键的用户维度变换。对应测试 pkg/loki/lbac_setup_test.go 验证了开启 LBAC 时这些模块全部注册且依赖无环TestSetupLBACEnabled关闭时这些模块全部不注册TestSetupLBACDisabled并确保 LBAC 中间件只安装一次TestLBACAuthMiddlewareRegisteredOnce。设置标签策略X-Prom-Label-Policy 头的格式标签策略通过X-Prom-Label-Policy请求头传给 Loki。该头由认证网关设置而不是客户端。单个策略的格式每个头的值形如tenant:URL-encoded selector其中 selector 是一组标准标签匹配器例如{envdev}。因为花括号、引号等字符不适合直接出现在 HTTP 头中需要做URL 编码。官方示例租户tenant1的策略{envdev}编码为X-Prom-Label-Policy: tenant1:%7Benv%3D%22dev%22%7D解码后即为tenant1:{envdev}。一个租户关联多个选择器要把多个选择器关联到同一租户有两种等价写法方式一重复头每个值一条X-Prom-Label-Policy: tenant1:%7Benv%3D%22prod%22%7D X-Prom-Label-Policy: tenant1:%7Benv%3D%22dev%22%7D方式二逗号分隔合并到同一个头值中X-Prom-Label-Policy: tenant1:%7Benv%3D%22prod%22%7D,tenant1:%7Benv%3D%22dev%22%7D两种写法的解析路径在源码中都能找到依据gRPC 侧解析函数ExtractLabelMatchersGRPCpkg/labelaccess/codec.go会对头值按逗号strings.Split(headerValue, ,)拆分后逐条解析HTTP 侧同样按此语义合并成LabelPolicySet。多个选择器之间按OR组合——一个日志流只要匹配其中任意一个选择器就会被返回。实战示例排除带敏感标签的日志最常见的 LBAC 需求是排除带有某标签的日志。例如排除所有带secrettrue标签的日志行使用不等匹配器{secret!true}对应网关头X-Prom-Label-Policy: tenant1:%7Bsecret%21%3D%22true%22%7D!编码为%21编码为%3D编码为%22实战示例多选择器组合策略假设某租户需要同时满足能访问生产环境envprod日志但生产环境中排除secrettrue的日志能访问开发环境envdev日志开发环境不做敏感标签排除。则策略应配置两个选择器{secret!true, envprod} {envdev}该策略的执行语义如下选择器匹配行为{secret!true, envprod}返回生产环境中没有secret: true标签的日志行选择器内多个匹配器是 AND 关系{envdev}返回开发环境的日志行即使它们带有secret: true标签这正是 DNF 的表达力所在两个选择器 OR第一个选择器内部 AND 两个条件从而在一个策略内同时表达排除 放行的差异化规则。对应到源码每个选择器内部是 AND 逻辑见上文ShouldFilter的单 Policy 全匹配判断而不同选择器之间是 OR任一匹配即放行。测试文件 pkg/labelaccess/request_chunk_filterer_test.go 与 pkg/labelaccess/middleware_test.go 覆盖了这类组合场景。标签策略的作用范围需要特别明确 LBAC 的边界标签策略只作用于查询中的日志流选择器Log stream selector不作用于标签过滤表达式Label filter expression。举例来说查询{envprod, secret!true} | error中LBAC 策略只会叠加/约束{envprod, secret!true}这部分流选择器| error这类过滤表达式以及解析后的 label filter不在 LBAC 的管辖范围内。相关概念可参考仓库内日志查询文档中关于 Log stream selector 与 Label filter expression 的说明以仓库实际文档为准。源码层面Loki 会先解析查询的流选择器再与策略选择器做合并/交集判断例如 volume 查询场景下中间件会把策略匹配器 AND 进查询的流选择器中使索引层只返回租户被允许看到的流pkg/labelaccess/middleware.go 的modifyVolumeQuery多策略时则跳过查询改写、改由响应级过滤保证 OR 语义。写入路径不受限LBAC 只约束查询LBAC 不作用于写入push请求。只要某租户被允许写入它就可以推送携带任意标签的日志行无论其查询策略如何。这是读时过滤模型的自然结果LBAC 在查询链路上做过滤而不是在写入时对标签做校验或改写。如果你需要限制租户能写入的标签需要另行配置写入侧校验如租户限制、标签验证等机制LBAC 本身不提供该能力。已知边界Alertmanager 与 ruler 不受 LBAC 约束标签策略不会被 Alertmanager 和 ruler 强制执行。这意味着ruler 服务处理的请求包含该租户的全部内容不应用 LBAC 过滤例如列出 ruler 中某租户的全部规则组rule groups时即使策略中的某个标签选择器会排除部分规则上的标签这些规则仍会全部返回。这一点对依赖 ruler 告警规则的部署方尤为重要不要把敏感数据可见性的最终防线寄托在 ruler/Alertmanager 上需要为告警与规则评估链路单独设计访问控制。从模块依赖看LBAC 的模块注入集中在Querier / QueryFrontend / QueryEngine / Ingester / IndexGateway / Server等查询相关链路pkg/loki/labelaccess.goruler/Alertmanager 组件并不在 LBAC 的注入清单中与文档描述的不受约束一致。端到端落地检查清单部署形态Loki 必须开启auth_enabled: true默认即开启运行在多租户模式功能开关配置lbac.enabled: true或-lbac.enabledtrue网关前置任何客户端不得直连 Loki API由认证网关剥离并重写X-Scope-OrgID与X-Prom-Label-Policy策略编码头值格式tenant:URL-encoded selector多选择器用重复头或逗号分隔选择器间 OR、选择器内 AND查询验证用logcli或 Grafana 以目标租户身份发起查询确认只返回策略允许的日志流对 volume 等索引类查询同样验证边界确认明确写入请求、ruler、Alertmanager 不受 LBAC 约束按需为这些链路补充其他控制手段。相关资源官方文档原文Use label-based access control with LokiLBAC 配置结构体与命令行参数pkg/labelaccess/config.goLBAC 模块装配与依赖注入pkg/loki/labelaccess.go、pkg/loki/lbac_setup_test.go策略头解析与传播X-Prom-Label-Policy、URL 解码、FNV 哈希缓存键pkg/labelaccess/propagation.go、pkg/labelaccess/codec.goHTTP 中间件解析、注入、volume 查询改写pkg/labelaccess/middleware.go过滤实现V1 chunk 级 / V2 stream 级pkg/labelaccess/request_chunk_filterer.go、pkg/labelaccess/request_stream_filterer.go策略与匹配器的 protobuf 风格类型定义pkg/labelaccess/types/label.go多租户文档multi-tenancy以仓库实际路径为准【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Loki 标签级访问控制（LBAC）实战指南：基于 X-Prom-Label-Policy 的多租户日志查询隔离
Loki 标签级访问控制LBAC实战指南基于 X-Prom-Label-Policy 的多租户日志查询隔离【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki导读标签级访问控制Label-Based Access ControlLBAC是 Lokiv3.7.3 起提供实验特性提供的一种细粒度查询隔离机制它允许运维方为每个租户绑定一组 Prometheus 标签选择器label selector使该租户发起的查询只能命中与任一选择器匹配的日志流从而实现租户内再分权的数据可见性边界。本文将基于 lbac.md 官方文档结合 pkg/labelaccess 与 pkg/loki/labelaccess.go 的源码实现完整讲解 LBAC 的安全模型、启用方式、标签策略头格式、多选择器组合、作用范围与边界限制并给出可直接落地的网关侧配置示例。什么是标签级访问控制LBACLBAC 的核心思想非常直接把租户能看哪些数据从整个租户的数据细化为满足若干标签选择器之一的数据。每个策略由一组标准的 Prometheus 标签选择器构成一个租户可以关联多个选择器选择器之间按OR析取组合查询执行时只有至少匹配其中一个选择器的日志流才会被返回其余日志流在查询阶段即被过滤掉由于选择器之间是 OR 关系整个策略体系等价于析取范式Disjunctive Normal Form, DNF。源码中 pkg/labelaccess/types/label.go 的LabelPolicy结构体正是用一个Selector []*LabelMatcher表达同一选择器内多个匹配器 AND而LabelPolicySetmap[string][]*types.LabelPolicy见 pkg/labelaccess/propagation.go则通过每个租户挂多个 Policy表达选择器之间 OR。从源码结构可以推断这套 DNF 语义最终落在过滤器的ShouldFilter方法上pkg/labelaccess/request_chunk_filterer.go遍历该租户的每个LabelPolicy在单个 Policy 内所有LabelMatcher必须全部匹配AND只要任意一个Policy 匹配就返回false不过滤该 chunk/stream即放行全部 Policy 都不匹配才返回true过滤掉。注意LBAC 建立在 Loki 多租户机制之上策略按租户隔离因此必须运行在多租户模式下。安全模型信任边界与网关前置Loki 本身不包含认证层。无论是租户标识还是标签策略都来源于 HTTP 请求头请求头含义X-Scope-OrgID租户tenant / org标识Loki 多租户的标准头X-Prom-Label-Policy标签策略格式为tenant:URL-encoded selector官方文档对此给出了一条硬性警告绝不直接将 Loki API 暴露给客户端。任何能直接触达 Loki 的客户端都可以自行伪造X-Scope-OrgID与X-Prom-Label-Policy头从而完全绕过标签级访问控制。必须在 Loki 前方部署认证网关由网关完成请求认证、设置租户并附加正确的标签策略。因此推荐架构为Client ──► Auth Gateway ──► Loki │ ├─ 1. 认证客户端身份 ├─ 2. 剥离用户提交的 X-Scope-OrgID / X-Prom-Label-Policy └─ 3. 依据认证后的身份写入正确的 X-Scope-OrgID 与 X-Prom-Label-Policy网关必须负责剥离用户自带的两个头并以认证身份推导出的值替换之。官方文档提及的开源网关参考实现为 grafana/db-auth-gateway更通用的认证反向代理部署指引可参考仓库内 authentication 文档若存在。这一信任边界在源码中同样成立Loki 侧只是信任X-Prom-Label-Policy头并解析执行见 pkg/labelaccess/middleware.go 中NewLabelAccessMiddleware的注释——parses the X-Prom-Label-Policy header and injects the parsed label selectors into the request context。启用标签级访问控制1. 确保多租户模式多租户模式默认开启显式配置为auth_enabled: true只有开启auth_enabled请求才会携带租户标识LBAC 才有按租户锚定策略的基础。2. 开启 LBAClbac: enabled: true对应配置结构体见 pkg/labelaccess/config.go其中Enabled字段被标记为category:experimental默认false。也可以通过命令行参数启用-lbac.enabledtrue该 flag 的官方描述为Enables label based access control through the X-Prom-Label-Policy header。3. 启用后发生什么开启后Loki 会在请求链路上解析X-Prom-Label-Policy头并强制执行其中的策略。从 pkg/loki/labelaccess.go 的setupLBAC()可以看到LBAC 是一个贯穿几乎全部查询路径的横切特性它注册了十余个内部模块并注入依赖AuthMiddleware合并labelaccess.NewLabelAccessMiddleware到 HTTP 认证中间件链负责解析策略头并注入请求上下文pkg/loki/labelaccess.goLabelAccessStoreWrapper / LabelAccessIngesterWrapper / Filterers分别包装 Store、Ingester并为 Ingester 配置 ChunkFilterer实现存储与内存侧过滤LabelAccessV2Engine为 V2 查询引擎设置RequestStreamFilterer实现数据对象上的流级过滤pkg/loki/labelaccess.go对应实现 pkg/labelaccess/request_stream_filterer.goLabelAccessInterceptors为 Ingester / IndexGateway 的 gRPC 服务端与客户端追加 LBAC 拦截器保证策略在 gRPC 链路上不丢失LabelAccessTripperware / LabelAccessUserIDTransformer处理查询前端中间件与缓存键的用户维度变换。对应测试 pkg/loki/lbac_setup_test.go 验证了开启 LBAC 时这些模块全部注册且依赖无环TestSetupLBACEnabled关闭时这些模块全部不注册TestSetupLBACDisabled并确保 LBAC 中间件只安装一次TestLBACAuthMiddlewareRegisteredOnce。设置标签策略X-Prom-Label-Policy 头的格式标签策略通过X-Prom-Label-Policy请求头传给 Loki。该头由认证网关设置而不是客户端。单个策略的格式每个头的值形如tenant:URL-encoded selector其中 selector 是一组标准标签匹配器例如{envdev}。因为花括号、引号等字符不适合直接出现在 HTTP 头中需要做URL 编码。官方示例租户tenant1的策略{envdev}编码为X-Prom-Label-Policy: tenant1:%7Benv%3D%22dev%22%7D解码后即为tenant1:{envdev}。一个租户关联多个选择器要把多个选择器关联到同一租户有两种等价写法方式一重复头每个值一条X-Prom-Label-Policy: tenant1:%7Benv%3D%22prod%22%7D X-Prom-Label-Policy: tenant1:%7Benv%3D%22dev%22%7D方式二逗号分隔合并到同一个头值中X-Prom-Label-Policy: tenant1:%7Benv%3D%22prod%22%7D,tenant1:%7Benv%3D%22dev%22%7D两种写法的解析路径在源码中都能找到依据gRPC 侧解析函数ExtractLabelMatchersGRPCpkg/labelaccess/codec.go会对头值按逗号strings.Split(headerValue, ,)拆分后逐条解析HTTP 侧同样按此语义合并成LabelPolicySet。多个选择器之间按OR组合——一个日志流只要匹配其中任意一个选择器就会被返回。实战示例排除带敏感标签的日志最常见的 LBAC 需求是排除带有某标签的日志。例如排除所有带secrettrue标签的日志行使用不等匹配器{secret!true}对应网关头X-Prom-Label-Policy: tenant1:%7Bsecret%21%3D%22true%22%7D!编码为%21编码为%3D编码为%22实战示例多选择器组合策略假设某租户需要同时满足能访问生产环境envprod日志但生产环境中排除secrettrue的日志能访问开发环境envdev日志开发环境不做敏感标签排除。则策略应配置两个选择器{secret!true, envprod} {envdev}该策略的执行语义如下选择器匹配行为{secret!true, envprod}返回生产环境中没有secret: true标签的日志行选择器内多个匹配器是 AND 关系{envdev}返回开发环境的日志行即使它们带有secret: true标签这正是 DNF 的表达力所在两个选择器 OR第一个选择器内部 AND 两个条件从而在一个策略内同时表达排除 放行的差异化规则。对应到源码每个选择器内部是 AND 逻辑见上文ShouldFilter的单 Policy 全匹配判断而不同选择器之间是 OR任一匹配即放行。测试文件 pkg/labelaccess/request_chunk_filterer_test.go 与 pkg/labelaccess/middleware_test.go 覆盖了这类组合场景。标签策略的作用范围需要特别明确 LBAC 的边界标签策略只作用于查询中的日志流选择器Log stream selector不作用于标签过滤表达式Label filter expression。举例来说查询{envprod, secret!true} | error中LBAC 策略只会叠加/约束{envprod, secret!true}这部分流选择器| error这类过滤表达式以及解析后的 label filter不在 LBAC 的管辖范围内。相关概念可参考仓库内日志查询文档中关于 Log stream selector 与 Label filter expression 的说明以仓库实际文档为准。源码层面Loki 会先解析查询的流选择器再与策略选择器做合并/交集判断例如 volume 查询场景下中间件会把策略匹配器 AND 进查询的流选择器中使索引层只返回租户被允许看到的流pkg/labelaccess/middleware.go 的modifyVolumeQuery多策略时则跳过查询改写、改由响应级过滤保证 OR 语义。写入路径不受限LBAC 只约束查询LBAC 不作用于写入push请求。只要某租户被允许写入它就可以推送携带任意标签的日志行无论其查询策略如何。这是读时过滤模型的自然结果LBAC 在查询链路上做过滤而不是在写入时对标签做校验或改写。如果你需要限制租户能写入的标签需要另行配置写入侧校验如租户限制、标签验证等机制LBAC 本身不提供该能力。已知边界Alertmanager 与 ruler 不受 LBAC 约束标签策略不会被 Alertmanager 和 ruler 强制执行。这意味着ruler 服务处理的请求包含该租户的全部内容不应用 LBAC 过滤例如列出 ruler 中某租户的全部规则组rule groups时即使策略中的某个标签选择器会排除部分规则上的标签这些规则仍会全部返回。这一点对依赖 ruler 告警规则的部署方尤为重要不要把敏感数据可见性的最终防线寄托在 ruler/Alertmanager 上需要为告警与规则评估链路单独设计访问控制。从模块依赖看LBAC 的模块注入集中在Querier / QueryFrontend / QueryEngine / Ingester / IndexGateway / Server等查询相关链路pkg/loki/labelaccess.goruler/Alertmanager 组件并不在 LBAC 的注入清单中与文档描述的不受约束一致。端到端落地检查清单部署形态Loki 必须开启auth_enabled: true默认即开启运行在多租户模式功能开关配置lbac.enabled: true或-lbac.enabledtrue网关前置任何客户端不得直连 Loki API由认证网关剥离并重写X-Scope-OrgID与X-Prom-Label-Policy策略编码头值格式tenant:URL-encoded selector多选择器用重复头或逗号分隔选择器间 OR、选择器内 AND查询验证用logcli或 Grafana 以目标租户身份发起查询确认只返回策略允许的日志流对 volume 等索引类查询同样验证边界确认明确写入请求、ruler、Alertmanager 不受 LBAC 约束按需为这些链路补充其他控制手段。相关资源官方文档原文Use label-based access control with LokiLBAC 配置结构体与命令行参数pkg/labelaccess/config.goLBAC 模块装配与依赖注入pkg/loki/labelaccess.go、pkg/loki/lbac_setup_test.go策略头解析与传播X-Prom-Label-Policy、URL 解码、FNV 哈希缓存键pkg/labelaccess/propagation.go、pkg/labelaccess/codec.goHTTP 中间件解析、注入、volume 查询改写pkg/labelaccess/middleware.go过滤实现V1 chunk 级 / V2 stream 级pkg/labelaccess/request_chunk_filterer.go、pkg/labelaccess/request_stream_filterer.go策略与匹配器的 protobuf 风格类型定义pkg/labelaccess/types/label.go多租户文档multi-tenancy以仓库实际路径为准【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考