Loki Operator 完全指南:在 Kubernetes 中原生部署与自动化管理 Loki 日志栈
Loki Operator 完全指南:在 Kubernetes 中原生部署与自动化管理 Loki 日志栈
导读:本文基于 Loki 仓库中 operator/docs/prologue/introduction.md 展开,系统介绍 Loki Operator 的项目定位、核心能力与快速上手路径。Loki Operator 是 Grafana Loki SIG 提供的 Kubernetes Operator,用于以 Kubernetes 原生方式部署与管理 Loki 及其关联的日志组件(告警规则、记录规则、多租户网关等)。读完本文,你将掌握 Loki Operator 解决的问题、它提供的 Kubernetes 自定义资源(CRD)、如何通过一条命令在 kind 集群上拉起整套 LokiStack,以及如何按多租户模式、存储、副本等维度做精细化配置。
Loki Operator 是什么
Loki Operator 提供对 Loki 及相关日志组件的 Kubernetes 原生部署和管理能力。它的目标非常明确:简化和自动化 Kubernetes 集群中 Loki 日志栈的配置——将原本需要手工编写一大份 Loki 配置、逐组件部署 StatefulSet/Deployment/Service 的繁琐工作,收敛为对一组 Kubernetes 自定义资源(Custom Resources)的声明式描述。
从仓库结构看,Loki Operator 是一个独立于 Loki 主程序的子项目,位于 operator/ 目录下,拥有自己独立的 go.mod、Makefile 与 Dockerfile,并通过 operator/quickstart.sh 提供一键式的本地演示环境搭建。项目的入口组件由 operator/cmd/loki-operator/ 提供,其核心控制器与 Manifest 渲染逻辑分别位于 operator/internal/controller/ 与 operator/internal/manifests/ 中。
为什么需要 Operator 来部署 Loki
Loki 在生产环境中往往以多组件形态运行(distributor、ingester、querier、compactor、ruler、gateway 等),每个组件都有独立的镜像、资源配额、存储挂载、探针与网络策略。纯手工部署时,需要维护大量 YAML 且难以应对升级、扩缩容和故障恢复。Operator 模式则把"期望状态"写入 CRD,由控制器负责持续调和(reconcile),把人工运维知识固化为可版本化、可审计的代码逻辑。
核心能力一:Kubernetes 自定义资源(CRD)
Loki Operator 的 API 组为 loki.grafana.com,主要 CRD 定义位于 operator/config/crd/(共 11 个 YAML 文件),其 Go 类型定义在 operator/api/loki/v1/ 与 v1beta1 版本目录中。官方 API 文档见 operator/docs/operator/api.md(该文档由 gen-crd-api-reference-docs 自动生成)。
通过自定义资源,用户可以声明式地部署和管理:
- LokiStack:一个完整的 Loki 日志栈实例,聚合了存储、租户、大小规格(size)、复制因子、Gateway 等核心配置;
- AlertingRule / RecordingRule:以 Kubernetes 原生资源定义 Loki 的告警规则与记录规则,由内置的 ruler 组件消费(相关设计文档见 operator/docs/enhancements/ruler_support.md);
- RulerConfig:配置 ruler 与 Alertmanager 的连接(含 TLS、Basic Auth、Header Auth、DNS 发现等);
- LokiStack 附属组件:如网关(gateway)、存储大小计算器(storage-size-calculator)等。
以 AlertingRule 为例,从 operator/docs/operator/api.md 可以看到其核心结构:spec.tenantID 指定规则在哪个租户内评估,spec.groups 定义规则组(组名全局唯一、可设评估 interval 与告警数量 limit),每个规则由 LogQL 表达式 expr、持续时间 for、labels 与 annotations 组成——这与 Prometheus 告警规则的心智模型保持一致,但表达式是 LogQL 而非 PromQL。
说明:告警规则、记录规则相关能力是后续版本逐步引入的,其演进思路可参考 operator/docs/enhancements/ 下的增强提案文档(如
ruler_support.md)。
核心能力二:简化部署配置
Loki Operator 的第二个核心能力是"用原生 Kubernetes 资源表达 Loki 的运维基本面"。用户在 LokiStack 的 spec 中即可配置:
- 租户(tenants):静态定义租户、角色、角色绑定,或委托给外部 OPA / OpenShift OAuth(详见下文"多租户模式");
- 限制(limits):通过
limits配置每租户的查询/写入限额与拦截规则(BlockedQuerySpec支持按 pattern 或正则精确拦截特定查询); - 复制因子(replication factor):控制写入数据的副本数,保障可用性;
- 存储(storage):通过
storage.schemas声明 schema 版本与生效日期,通过storage.secret指向存放对象存储凭证的 Secret(支持 S3、Azure、GCS 等),详见 operator/docs/lokistack/object_storage.md; - 大小规格(size):如
1x.pico、1x.demo、1x.small等,一键决定各组件的副本数与资源配额(规格枚举定义见 operator/docs/operator/api.md 的LokiStackSizeType)。
此外,Loki Operator 还提供**特性开关(Feature Gates)**体系来按需裁剪能力(如是否部署 Gateway、是否启用保留策略等),具体配置方式与各开关含义见 operator/docs/operator/feature-gates.md。保留策略与区域感知复制等高级能力的设计见 operator/docs/enhancements/retention_support.md 与 operator/docs/enhancements/zone_aware_replication.md。
快速开始:一条命令拉起 LokiStack
环境要求
最便捷的起步方式是使用 Kubernetes kind)。
从仓库直接部署
在克隆本仓库后,进入 operator/ 目录执行:
make quickstart
该命令会基于 operator/quickstart.sh 在本地 kind 集群中完成:创建集群、加载/构建镜像、部署 Operator 并创建示例 LokiStack,用于演示目的。清理环境使用:
make quickstart-cleanup
使用自定义镜像测试本地改动
如果你想验证自己 fork 的代码改动,需要提供一个属于你的镜像仓库组织(registry organization),且镜像仓库名必须为 loki-operator(例如 quay.io/my-company-org/loki-operator)。在 operator/Makefile 中,镜像名由 REGISTRY_BASE 推导(默认 docker.io/grafana,OpenShift 场景为 quay.io/openshift-logging):
make oci-build oci-push quickstart REGISTRY_BASE=quay.io/my-company-org
其中 oci-build 负责构建镜像,oci-push 负责推送到指定 registry,随后 quickstart 使用新镜像拉起整套环境。
提示:不希望在 kind/OpenShift 上反复部署 Operator 的本地开发与调试场景,可以参考 operator/docs/operator/hack_operator_make_run.md 中
make run的用法;需要完整的分步 hack 指南(kind 与 OpenShift 两种环境、常见故障排查)见 operator/docs/operator/hack_loki_operator.md。
深入:一个完整的 LokiStack 配置示例
结合多租户文档 operator/docs/user-guides/tenancy-modes.md,下面是一个"静态租户 + OIDC 认证 + 进程内 OPA 授权"的完整示例:
apiVersion: loki.grafana.com/v1
kind: LokiStack
metadata:
name: lokistack-dev
namespace: loki
spec:
size: 1x.pico
storage:
schemas:
- version: v13
effectiveDate: 2023-10-15
secret:
name: loki-storage
type: s3
storageClassName: standard
tenants:
mode: static
authentication:
- tenantName: team-a
tenantId: team-a
oidc:
issuerURL: https://auth.example.com
redirectURL: https://loki.example.com/oidc/team-a/callback
groupClaim: groups
usernameClaim: email
secret:
name: team-a-oidc-secret
authorization:
roles:
- name: read-write
resources:
- logs
tenants:
- team-a
permissions:
- read
- write
roleBindings:
- name: team-a-binding
roles:
- read-write
subjects:
- kind: group
name: team-a-developers
要点拆解:
size: 1x.pico选择最小规格,适合开发验证;storage.schemas声明 schema 版本v13及其生效日期,storage.secret引用名为loki-storage的 Secret 与存储类型s3;tenants.mode: static启用静态多租户;authentication配置租户team-a的 OIDC 信息(Issuer、回调地址、组/用户声明映射);authorization.roles与roleBindings静态声明"读+写"权限并绑定到team-a-developers这个用户组。
从源码结构看,LokiStackSpec 的完整字段定义(含 size、storage、tenants、limits、rules、gateway 等)位于 operator/docs/operator/api.md 的自动生成 API 文档中,是排查配置错误的第一参考。
多租户模式:五种部署形态怎么选
LokiStack Gateway 是负责认证、授权与多租户访问的专用组件,支持以下五种模式(详见 operator/docs/user-guides/tenancy-modes.md):
| 模式 | 认证 | 授权 | 适用场景 |
|---|---|---|---|
static |
OIDC / mTLS | 进程内 OPA | 授权方案静态、租户与角色固定 |
dynamic |
OIDC / mTLS | 外部 OPA 端点 | 授权策略动态变化、需外置决策 |
passthrough |
mTLS | 无(外部组件代做) | 由外部组件透传 X-Scope-OrgID 头 |
openshift-logging |
OpenShift OAuth | 外部 OPA + OpenShift RBAC | OpenShift Logging 产品的日志存储 |
openshift-network |
OpenShift OAuth | 外部 OPA + OpenShift RBAC | OpenShift Network Observability 的网络追踪存储 |
- static:租户、角色、角色绑定全部写死在 LokiStack 配置中,授权由进程内 OpenPolicyAgent(OPA)Rego 引擎执行;
- dynamic:把授权决策委托给外部 OPA 兼容端点(如
http://opa.loki.svc:8181/v1/data/loki/authz),策略更新无需重部署网关; - passthrough:认证/授权全部外置,网关仅依据客户端 mTLS 与
X-Scope-OrgID头识别租户;不关心授权的场景还可配置defaultTenant兜底; - openshift-logging / openshift-network:面向 OpenShift 产品形态的预配置模式,使用 OpenShift 内置 OAuth 与 RBAC,预置租户(
application、infrastructure、audit,或网络场景下的单一network租户),并支持通过adminGroups授予集群级日志访问权限。
另外需要说明:如果你完全不需要网关,也可以通过 FeatureGates 配置关闭 Gateway 组件,让日志客户端直接写入 distributor。相关配置与示例分别见 operator/docs/operator/feature-gates.md、operator/docs/user-guides/forwarding_logs_without_gateway.md(直接对接 distributor)与 operator/docs/user-guides/forwarding_logs_to_gateway.md(经网关转发,含 OpenShift Logging、Promtail、Fluentd 等客户端的接入步骤)。
兼容性与版本要求
根据 operator/docs/operator/compatibility.md:
- Kubernetes:Operator 通过 client-go 与集群通信,集群版本兼容性以 client-go 的兼容矩阵为准;由于使用 CRD 要求 Kubernetes >= v1.7.0,又因使用
apiextensions.k8s.io/v1版本 CRD,实际要求 Kubernetes >= v1.21.0; - Loki:当前 Operator 支持运行 v3.1.0 至 v3.7.x 的一系列 Loki 版本(如 v3.5.5、v3.6.5、v3.7.2、v3.7.3、v3.7.7 等)。
版本发布节奏与流程可参考 operator/docs/operator/release.md。
从入门到实战的阅读路径
- 快速体验:先执行
make quickstart,再阅读 operator/docs/prologue/quickstart.md 理解部署原理; - 理解 API:完整字段级参考见 operator/docs/operator/api.md,CRD 清单见 operator/config/crd/;
- 配置存储:对象存储(S3/Azure/GCS 等)的 Secret 与 schema 配置见 operator/docs/lokistack/object_storage.md;
- 接入日志:经网关转发(OpenShift Logging / Promtail / Fluentd)见 forwarding_logs_to_gateway.md,直连 distributor 见 forwarding_logs_without_gateway.md;
- 连接 Grafana:查询与可视化的接入步骤见 operator/docs/user-guides/howto_connect_grafana.md;
- 生产加固:网关外部访问与 Ingress 配置见 operator/docs/user-guides/gateway-config.md,网络策略见 operator/docs/user-guides/network_policies.md,OpenTelemetry 接入见 operator/docs/user-guides/open-telemetry.md。
综上,Loki Operator 以"声明式 CRD + 控制器调和"的方式,把 Loki 日志栈的部署、配置与运维工作标准化:小到一条 make quickstart 拉起本地演示环境,大到在 OpenShift 产品级环境中以静态/动态/透传等多种租户模式承载多团队日志,都可以在统一的 loki.grafana.com API 体系下完成。