使用 Helm Chart 在 Kubernetes 上部署 Loki 微服务Distributed模式【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/lokiLoki 的微服务microservices / Distributed部署模式将 Compactor、Distributor、Ingester、Querier 等组件拆分为独立进程运行适合日日志量超过 1TB 的大型生产集群。本文以官方 Helm Chart 为核心完整讲解从添加社区 Chart 仓库、编写values.yaml、执行安装/升级到验证 Pod 状态的整套流程并深入对象存储S3 / Azure配置、Gateway API 暴露方案与优雅关停等进阶话题帮助你交付一套可运行的分布式 Loki。微服务模式将 Loki 拆成独立进程与单二进制SingleBinary和简单可扩展SimpleScalableread/write/backend 三目标模式不同微服务模式将 Loki 的每个组件作为独立进程运行在 Kubernetes 中也被称为 Distributed分布式部署。这种方式组件职责清晰、可按负载独立扩缩容是大型集群的首选形态但部署与管理也最复杂。当 Chart 以deploymentMode: Distributed部署并采用下述示例中的副本数时会创建以下组件组件副本数职责Compactor1压缩并处理已存储的数据Distributor3分发写入请求IndexGateway2处理索引查询Ingester3启用 zone awareness 时每个 zone 1 个负责数据摄入Querier3处理查询QueryFrontend2管理前端查询QueryScheduler2调度查询Gateway1NGINX暴露 Loki API 并将请求代理到正确的组件Loki Canary1DaemonSet验证 Loki 部署的健康状态Chunks cache1使用 memcached 缓存 chunk 数据Results cache1使用 memcached 缓存查询结果其中 Ingester 默认启用zone-aware replication分区感知复制ingester.replicas: 3时Chart 会创建zone-a、zone-b、zone-c三个 StatefulSet每个 zone 一个副本。这一机制要求集群至少 3 个节点并且依赖 rollout-operator 来安全执行多 zone 滚动更新需在values.yaml中设置rollout_operator.enabled: true或单独安装 rollout-operator。开发环境如需关闭可设置ingester.zoneAwareReplication.enabled: false。从 Chart 源码可以印证这一设计在 production/helm/loki/templates/ingester/ 目录下除了常规的statefulset-ingester.yaml还存在statefulset-ingester-zone-a.yaml、statefulset-ingester-zone-b.yaml、statefulset-ingester-zone-c.yaml以及对应的 headless Service 和 HPA 模板values.yaml 中对zoneAwareReplication的注释也明确指出启用后会创建 3 个 StatefulSet所有写入都会向每个 zone 发送一份副本从而允许单个 zone 内的多个 Ingester 同时重启而不丢失数据。需要特别说明的是官方不建议在微服务模式下使用filesystem存储。本文示例使用已弃用的内置 MinIO subchart 以便提供完整可运行的自包含示例生产环境必须配置独立的外部对象存储后端。前置条件Helm 3 及以上版本Kubernetes 1.25 及以上版本一个运行中的 Kubernetes 集群由于 zone-aware replication 默认开启集群至少需要 3 个节点。开发与测试环境的部署流程自 Grafana 官方 Chart 迁移至社区维护2026-03-16 起由 Grafana Champions 与 Grafana Community 在 Grafana-community/helm-charts 仓库维护Chart 的大版本号升级意味着破坏性变更后仓库地址已发生变化首次部署时需注意使用新地址。第 1 步添加 Grafana Community Chart 仓库helm repo add grafana-community https://grafana-community.github.io/helm-charts第 2 步更新 Chart 仓库helm repo update第 3 步创建配置文件values.yaml下面的示例展示了使用 MinIO 作为存储、以测试模式部署 Loki 的完整配置。注意内置 MinIO subchart 已弃用计划于 2026-10-31 移除chart v17 渲染该示例需要ignoreMinioDeprecation: true生产环境请配置独立的外部对象存储。loki: schemaConfig: configs: - from: 2024-04-01 store: tsdb object_store: s3 schema: v13 index: prefix: loki_index_ period: 24h ingester: chunk_encoding: snappy querier: # 默认是 4内存和 CPU 充足时可调大出现 OOM 时调小 max_concurrent: 4 pattern_ingester: enabled: true limits_config: allow_structured_metadata: true volume_enabled: true deploymentMode: Distributed ingester: replicas: 3 # 通过复制保证数据持久性 zoneAwareReplication: enabled: false querier: replicas: 3 # 通过并行提升查询性能 maxUnavailable: 2 queryFrontend: replicas: 2 maxUnavailable: 1 queryScheduler: replicas: 2 distributor: replicas: 3 maxUnavailable: 2 compactor: replicas: 1 indexGateway: replicas: 2 maxUnavailable: 1 patternIngester: enabled: true replicas: 1 # 实验性 Bloom 组件默认关闭 bloomPlanner: replicas: 0 bloomBuilder: replicas: 0 bloomGateway: replicas: 0 # 其他部署模式组件置零 backend: replicas: 0 read: replicas: 0 write: replicas: 0 singleBinary: replicas: 0 # 暴露 Loki gateway便于外部写入和查询 gateway: service: type: LoadBalancer ignoreMinioDeprecation: true # 临时方案——MinIO 将于 2026-10-31 移除 # 启用 minio 作为存储 minio: enabled: true关于配置的几点说明deploymentMode是 Chart 的核心开关。查看 values.yaml 可知默认值是SimpleScalable可选SingleBinary、SimpleScalable、Distributed三种正式模式以及SingleBinary-SimpleScalable、SimpleScalable-Distributed两种迁移模式其中 SimpleScalable 与 Distributed 模式强制要求对象存储。上述示例中backend/read/writeSimpleScalable 组件与singleBinary的副本数置零、bloomPlanner/bloomBuilder/bloomGateway置零是为了避免其他部署模式的组件被重复创建。仓库中的 distributed-values.yaml 提供了同样的参考写法。各组件maxUnavailable用于控制 PodDisruptionBudget 允许的最大不可用副本数配合滚动更新可在保证可用性的前提下安全发布。第 4 步安装或升级 Loki 部署安装helm install --values values.yaml loki grafana-community/loki升级helm upgrade --values values.yaml loki grafana-community/loki第 5 步验证 Loki 是否正常运行kubectl get pods -n loki输出应类似于loki-canary-8thrx 1/1 Running 0 167m loki-canary-h965l 1/1 Running 0 167m loki-canary-th8kb 1/1 Running 0 167m loki-chunks-cache-0 2/2 Running 0 167m loki-compactor-0 1/1 Running 0 167m loki-distributor-7c9bb8f4dd-bcwc5 1/1 Running 0 167m loki-distributor-7c9bb8f4dd-jh9h8 1/1 Running 0 167m loki-distributor-7c9bb8f4dd-np5dw 1/1 Running 0 167m loki-gateway-77bc447887-qgc56 1/1 Running 0 167m loki-index-gateway-0 1/1 Running 0 167m loki-index-gateway-1 1/1 Running 0 166m loki-ingester-0 1/1 Running 0 167m loki-ingester-1 1/1 Running 0 167m loki-ingester-2 1/1 Running 0 167m loki-minio-0 1/1 Running 0 167m loki-querier-bb8695c6d-bv9x2 1/1 Running 0 167m loki-querier-bb8695c6d-bz2rw 1/1 Running 0 167m loki-querier-bb8695c6d-z9qf8 1/1 Running 0 167m loki-query-frontend-6659566b49-528j5 1/1 Running 0 167m loki-query-frontend-6659566b49-84jtx 1/1 Running 0 167m loki-query-scheduler-f6dc4b949-fknfk 1/1 Running 0 167m loki-query-scheduler-f6dc4b949-h4nwh 1/1 Running 0 167m loki-results-cache-0 2/2 Running 0 167m从输出可以直观看到每个组件对应的 Workload 类型Distributor、Querier、QueryFrontend、QueryScheduler、Gateway 是 DeploymentIngester、IndexGateway、Compactor 以及两个 memcached 缓存是 StatefulSetCanary 是 DaemonSet——与 production/helm/loki/templates/ 目录中deployment-*.yaml、statefulset-*.yaml、daemonset.yaml的模板划分一一对应。对象存储配置用 MinIO 完成测试后建议将 Loki 切换到对象存储供应商。下面是不同对象存储的配置示例。安全警告使用 S3 存储部署 Loki 时不要使用默认的 bucket 名称chunk、ruler和admin请为每个 bucket 选择唯一名称2024-06-27 的 Grafana 安全公告披露了默认 bucket 名可能导致的非预期数据写入问题。该警告不适用于 MinIO——使用 MinIO 时推荐保留默认 bucket 名。使用 S3 存储# Example configuration for Loki with S3 storage loki: schemaConfig: configs: - from: 2024-04-01 store: tsdb object_store: s3 schema: v13 index: prefix: loki_index_ period: 24h storage_config: aws: region: AWS region your bucket is in, for example, eu-west-2 bucketnames: Your AWS bucket for chunk, for example, aws-loki-dev-chunk s3forcepathstyle: false ingester: chunk_encoding: snappy pattern_ingester: enabled: true limits_config: allow_structured_metadata: true volume_enabled: true retention_period: 672h # 28 days retention querier: max_concurrent: 4 storage: type: s3 bucketNames: chunks: Your AWS bucket for chunk, for example, aws-loki-dev-chunk ruler: Your AWS bucket for ruler, for example, aws-loki-dev-ruler admin: Your AWS bucket for admin, for example, aws-loki-dev-admin s3: # s3 URL 可用于指定 endpoint、access key、secret key 和 bucket 名称 # 适用于 S3 兼容存储或本地使用 S3 作为后端使用 s3 URL 时下面的单项字段可省略 s3: s3://access_key:secret_access_keycustom_endpoint/bucket_name # AWS endpoint URL endpoint: your-endpoint # AWS region where the S3 bucket is located region: your-region # AWS secret access key secretAccessKey: your-secret-access-key # AWS access key ID accessKeyId: your-access-key-id # AWS signature version (e.g., v2 or v4) signatureVersion: your-signature-version # Forces the path style for S3 (true/false) s3ForcePathStyle: false # Allows insecure (HTTP) connections (true/false) insecure: false # HTTP configuration settings http_config: {} deploymentMode: Distributed # Disable minio storage minio: enabled: false ingester: replicas: 3 zoneAwareReplication: enabled: false querier: replicas: 3 maxUnavailable: 2 queryFrontend: replicas: 2 maxUnavailable: 1 queryScheduler: replicas: 2 distributor: replicas: 3 maxUnavailable: 2 compactor: replicas: 1 indexGateway: replicas: 2 maxUnavailable: 1 patternIngester: enabled: true replicas: 1 bloomPlanner: replicas: 0 bloomBuilder: replicas: 0 bloomGateway: replicas: 0 backend: replicas: 0 read: replicas: 0 write: replicas: 0 singleBinary: replicas: 0S3 配置要点loki.storage_config.aws是传给 Loki 进程的底层 AWS 配置loki.storage.s3则是 Chart 层用于渲染存储 secret/配置的高层设置二者需保持一致s3URL 形式适合 S3 兼容存储或自建对象存储如 MinIO、Ceph RGW可以一条字符串完成 endpoint 与凭据配置使用单项字段endpoint/region/accessKeyId/secretAccessKey时则更清晰直观insecure: false表示强制 HTTPS本地 HTTP 测试时可临时改为true。使用 Azure Blob Storage# Example configuration for Loki with Azure Blob Storage loki: schemaConfig: configs: - from: 2024-04-01 store: tsdb object_store: azure schema: v13 index: prefix: loki_index_ period: 24h ingester: chunk_encoding: snappy tracing: enabled: true querier: max_concurrent: 4 storage: type: azure azure: # Name of the Azure Blob Storage account accountName: your-account-name # Key associated with the Azure Blob Storage account accountKey: your-account-key # Comprehensive connection string for Azure Blob Storage account (Can be used to replace endpoint, accountName, and accountKey) connectionString: your-connection-string # Flag indicating whether to use Azure Managed Identity for authentication useManagedIdentity: false # Flag indicating whether to use a federated token for authentication useFederatedToken: false # Client ID of the user-assigned managed identity (if applicable) userAssignedId: your-user-assigned-id # Timeout duration for requests made to the Azure Blob Storage account (in seconds) requestTimeout: your-request-timeout # Domain suffix of the Azure Blob Storage service endpoint (e.g., core.windows.net) endpointSuffix: your-endpoint-suffix bucketNames: chunks: chunks ruler: ruler admin: admin deploymentMode: Distributed ingester: replicas: 3 zoneAwareReplication: enabled: false querier: replicas: 3 maxUnavailable: 2 queryFrontend: replicas: 2 maxUnavailable: 1 queryScheduler: replicas: 2 distributor: replicas: 3 maxUnavailable: 2 compactor: replicas: 1 indexGateway: replicas: 2 maxUnavailable: 1 bloomPlanner: replicas: 0 bloomBuilder: replicas: 0 bloomGateway: replicas: 0 backend: replicas: 0 read: replicas: 0 write: replicas: 0 singleBinary: replicas: 0Azure 配置要点connectionString可以整体替代endpoint、accountName、accountKey三项生产环境推荐使用useManagedIdentity: true或联邦令牌useFederatedToken: true代替明文密钥避免凭据落盘。其他存储供应商的配置可参考 production/helm/loki/README.md 及 Chart 的 Helm Chart Reference 文档。通过 Gateway API 暴露服务除传统的 Kubernetes Ingress 外Loki Helm Chart 还支持 Gateway API 路由且提供了两个相互独立的选项保留 nginx gateway 或完全绕过它。选项一通过 Gateway API 暴露 nginx gateway使用gateway.route替代gateway.ingress创建指向 nginx gateway 的 Gateway API 路由。nginx 仍作为代理只是入口从传统 Ingress 换成 Gateway API 资源gateway: ingress: enabled: false # disable traditional Ingress route: main: enabled: true kind: HTTPRoute parentRefs: - name: my-gateway namespace: gateway-namespace hostnames: - loki.example.com选项二绕过 nginx直接路由到 Loki 服务使用顶层route:键与顶层ingress:互斥将 Gateway API 流量直接路由到 Loki 服务完全绕过 nginx。当deploymentMode: Distributed时Chart 会自动生成基于路径的规则把请求分发到正确的微服务组件distributor、query-frontend、ruler、compactorgateway: enabled: false route: main: enabled: true kind: HTTPRoute parentRefs: - name: my-gateway namespace: gateway-namespace hostnames: - loki.example.com两个选项的通用行为若未显式设置apiVersionChart 会自动探测集群中已安装的最新 Gateway API 版本支持的路由类型包括HTTPRoute、GRPCRoute、TCPRoute、TLSRoute和UDPRoute。Distributor 优雅关停在滚动发布或缩容期间可以让 Distributor 优雅退出设置distributor.shutdownDelay例如90s收到 SIGTERM 后 Distributor 会在该时长内于/ready端点返回 503使负载均衡器在关停前完成连接排空。distributor: shutdownDelay: 90s terminationGracePeriodSeconds: 120约束条件distributor.terminationGracePeriodSeconds必须大于shutdownDelay与loki.server.graceful_shutdown_timeout默认5s之和否则 Pod 会在优雅关停完成前被强制终止。从源码看Distributor 是 Deployment 形态deployment-distributor.yaml其就绪探针默认指向/ready见 values.yaml 中的readinessProbe配置这正是该机制生效的基础。生产环境部署建议官方推荐在大规模场景下将 Loki 运行在 AWS、Azure 或 GCP 等云环境中并提供了最小可用生产环境的部署指南AWS、Azure 各一份。这些指南在社区维护的官方文档站点中持续更新建议在生产落地前先行阅读。后续步骤配置 Agent 向 Loki 发送日志数据使用推荐的 Kubernetes 监控 Helm Chart 对 Loki 部署进行监控与告警对应文档位于本仓库 docs/sources/setup/install/helm/ 目录下的 monitor-and-alert 指南深入理解部署模式的差异后可参考仓库中的 values.schema.jsonChart 参数的 JSON Schema 校验、ci/non-default-values.yamlCI 中的非默认配置样例以及 test/integration/distributed-advanced/non-default-values.yaml分布式高级集成测试配置验证自定义values.yaml的合法性与实际效果。【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考