企业官网建设流程全解析

Loki Operator 兼容性指南：支持的 Kubernetes 与 Loki 版本全解析

【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki

Loki Operator（Grafana Loki 展开，结合 operator/go.mod、operator/config/crd/bases/loki.grafana.com_lokistacks.yaml 等源码与清单文件，帮助你准确判断"当前集群能否运行该 Operator""该 Operator 能部署哪个版本的 Loki"，并为升级路径提供可验证的依据。

兼容性总览：两个独立的版本维度

Loki Operator 的兼容性声明围绕两个维度展开：

1. Kubernetes 集群版本：决定 Operator 能否在目标集群上安装、运行，主要由 Operator 依赖的client-go库版本与所用 CRD API 版本决定；
2. Loki 发行版本：决定 Operator 能够以何种镜像版本部署和接管 Loki 组件，由 Operator 内置的版本支持列表与默认镜像决定。

官方文档给出的结论是："The Loki Operator supports a number of Kubernetes and Loki releases."（Loki Operator 支持一系列 Kubernetes 与 Loki 发行版本）。下面分别展开。

Kubernetes 集群版本兼容性

client-go 决定兼容边界

Loki Operator 通过client-go（Kubernetes 官方 Go 客户端库）与 Kubernetes API Server 通信，因此集群版本支持范围本质上由client-go的兼容矩阵决定——即"client-go 声明支持的 Kubernetes 版本区间，就是 Operator 可以正常工作的区间"。

文档特别强调，除此之外的额外兼容性（例如在更老或更新的集群上偶然可用）仅属"尽力而为"（best effort），官方不做承诺。这意味着：

• 若集群版本在client-go支持范围内，可视为官方支持；
• 若不在范围内但恰好能运行，属于"碰巧可用"，不受保证。

当前仓库实际使用的 client-go 版本

文档撰写时记录的client-go版本为v0.23.5，但以当前仓库实际依赖为准：在 operator/go.mod 中，k8s.io/client-go已锁定为v0.35.3，同时配套依赖：

• k8s.io/api v0.35.3
• k8s.io/apimachinery v0.35.3
• k8s.io/apiserver v0.35.3
• k8s.io/component-base v0.35.3
• sigs.k8s.io/controller-runtime v0.23.3

也就是说，当前主线代码的集群兼容边界由client-go v0.35.3（及 controller-runtime v0.23.3）对应的官方兼容矩阵决定。在规划集群版本时，应以你将要部署的 Operator 版本所对应的go.mod实际依赖为准，而不是依赖过时的文档快照。这也是"以仓库实际内容为准"的典型场景。

CRD API 版本带来的两个硬性门槛

除了client-go，CRD 的 API 版本还设置了两个明确的最低集群版本门槛：

其中第二条是当前的实际硬约束。可以在仓库中直接验证：Operator 生成的 CRD 清单头部即为apiVersion: apiextensions.k8s.io/v1，例如 operator/config/crd/bases/loki.grafana.com_lokistacks.yaml 第 2 行，以及 operator/bundle/community/manifests/loki.grafana.com_lokistacks.yaml 等 bundle 清单；Operator 定义的 API 组为loki.grafana.com，其类型文档可在 operator/docs/operator/api.md 中查阅（该页面由gen-crd-api-reference-docs自动生成）。

结论：实际部署时，集群版本应同时满足client-go兼容区间与>= v1.21.0两条约束；前者决定了"能跑得多稳"，后者决定了"能不能装"。

Loki 版本兼容矩阵

完整支持列表

Loki Operator 明确声明可与之配合运行的 Loki 版本如下（来自 operator/docs/operator/compatibility.md，均为 v3.x 系列）：

• v3.1.0
• v3.1.1
• v3.2.0
• v3.2.1
• v3.3.2
• v3.4.2
• v3.4.3
• v3.5.4
• v3.5.5
• v3.6.5
• v3.7.2
• v3.7.3
• v3.7.7

该列表覆盖了从 v3.1 到 v3.7 的主要补丁版本。列表语义是"这些版本的 Loki 可以（被 Operator）运行"（The versions of Loki compatible to be run with the Loki Operator are），因此：

• 选择列表内版本：官方保证的兼容区间；
• 选择列表外版本：不属于声明范围，需自行验证或等待 Operator 后续版本更新支持。

默认镜像与支持列表的对应关系

支持列表并非孤立的文字声明，而是落地在 Operator 的发布产物中。在 Operator 的 ClusterServiceVersion（CSV）清单里，可以找到与支持列表一致的默认 Loki 镜像：

• operator/bundle/community/manifests/loki-operator.clusterserviceversion.yaml 中默认镜像为docker.io/grafana/loki:3.7.7；
• operator/bundle/openshift/manifests/loki-operator.clusterserviceversion.yaml 中默认镜像为quay.io/openshift-logging/loki:v3.7.7；
• 对应各 overlay 的镜像补丁，例如 operator/config/overlays/community/manager_related_image_patch.yaml。

可见，当前发布线把v3.7.7作为默认部署的 Loki 版本，与兼容列表的最新条目保持一致。这也给出一个实用提示：若要运行列表内较旧版本（如 v3.1.0），需要显式指定对应的 Loki 镜像，Operator 不会默认回退到旧版本。

兼容性如何落地：从依赖到产物

理解兼容性声明后，可以顺着仓库把"文档 -> 依赖 -> 清单产物"的链路串起来，方便你在实际排障或升级时定位证据。

1. 依赖层：operator/go.mod

operator/go.mod 是整个兼容性声明的根：

• k8s.io/client-go v0.35.3：决定 Kubernetes 集群兼容区间（见上文）；
• github.com/grafana/loki/v3 v3.7.1：Operator 以 Go 模块方式依赖 Loki v3.7.1，作为版本支持的代码级锚点；
• sigs.k8s.io/controller-runtime v0.23.3：Operator 的控制器框架，其版本与client-go版本联动。

2. CRD 层：config/crd 与 bundle/manifests

Operator 的四个 CRD 均使用apiextensions.k8s.io/v1：

• loki.grafana.com_lokistacks.yaml（核心的 LokiStack 自定义资源）
• loki.grafana.com_alertingrules.yaml
• loki.grafana.com_recordingrules.yaml
• loki.grafana.com_rulerconfigs.yaml

它们同时存在于 operator/config/crd/bases/（kustomize 源）与 operator/bundle/community/manifests/（OLM bundle 产物）中，二者应保持同步。

3. 发布层：bundle 生成与版本管理

Operator 的发布流程（详见 operator/docs/operator/release.md）包括：更新 Operator 版本号并执行make bundle-all重新生成 bundle 清单、更新CHANGELOG.md、打 release 标签，以及向社区 OperatorHub 仓库提交 bundle。这意味着每次支持新的 Loki 版本，都会同步反映到 CSV 的默认镜像与支持文档中——因此判断"当前 Operator 支持哪个 Loki 版本"时，把 compatibility.md 与 CSV 清单对照阅读是最可靠的姿势。

使用建议与注意事项

综合文档与源码，落地到实际运维时有几点值得留意：

1. 集群版本评估顺序：先确认集群>= v1.21.0（apiextensions.k8s.io/v1硬门槛），再对照所部署 Operator 版本的go.mod中client-go版本的官方兼容矩阵确认区间。文档中记录的v0.23.5属历史快照，当前仓库主线已升级到v0.35.3，务必以实际部署版本为准。
2. Loki 版本选择：优先选择兼容列表内的版本；默认部署为 v3.7.7，如需旧版本须显式指定镜像，且旧版本属于声明区间内方可视为受支持。
3. "尽力而为"的边界：不在声明区间内的组合并非一定不可用，但官方不做承诺，生产环境应避免依赖这种偶然兼容。
4. 升级前对照三处：compatibility.md的支持列表、CSV 中的默认镜像、go.mod中的依赖版本，三者一致时兼容性声明才完整成立。

通过本文梳理的"文档 + go.mod + CRD + CSV"四方证据链，你可以准确回答两个最核心的问题：我的集群能不能装这个 Operator？它能管哪个版本的 Loki？

【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki