企业官网建设流程全解析

Loki Operator 特性开关（Feature Gates）完整指南：从 ProjectConfig 到 OpenShift 平台集成的配置详解

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

本指南围绕 Loki Operator（位于 operator 目录）的FeatureGatesAPI 类型展开，系统讲解其在config.loki.grafana.com/v1组下的全部字段定义、在controller_manager_config.yaml中的真实配置写法，以及各开关在源码中的落地方式。读完本文，你将掌握如何在社区版与 OpenShift 发行版中逐项开启/关闭 Loki Operator 的监控、加密、Webhook、网关与平台集成能力，并理解内置证书管理（BuiltInCertManagement）的轮换语义与 TLS 安全档位（TLSProfile）的选型。

一、Feature Gates 是什么

Loki Operator 通过一组特性开关（Feature Gates）来控制其行为能力——例如是否创建 ServiceMonitor、是否为 HTTP/gRPC 服务启用 TLS、是否安装准入校验 Webhook、是否启用多租户网关等。这些开关不属于 LokiStack 自定义资源（CR），而是由 Operator 自身的ProjectConfig配置承载。

从源码结构看（operator/api/config/v1/projectconfig_types.go），FeatureGates是一个 Go 结构体，字段以 JSON 标签暴露，其中包含布尔开关、嵌套结构体（BuiltInCertManagement、OpenShiftFeatureGates）以及字符串类型（TLSProfile）。该结构体挂在ProjectConfig之下：

// ProjectConfig is the Schema for the projectconfigs API type ProjectConfig struct { metav1.TypeMeta `json:",inline"` ControllerManagerConfigurationSpec `json:",inline"` Gates FeatureGates `json:"featureGates,omitempty"` }

ProjectConfig的配置载体是 Operator 启动时挂载的controller_manager_config.yaml，在 operator/config/overlays 下有community、community-openshift、development、openshift四套 overlay，均包含featureGates配置块。

官方文档说明：本文所依据的 operator/docs/operator/feature-gates.md 是由gen-crd-api-reference-docs自动生成的 API 参考页（见 operator/config/docs/config.json 中的docsURLTemplate指向该页），因此字段注释与源码注释一一对应，可以放心作为配置依据。

二、如何配置 Feature Gates：controller_manager_config.yaml

Feature Gates 通过 Operator 的ProjectConfig配置启用。社区版（communityoverlay）的 controller_manager_config.yaml 展示了一个最小可用示例：

apiVersion: config.loki.grafana.com/v1 kind: ProjectConfig health: healthProbeBindAddress: :8081 metrics: bindAddress: :8080 secure: false webhook: port: 9443 leaderElection: leaderElect: true resourceName: loki-operator.grafana.com featureGates: # # Component feature gates # lokiStackGateway: true restrictedPodSecurityStandard: false # # Webhook feature gates # lokiStackWebhook: true alertingRuleWebhook: true recordingRuleWebhook: true

注意：未显式声明的开关默认即为false（关闭）。配置项采用camelCase形式，与 JSON 标签一一对应。例如builtInCertManagement是一个嵌套对象而非布尔值。

三、组件与监控类 Feature Gates

3.1 lokiStackGateway

• 类型：bool
• 作用：启用对反向代理组件lokistack-gateway的调和（reconcile），实现多租户下对 Loki 的认证/授权流量控制。关闭时 Operator 不会创建该网关组件。

网关的租户配置、ServiceMonitor 生成逻辑可在 operator/internal/manifests/gateway_tenants.go 中看到，其执行前提正是opts.Gates.OpenShift.Enabled与网关相关开关。

3.2 serviceMonitors

• 类型：bool
• 作用：为每个 LokiStack 组件创建一个由 Prometheus-Operator 托管的ServiceMonitor资源，用于抓取组件指标。

3.3 serviceMonitorTlsEndpoints

• 类型：bool
• 作用：为上述ServiceMonitor的 endpoints 启用TLS。该开关通常与serviceMonitors一起使用，在 operator/internal/manifests/gateway_tenants.go 中通过openshift.ConfigureGatewayServiceMonitor(sm, opts.Gates.ServiceMonitorTLSEndpoints)落地。

3.4 lokiStackAlerts

• 类型：bool
• 作用：创建由 Prometheus-Operator 托管的PrometheusRules，内置常见的 Loki 告警规则。

3.5 grafanaLabsUsageReport

• 类型：bool
• 作用：启用 Grafana Labs 的 Loki 用量上报（usage reporting）能力。文档注释指向 Loki v2.5 版本的 usage-reporting 说明，社区 overlay 中默认关闭（false），OpenShift overlay 中同样关闭。

3.6 restrictedPodSecurityStandard

• 类型：bool
• 作用：使 Operator 生成的 Pod 符合 Kubernetes受限 Pod 安全标准（Restricted Pod Security Standard）。开启后会在工作负载上应用更严格的securityContext约束。社区 overlay 中为false，OpenShift overlay 中为true。

3.7 defaultNodeAffinity

• 类型：bool
• 作用：开启后 Operator 会为所有 Pod设置默认的节点亲和性（node affinity），将 Pod 调度限制在Linux 节点上。该开关影响所有工作负载的调度行为，适合对节点 OS 有明确要求的集群。

四、加密类 Feature Gates：HTTP/gRPC TLS 与内置证书管理

加密类开关是 LokiStack 数据面安全的核心，涉及三组能力：HTTP 加密、gRPC 加密、内置证书管理。

4.1 httpEncryption 与 grpcEncryption

• 类型：均为bool
• 作用：
  • httpEncryption：为所有 LokiStackHTTP 服务启用 TLS 加密；
  • grpcEncryption：为所有 LokiStackgRPC 服务启用 TLS 加密。

启用前提（务必注意）：开启后，每个服务需要一个与服务同名的 Secret，包含以下数据：

同时，每个服务还需要一个以 LokiStack CR 名称 +-ca-bundle后缀命名的 ConfigMap（例如lokistack-dev-ca-bundle），包含：

换句话说，仅开启开关还不够，你必须事先为每个服务准备好证书 Secret 与 CA Bundle ConfigMap，Operator 才能正确配置 TLS。

4.2 builtInCertManagement（内置证书管理）

• 类型：BuiltInCertManagement（嵌套结构体，非布尔值）
• 作用：启用 Operator内置的证书生成与轮换设施，为所有 LokiStack 服务及内部客户端生成并轮换 TLS 客户端/服务端证书（lokistack-gateway 除外）。开启后，Loki 内部所有 HTTP 与 gRPC 通信都将提升为mTLS。

对于 lokistack-gateway 的证书，需要你自己提供 Secret，或在 OpenShift 上使用ServingCertsService能力（见下文 OpenShift 部分）。

嵌套结构体字段详解（源码定义）

OpenShift overlay（operator/config/overlays/openshift/controller_manager_config.yaml）给出了官方推荐取值，可直接参考：

builtInCertManagement: enabled: true # CA certificate validity: 5 years caValidity: 43830h # CA certificate refresh at 80% of validity caRefresh: 35064h # Target certificate validity: 90d certValidity: 2160h # Target certificate refresh at 80% of validity certRefresh: 1728h

换算关系：

• 43830h≈ 5 年（CA 有效期）；35064h= 43830 × 80%（CA 在 4 年时轮换）；
• 2160h= 90 天（目标证书有效期）；1728h= 2160 × 80%（证书在 72 天时轮换）。

这种"80% 轮换"策略保证证书在过期前完成滚动更新，避免因证书过期导致集群内部通信中断。证书轮换、过期检查的调和逻辑分别位于 operator/internal/handlers/lokistack_rotate_certs.go 与 operator/internal/handlers/lokistack_check_cert_expiry.go。

4.3 tlsProfile（TLS 安全档位）

• 类型：string
• 作用：选择 TLS 安全档位（profile），在使用httpEncryption或grpcEncryption时强制执行。

可选值定义于 operator/api/config/v1/projectconfig_types.go 的TLSProfileType常量，基于 Mozilla 的 TLS 定义：

该配置最终会转换成具体的密码套件与最低 TLS 版本：在 operator/internal/manifests/options.go 中，TLSProfileSpec携带Ciphers（握手协商的密码套件列表）与MinTLSVersion（最低 TLS 协议版本），TLSCipherSuites()方法将密码套件切片以逗号拼接成 Loki 配置所需的字符串。

五、Webhook 类 Feature Gates

Operator 内置了 4 个与准入校验/转换 Webhook 相关的开关，社区 overlay 默认开启前三个：

这组开关在社区 overlay 中rulerConfigWebhook未显式声明（默认关闭），在 OpenShift overlay 中全部为true。Webhook 端口由ProjectConfig顶层的webhook.port（默认9443）决定。

六、OpenShift 专属 Feature Gates

openshift字段是一个嵌套结构体OpenShiftFeatureGates（源码定义），仅支持在 OpenShift 平台上使用，其内部还有一个总开关：

其中TokenCCOAuthEnv是只读/自动探测字段（源码中没有json标签，且不对外暴露配置），由 Operator 根据运行环境自动判断，用户无需也无法手动配置。

七、端到端配置示例：OpenShift 全量开关

operator/config/overlays/openshift/controller_manager_config.yaml 展示了完整启用的参考配置，覆盖监控、加密、组件、Webhook 与 OpenShift 五组能力，可直接对照自己的集群逐项取舍：

apiVersion: config.loki.grafana.com/v1 kind: ProjectConfig health: healthProbeBindAddress: :8081 metrics: bindAddress: :8443 secure: true webhook: port: 9443 leaderElection: leaderElect: true resourceName: loki-operator.grafana.com featureGates: # # Monitoring feature gates # serviceMonitors: true serviceMonitorTlsEndpoints: true lokiStackAlerts: true # # Encryption feature gates # httpEncryption: true grpcEncryption: true builtInCertManagement: enabled: true # CA certificate validity: 5 years caValidity: 43830h # CA certificate refresh at 80% of validity caRefresh: 35064h # Target certificate validity: 90d certValidity: 2160h # Target certificate refresh at 80% of validity certRefresh: 1728h # # Component feature gates # lokiStackGateway: true grafanaLabsUsageReport: false restrictedPodSecurityStandard: true defaultNodeAffinity: true # # Webhook feature gates # lokiStackWebhook: true alertingRuleWebhook: true recordingRuleWebhook: true rulerConfigWebhook: true # # OpenShift feature gates # openshift: enabled: true servingCertsService: true ruleExtendedValidation: true clusterTLSPolicy: true clusterProxy: true dashboards: true

需要注意：本示例中metrics.secure: true且监听:8443，与社区版的非安全指标端口不同；同时未声明tlsProfile（此时按 Operator 默认行为处理）。若需限定 TLS 档位，可在featureGates下追加tlsProfile: Intermediate或Modern/Old。

八、Feature Gates 的源码落地路径

理解开关如何从配置流到最终资源，有助于排查"开关已开但未生效"的问题。从源码结构看，整条链路大致如下：

1. 定义：operator/api/config/v1/projectconfig_types.go 定义FeatureGates及其全部字段，ProjectConfig.Gates承载实例；深度拷贝实现位于 operator/api/config/v1/zz_generated.deepcopy.go。
2. 加载：Operator 启动时读取controller_manager_config.yaml（各 overlay 见 operator/config/overlays），反序列化为ProjectConfig。
3. 传递：开关随Options.Gates传入 manifests 生成层，见 operator/internal/manifests/options.go 中Gates configv1.FeatureGates字段。
4. 消费：各 manifest 构建函数按需读取开关——例如网关租户与 ServiceMonitor 配置（operator/internal/manifests/gateway_tenants.go）、网关处理器（operator/internal/handlers/internal/gateway/gateway.go）、存储处理器（operator/internal/handlers/internal/storage/storage.go）。
5. 特殊逻辑：证书轮换与过期检查分别由 operator/internal/handlers/lokistack_rotate_certs.go 与 operator/internal/handlers/lokistack_check_cert_expiry.go 驱动，并在 operator/internal/handlers/lokistack_rotate_certs_test.go、operator/internal/handlers/lokistack_check_cert_expiry_test.go 中有对应测试覆盖。

九、配置速查与建议

实践要点：

• 逐项验证依赖：serviceMonitorTlsEndpoints依赖serviceMonitors；tlsProfile只有在开启httpEncryption/grpcEncryption时才被强制执行；builtInCertManagement与手工提供证书的httpEncryption/grpcEncryption属于两条不同路线，注意区分。
• Secret 与 ConfigMap 先行：手工加密模式下，每个服务必须先就绪tls.crt/tls.keySecret 与<CR 名>-ca-bundleConfigMap，否则服务无法正常启动。
• 以 overlay 为基准：社区版请参考 community 配置，OpenShift 版请参考 openshift 配置，其中已包含经过验证的证书轮换时长取值。

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