📚 课程目录第3章模板语法入门

3. Helm 部署 Loki Stack：Chart 配置与安装

Loki Stack（简称 LGTM 中的 L）由 Loki（日志存储与查询引擎）、Promtail（日志采集 Agent）和 Grafana（可视化面板）三个核心组件构成。本章将基于 Helm Chart 完成三组件的完整部署，并讲解关键配置项，为后续根因定位场景打下数据采集基础。

3.1 架构概览

下图展示了 Loki Stack 在 Kubernetes 集群中的典型部署拓扑：Promtail 以 DaemonSet 方式运行在每个 Node 上，采集容器日志并推送至 Loki；Loki 以 StatefulSet 模式存储日志数据并提供查询接口；Grafana 通过 Loki 数据源实现日志检索与可视化。

3.2 添加 Helm 仓库

Grafana 官方维护的 Helm 仓库包含 Loki、Promtail 和 Grafana 三个 Chart。首先添加仓库并更新索引：

helm repo add grafana https://grafana.github.io/helm-charts
helm repo update

确认 Chart 版本：

helm search repo grafana/loki --versions | head -5
helm search repo grafana/promtail --versions | head -5
helm search repo grafana/grafana --versions | head -5

3.3 核心配置项解析

三个 Chart 的配置集中在 values.yaml 中。下表列出部署时必须关注的关键参数：

Chart	参数路径	推荐值	说明
loki	`loki.auth_enabled`	`false`	测试环境关闭认证；生产环境建议开启并配置 gateway
loki	`loki.storageConfig.boltdb_shipper.shared_store`	`filesystem`	单节点使用本地文件系统；生产环境切换为 s3/gcs
loki	`loki.schemaConfig.configs`	见下方代码块	定义 schema 版本与索引周期
loki	`singleBinary.replicas`	`1`	单二进制模式，适合小规模集群
promtail	`config.lokiAddress`	`http://loki:3100/loki/api/v1/push`	Promtail 推送日志的 Loki 地址
promtail	`config.clients`	见下方代码块	支持多 Loki 后端配置
grafana	`datasources.datasources.yaml`	见下方代码块	预配置 Loki 数据源
grafana	`adminPassword`	`admin`	Grafana 管理员密码，生产环境务必修改

3.4 准备 values 文件

为每个 Chart 创建独立的 values 文件，便于管理和升级。

3.4.1 Loki values

# loki-values.yaml
loki:
  auth_enabled: false
  commonConfig:
    replication_factor: 1
  storageConfig:
    boltdb_shipper:
      shared_store: filesystem
    filesystem:
      directory: /data/loki/chunks
  schemaConfig:
    configs:
      - from: 2024-01-01
        store: boltdb-shipper
        object_store: filesystem
        schema: v12
        index:
          prefix: index_
          period: 24h

singleBinary:
  replicas: 1
  persistence:
    enabled: true
    size: 10Gi

serviceAccount:
  create: true

3.4.2 Promtail values

# promtail-values.yaml
config:
  clients:
    - url: http://loki:3100/loki/api/v1/push
      tenant_id: ""
  snippets:
    pipelineStages:
      - cri: {}
    scrapeConfigs:
      - job_name: kubernetes-pods
        kubernetes_sd_configs:
          - role: pod
        pipeline_stages:
          - cri: {}
        relabel_configs:
          - source_labels: [__meta_kubernetes_pod_label_app]
            target_label: app
          - source_labels: [__meta_kubernetes_namespace]
            target_label: namespace
          - source_labels: [__meta_kubernetes_pod_name]
            target_label: pod

rbac:
  create: true

serviceAccount:
  create: true

3.4.3 Grafana values

# grafana-values.yaml
adminPassword: admin

datasources:
  datasources.yaml:
    apiVersion: 1
    datasources:
      - name: Loki
        type: loki
        access: proxy
        url: http://loki:3100
        version: 1
        isDefault: true

dashboardProviders:
  dashboardproviders.yaml:
    apiVersion: 1
    providers:
      - name: default
        orgId: 1
        folder: ""
        type: file
        disableDeletion: false
        editable: true
        options:
          path: /var/lib/grafana/dashboards

persistence:
  enabled: true
  size: 5Gi

service:
  type: ClusterIP
  port: 80

配置要点：

Loki 的 auth_enabled: false 仅用于测试环境，生产环境必须通过 gateway 或 nginx 开启认证。
Promtail 的 clients.url 使用 Service 名称 loki，Kubernetes DNS 会自动解析到 Loki Pod。
Grafana 的 datasources.datasources.yaml 是预配置数据源的标准方式，无需手动添加。

3.5 安装 Chart

按照依赖顺序依次安装：先安装 Loki，再安装 Promtail 和 Grafana。

# 1. 安装 Loki
helm install loki grafana/loki \
  --namespace logging \
  --create-namespace \
  -f loki-values.yaml

# 2. 安装 Promtail
helm install promtail grafana/promtail \
  --namespace logging \
  -f promtail-values.yaml

# 3. 安装 Grafana
helm install grafana grafana/grafana \
  --namespace logging \
  -f grafana-values.yaml

验证安装：

# 查看 Pod 状态
kubectl get pods -n logging

# 预期输出：
# NAME                       READY   STATUS    RESTARTS   AGE
# loki-0                     1/1     Running   0          2m
# promtail-xxxxx             1/1     Running   0          2m
# grafana-xxxxx              1/1     Running   0          2m

# 查看 Service
kubectl get svc -n logging
# loki          ClusterIP   10.x.x.x   3100/TCP
# grafana       ClusterIP   10.x.x.x   80/TCP

3.6 访问 Grafana 并验证日志流

使用端口转发访问 Grafana：

kubectl port-forward -n logging svc/grafana 8080:80

浏览器打开 http://localhost:8080，使用 admin / admin 登录。进入 Explore 页面，选择 Loki 数据源，执行一条简单查询验证日志采集：

{namespace="logging"} |= `loki`

如果返回日志条目，说明 Loki Stack 部署成功，日志流已打通。

3.7 常见问题与排查

现象	可能原因	解决措施
Promtail Pod 日志报 `connection refused`	Loki Service 未就绪或地址配置错误	检查 `kubectl get svc -n logging` 确认 loki Service 存在；检查 Promtail values 中 `clients.url`
Grafana 数据源测试失败	Grafana 无法解析 `loki:3100`	确认 Grafana 与 Loki 在同一 Namespace；或使用完整 Service 名称 `loki.logging.svc.cluster.local`
Loki Pod 频繁重启	存储目录权限不足或磁盘空间满	检查 PVC 状态；调整 `singleBinary.persistence.size`
Explore 查询无数据	Promtail 未正确采集或标签不匹配	检查 Promtail 日志；使用 `{namespace="default"}` 等宽泛标签测试

生产环境注意事项：

Loki 的 singleBinary.replicas 仅适合小规模日志量（每天 < 100GB）。生产环境应使用微服务模式（ingester/querier/distributor 分离）。
Promtail 的 DaemonSet 会占用节点资源，建议设置 resources.limits.memory: 256Mi 避免内存泄漏影响节点。
Grafana 的 adminPassword 应通过 Kubernetes Secret 注入，而非明文写在 values 中。

3.8 本章小结

通过 Helm 部署 Loki Stack 只需三个 Chart、三个 values 文件、三条 install 命令。核心在于理解组件间的网络发现机制（Service 名称解析）和关键配置项的含义。部署完成后，日志数据从 Pod 流向 Promtail，再推送至 Loki，最终在 Grafana 中呈现——这条链路是后续根因定位分析的数据基础。