Loki Operator API 完全指南：LokiStack 与 Ruler 系列 CRD 类型逐项解析

Loki Operator API 完全指南LokiStack 与 Ruler 系列 CRD 类型逐项解析【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki本文依据 operator/docs/operator/api.md由gen-crd-api-reference-docs自动生成的 Loki Operator API 参考文档整理而成。这份文档定义了 Loki Operator 对外暴露的全部自定义资源CRD类型涵盖loki.grafana.com/v1与loki.grafana.com/v1beta1两个 API 组。通过阅读本文你将系统掌握LokiStack集群编排、AlertingRule/RecordingRule规则、RulerConfig告警与 remote-write 配置以及 Gateway 多租户认证授权的完整字段语义从而能够直接编写和校验生产可用的 CR 清单。文档背景自动生成的操作符 API 契约该 API 参考文档是 Loki Operator 向用户暴露的类型契约总览其内容全部来自 operator/api/loki/v1 目录下的 Go 类型定义lokistack_types.go、alertingrule_types.go、recordingrule_types.go、rulerconfig_types.go等通过gen-crd-api-reference-docs工具自动渲染。文档将类型分为两个版本组loki.grafana.com/v1当前主版本包含 70 余个类型定义loki.grafana.com/v1beta1旧版兼容组字段语义与 v1 基本一致但缺少部分 v1 新增字段例如TenantsSpec中 v1beta1 没有openshift、passthrough、disableIngress、gateway等子配置。文中所有字段均标注了(Optional)可选或必填无标注(Appears on:)则指明该类型在哪些父类型中被引用便于逆向梳理对象树。下文以 v1 为主版本展开并在必要时说明 v1beta1 的差异。顶层资源类型用户实际编写的 CR 对象v1 组共定义 4 类顶层资源类型可直接作为kind使用它们是用户与 Operator 交互的入口资源类型用途对应源码LokiStackLoki 集群实例的声明式编排规格 状态operator/api/loki/v1/lokistack_types.goAlertingRule基于 LogQL 的告警规则operator/api/loki/v1/alertingrule_types.goRecordingRule基于 LogQL 的预计算记录规则operator/api/loki/v1/recordingrule_types.goRulerConfigruler 组件的告警通知与 remote-write 全局配置operator/api/loki/v1/rulerconfig_types.go每个资源均遵循 Kubernetes 惯例metadata引用 Kubernetesmeta/v1.ObjectMeta、spec期望状态与status观测状态通常包含conditions条件列表。LokiStack集群实例的编排核心LokiStack是 Operator 管理的核心资源其spec定义了整个 Loki 集群的部署形态。以下按功能域拆解LokiStackSpec的全部字段。基础规格管理状态与集群规模managementStateManagementStateType可选定义 CR 是否由 Operator 接管默认Managed。取值为ManagedOperator 正常协调该资源UnmanagedOperator 不协调用户自行管理。sizeLokiStackSizeType必填声明 Loki 部署的规模档位是集群资源与高可用能力的一键开关。源码 operator/api/loki/v1/lokistack_types.go#L28-L73 中的枚举如下取值语义1x.demo极小资源需求、无 HA 支持面向笔记本单节点集群的轻量测试/演示/原型无任何性能保证严禁用于生产1x.pico极小资源需求不要求单副本因子与自动压缩1x.extra-small超小资源需求不要求单副本因子与自动压缩1x.small小资源需求不要求单副本因子与自动压缩1x.medium小资源需求要求单副本因子与自动压缩每个档位对应的默认资源 requests/limits 与 PVC 大小在 operator/internal/manifests/internal/sizes.go 的resourceRequirementsTable中定义例如1x.pico的 querier 默认请求750mCPU 与1.5Gi内存demo 档所有组件 PVC 均为10Gi。operator-sdk 的 CSV 描述符显示1x.demo未出现在size的可选项 UI 中进一步印证其仅供测试。存储对象存储端点与 SchemastorageClassNamestring必填ingester/querier 的 PVC 存储类。storageObjectStorageSpec必填日志持久化后端包含三个子字段schemas[]ObjectStorageSchema读写日志的存储 schema 列表默认[{version:v11, effectiveDate:2020-10-11}]至少 1 项。每个 schema 由version与effectiveDate组成versionObjectStorageSchemaVersionv11、v12、v13effectiveDateStorageSchemaEffectiveDateYYYY-MM-DD格式、按UTC时区解释。文档特别强调两条规则新建 LokiStack 时建议用最新版本 昨天作为生效日期保证配置始终存在当前有效的 schema新增 schema 版本必须放在未来以便跨天后 Loki 自动切换。secretObjectStorageSecretSpec必填与 LokiStack 同命名空间的对象存储认证 Secret。其typeObjectStorageSecretType可选azure、gcs、s3、swift、alibabacloudcredentialModeCredentialMode可选可显式指定认证模式不设置时 Operator 会依据 Secret 内容与自身配置自动推断staticSecret 中长期凭据默认模式所有存储类型均支持token从凭据源获取短期令牌静态配置不包含凭据可做到更细粒度控制并非所有存储类型都支持token-cco类似 token但凭据源由环境配置依赖 Cloud Credential Operator 提供 Secret仅在特定环境与存储类型组合下支持。tlsObjectStorageTLSSpec可选到达对象存储端点的 TLS 配置复用CASpeccaName必填、caKey可选caKey为空时默认service-ca.crtConfigMap 需与 LokiStack 同命名空间。proxyClusterProxy可选集群位于代理之后时的代理配置httpProxy/httpsProxy/noProxy分别对应HTTP_PROXY/HTTPS_PROXY/NO_PROXY环境变量注入。哈希环与复制hashRingHashRingSpec可选分布式哈希环配置。type目前仅支持memberlist默认memberlist.instanceAddrType可选default取 pod 首个私有网络接口地址RFC 1918/6598或podIP使用集群 Pod 网络公网 IPmemberlist.enableIPv6开启 IPv6 时强制instanceAddrType为podIP以避免本地地址查找。replicationFactorint32可选已弃用文档与源码均标注请改用replication.factor该字段将在未来版本移除。replicationReplicationSpec可选数据复制配置factorint32最小 1为流复制因子zones[]ZoneSpec用于 zone 感知部署每个ZoneSpec含maxSkew默认 1与topologyKey节点标签拓扑键源码强调复制因子必须小于等于可用 zone 数。状态中InsufficientIngesterReplicas这一 condition reason 也印证了ingester 副本数若小于等于复制因子pod 重启会导致日志摄取中断的约束。组件模板与调度templateLokiTemplateSpec可选允许对 8 个 Loki 组件compactor、distributor、ingester、querier、queryFrontend、gateway、indexGateway、ruler逐一覆盖调度配置每个组件使用LokiComponentSpecreplicas组件副本数nodeSelector节点标签选择tolerations节点污点容忍podAntiAffinityPod 反亲和调度规则。顶层useRequestsAsLimitsbool可选tech-preview 特性开启后operand Pod 的 limits 等于 requests形成资源硬上限但会削弱集群对摄入/查询负载尖峰的弹性。规则与限制rulesRulesSpec可选启用 ruler 组件enabled必填并支持selector选择要挂载的 LokiRules、namespaceSelector限定 PrometheusRules 发现范围不指定时仅使用 LokiStack 所在命名空间。limitsLimitsSpec可选限制配置分两层——globalLimitsTemplateSpec集群全局与tenantsmap[string]PerTenantLimitsTemplateSpec按租户覆盖。每层均含四个子块摄取限制IngestionLimitSpec单位均在字段中标注字段含义ingestionRate每秒摄取速率MBingestionBurstSize每个 distributor 副本的本地限速突发大小MB应至少等于单次 push 请求的最大日志体量maxLabelNameLength标签键最大字符数maxLabelValueLength标签值最大字符数maxLabelNamesPerSeries每条流最大标签数maxGlobalStreamsPerTenant集群范围内每租户最大活跃流数maxLineSize单行日志最大字节数perStreamDesiredRate自动流分片stream sharding的目标速率MB/秒perStreamRateLimit单流每秒最大字节速率MBperStreamRateLimitBurst单流最大突发字节MB查询限制QueryLimitSpecmaxEntriesLimitPerQuery单查询最大返回条目数、maxChunksPerQuery单查询最大拉取 chunk 数、maxQuerySeriesmetric 查询返回的最大唯一序列数、queryTimeout查询执行超时默认3m、cardinalityLimit索引查询基数上限、maxVolumeSerieslog-volume 响应最大聚合序列数。租户级PerTenantQueryLimitSpec在继承全部查询限制外还多了blocked[]BlockedQuerySpec查询拦截规则可按pattern精确匹配或regex正则匹配hash为查询串的 32 位 FNV-1 哈希拦截并用typesfilter/limited/metric限定拦截的查询类型。OTLP 属性映射OTLPSpec配置哪些 OpenTelemetry resource/scope/log 属性被转换为流标签streamLabels.resourceAttributes或直接丢弃drop未列出的属性将作为结构化元数据存储属性名必须使用 OpenTelemetry 规范名称。租户级 OTLP 配置会与全局配置合并。在 OpenShift 租户模式下openshift.otlp.enableConsoleLabels可为 OTLP 输入追加一组 OpenShift 日志控制台专用流标签k8s.container.name、k8s.pod.name、service.name等 12 个属性。保留期限RetentionLimitSpecdays必填最小 1为全局保留天数streams[]*RetentionStreamSpec可选支持按流覆盖——每个流保留规则含days必填、priority默认 1规则优先级与selector必填LogQL 流选择器。网络策略networkPoliciesNetworkPoliciesSpec可选的ruleSet决定 Operator 应用的网络策略规则集None不含任何策略等效于移除 Operator 创建的所有 NetworkPolicyRestrictIngressEgress创建仅放行经网关的查询与日志摄入、Loki 组件对对象存储的访问、LokiStack 组件间通信的策略。该配置的观测结果会写入status.networkPolicyStatusLokiStackNetworkPolicyStatus包含实际应用的ruleSet与允许访问对象存储的 TCP 出口端口objectStorageAllowedEgressPorts。多租户网关认证与授权tenantsTenantsSpec可选配置 lokistack-gateway 组件的多租户能力modeModeType必填默认openshift-logging决定整体策略static使用进程内 OpenPolicyAgent Rego 授权器断言authorization中的 Roles 与 RoleBindingsdynamic将授权委托给第三方 OPA 兼容端点authorization.opa.urlopenshift-logging为 OpenShift 的 application/infrastructure/audit 日志提供全自动集群内认证授权openshift-network仅面向 network 日志的全自动 OpenShift 认证授权passthrough网关以 mTLS 校验客户端后透传X-Scope-OrgID租户头。配套子配置包括authentication[]AuthenticationSpec逐租户认证每项包含tenantName、tenantId必填以及二选一的oidcOIDCSpecsecret引用同命名空间 Secret 存放 clientID/clientSecret、issuerURL必填、issuerCA、redirectURL、groupClaim/usernameClaim指定 ID Token 声明或mTLSMTLSSpec含ca自定义 CA。authorizationAuthorizationSpecopa.url第三方端点、rolesRoleSpecname、resources、tenants、permissions权限类型为read/write、roleBindingsRoleBindingsSpec将roles绑定到subjects主体kind为user/group。openshiftOpenshiftTenantSpecadminGroups定义管理员组默认system:cluster-admins、cluster-admin、dedicated-admin空数组即禁用与otlp.enableConsoleLabels。passthroughPassthroughTenantSpeccaValueReference自定义受信 CA 列表与defaultTenant未携带X-Scope-OrgID时的默认租户不设置则拒绝此类请求。disableIngress为 true 时不再自动创建网关的 Route/Ingress 外部访问资源。gatewayGatewaySpec网关服务器 TLStls.ca、tls.certificate、tls.privateKey其中证书与 CA 用ValueReference引用同命名空间 ConfigMap/Secret 的某个键——configMapName与secretName必须二选一且只能选一由 CRD 的 XValidation 规则强制私钥用SecretReference引用。状态字段可观测性LokiStackStatus向用户暴露三类观测信息componentsLokiStackComponentStatus按组件compactor/distributor/indexGateway/ingester/querier/queryFrontend/gateway/ruler聚合的PodStatusMap即map[PodStatus][]string的 pod 名分组PodStatus取值为Pending/Running/Ready/Failed/UnknownstorageLokiStackStorageStatus已应用的schemas列表与当前credentialModenetworkPolicyStatus已应用的网络策略规则集与对象存储出口端口conditions部署健康条件条件类型LokiStackConditionType为Ready/Pending/Failed/Degraded/Warning并配套 20 个LokiStackConditionReason包括ReadyComponents、FailedComponents、MissingObjectStorageSecret、InvalidObjectStorageSchema、InsufficientIngesterReplicas、MissingGatewayTenantSecret、MissingTokenCCOAuthenticationSecret、ReasonZoneAwareNodesMissing、StorageNeedsSchemaUpdateschema 版本低于 v13 时提示等可直接用于告警与排障。AlertingRule 与 RecordingRuleLogQL 规则对象两者结构几乎对称均用于把规则组提交给 ruler 加载执行通过LokiStack.spec.rules.selector关联挂载。AlertingRuleSchema foralertingrulesAPIspec.tenantIDstring必填规则求值所属租户spec.groups[]*AlertingRuleGroup规则组每个组含namestring组名必须在所有告警规则中唯一intervalPrometheusDuration可选规则求值周期limitint32可选单规则最多可产生的告警数0 表示不限rules[]*AlertingRuleGroupSpec组内规则每条含alertstring可选告警名必须是合法标签值exprstring必填的 LogQL 表达式每个求值周期在当前时间求值结果序列进入 pending/firingforPrometheusDuration可选持续满足多久才视为 firing未满时长前为 pendingannotations/labelsmap[string]string可选附加到每条告警的注解与标签。status.conditions[]meta/v1.Condition反映规则世代generation健康状态。RecordingRuleSchema forrecordingrulesAPI字段语义与告警规则一致差异仅在规则定义——recordstring可选为输出时序名必须是合法 metric 名expr为 LogQL 表达式labels附加到每条记录规则组级name需在所有记录规则中唯一limit限制单规则产生的序列数。RulerConfig告警通知与 remote-writeRulerConfigSchema forrulerconfigsAPI是独立于 LokiStack 的全局规则运行配置spec字段如下evaluationIntervalPrometheusDuration可选规则求值频率pollIntervalPrometheusDuration可选轮询新规则定义的频率alertmanagerAlertManagerSpec可选ruler 到 AlertManager 的连通配置endpoints[]string必填的 AlertManager URL 列表每个 URL 在配置中视为独立分组组内多实例 HA 可通过 DNS 发现discovery.enableSRVrefreshInterval控制刷新周期支持externalUrl告警回跳return pathURLexternalLabels附加到所有告警的标签enableV2使用 AlertManager v2 APInotificationQueue通知队列参数——capacity队列容量、timeout发送 HTTP 超时、forOutageTolerance容忍告警for状态中断恢复的最大时长、forGracePeriod告警与恢复for状态间的最小间隔仅对for大于宽限期的告警生效、resendDelay重发最小间隔relabelConfigs[]RelabelConfig告警标签重写RelabelConfig字段与 Prometheusmetric_relabel_configs对齐sourceLabels、separator默认;、targetLabel、regex默认(.*)、modulus、replacement默认$1、action默认replaceclientAlertManagerClientConfig客户端级配置支持tlscaPath/serverName/certPath/keyPath/insecureSkipVerify、headerAuthtype/credentials/credentialsFile后两者互斥、basicAuthusername/password。remoteWriteRemoteWriteSpec可选ruler 将记录规则指标外送的能力enabled开关refreshPeriod重配置刷新最小间隔clientRemoteWriteClientSpecname唯一名、url必填端点、timeout、authorizationbasic或bearer、authorizationSecretName授权 Secret存于授权 Secret 命名空间、additionalHeaders、relabelConfigs、proxyUrl、followRedirectsqueueRemoteWriteClientQueueSpeccapacity每 shard 缓冲样本数、maxShards/minShards并发度上下限、maxSamplesPerSend、batchSendDeadline缓冲最大等待、minBackOffPeriod初始重试延迟每次翻倍、maxBackOffPeriod最大重试延迟。overridesmap[string]RulerOverrides按租户覆盖目前支持逐租户覆盖alertmanager配置。status.conditions反映 RulerConfig 健康状态涉及凭据缺失MissingRulerSecret等 condition reason 亦在LokiStackConditionReason中统一定义。v1beta1 兼容组要点loki.grafana.com/v1beta1的类型骨架与 v1 完全一致LokiStack、AlertingRule、RecordingRule、RulerConfig及全部辅助类型但存在以下能力差异升级到 v1 前需注意TenantsSpec仅含mode、authentication、authorization缺少v1 的openshift、passthrough、disableIngress、gateway字段AlertManagerClientTLSConfig无insecureSkipVerify字段字段默认值以 v1 源码中的kubebuilder:default为准如queryTimeout3m、hashRing.typememberlist、managementStateManaged、zone.maxSkew1、retentionStream.priority1。编写 CR 的实践要点与排障速查综合文档与源码实际编写清单时建议遵循以下要点规模选择生产环境切勿使用1x.demo需要单副本因子与自动压缩时选择1x.medium否则在1x.pico/1x.extra-small/1x.small间按资源预算选择存储 Schema新集群使用最新 schemav13 昨天的生效日期未来升级 schema 时将新条目放在未来日期状态出现StorageNeedsSchemaUpdate表示当前 schema 低于 v13复制与 zonereplication.factor必须不大于 zone 数ingester 副本数必须大于复制因子否则会出现InsufficientIngesterReplicas导致滚动重启时摄取中断多租户static模式下 OPA Rego 授权器消费roles/roleBindingsdynamic模式必须提供authorization.opa.urlpassthrough模式若需允许无头请求需配置defaultTenant凭据引用ValueReference的configMapName与secretName二选一CRD XValidation 强制CA ConfigMap 默认键为service-ca.crt查询治理利用limits.tenants.id.queries.blocked的 pattern/regex types 组合拦截高风险查询hash字段为查询串 FNV-1 32 位哈希状态观测通过LokiStack.status.components.component查看各组件的 Pod 状态分组通过status.conditions的 type/reason 组合如DegradedMissingObjectStorageSecret快速定位配置问题。如需深入字段校验细节如kubebuilder:validation注解、默认值、XValidation 规则可直接查阅 operator/api/loki/v1/lokistack_types.go 及各规则类型源码默认资源规格见 operator/internal/manifests/internal/sizes.go完整的 CRD 定义OpenAPI 校验位于 operator/config/crd 目录。【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考