使用 Kubernetes Monitoring Helm Chart 与 Loki 采集 Kubernetes 日志的完整实战指南-港品优选

使用 Kubernetes Monitoring Helm Chart 与 Loki 采集 Kubernetes 日志的完整实战指南

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

Loki 最典型的落地场景之一，就是从 Kubernetes 集群中采集并存储日志。本指南基于 Grafana 官方教程，完整演示如何在同一 Kubernetes 集群中部署 Loki、Grafana 与 Kubernetes Monitoring Helm chart（内含 Grafana Alloy 采集器），实现 Pod 日志与 Kubernetes 事件两类日志的采集、存储与可视化。读完本文，你将掌握 Helm 安装 Loki（单二进制模式）、配置 Grafana 的 Loki 数据源、精细化控制 Alloy 日志采集（命名空间过滤、标签保留、结构化元数据）的完整实操链路。

背景：Kubernetes 中的三类日志

Kubernetes 集群中的日志大致可分为三类，Loki 的主要使用场景就是针对它们做集中采集：

Pod 日志（Pod logs）：集群中运行的 Pod 所生成的日志，也是本教程采集的第一类日志。
Kubernetes 事件（Kubernetes Events）：由 Kubernetes API Server 生成的事件日志，描述集群内发生的重要状态变化。
节点日志（Node logs）：集群节点自身产生的日志（如/var/log/journal下的系统日志），本教程中不涉及。

本教程聚焦前两类：Pod 日志和Kubernetes 事件，并部署 Grafana 用于可视化。

动手前的关键认知

正式开始前，先明确几个影响后续决策的核心概念：

Loki 的部署模式：Loki 既可以单二进制（monolithic）运行，也可以作为分布式系统运行。本教程采用单二进制模式（Single Binary）。在 Loki Helm chart 的 values.yaml 中，deploymentMode字段定义了三种模式及其适用规模：
- SingleBinary：以单个二进制部署，适合小型安装（通常无高可用需求，日写入量约几十 GB 以内），可随日志量垂直扩容；
- SimpleScalable：拆分为 read、write、backend 三个目标部署，适合中型安装（约 1TB/天以内），比分布式更易管理；
- Distributed：按微服务拆分独立组件，最复杂但能力最强，适合大型安装（通常超过 1TB/天）。
Grafana Labs 官方建议：生产环境处理高日志量时，优先采用分布式/微服务模式。本教程使用单二进制模式足以支撑演示场景。
部署位置：Loki、Grafana 以及 Kubernetes Monitoring Helm chart 自带的 Alloy 都将部署在meta命名空间。请确保你有在该命名空间创建资源的权限，并评估节点剩余容量是否足够承载这些 Pod。Kubernetes Monitoring chart 本身资源占用很小，也可以只部署它、把日志写到外部 Loki 实例或 Grafana Cloud。
存储后端：Loki Helm chart 默认内置的对象存储后端是 MinIO，本教程直接使用它。生产环境应迁移到 S3、GCS、Azure Blob Storage 或 MinIO 集群等更成熟的存储方案。

前提条件

开始前需要准备：

一个运行Kubernetes 1.23 及以上版本的集群；
本地安装kubectl；
本地安装Helm。

第一步：创建`meta`与`prod`命名空间

Kubernetes Monitoring chart 将监控两个命名空间，职责划分如下：

meta：部署 Loki、Grafana 与 Alloy；
prod：部署用于产生日志的示例应用。

kubectl create namespace meta && kubectl create namespace prod

第二步：添加 Helm 仓库并克隆教程仓库

Grafana 与 Kubernetes Monitoring Helm chart 位于 Grafana Helm 仓库，而 Loki Helm chart 独立维护在 Grafana Community Helm Charts 仓库中。分别添加两个仓库并更新索引：

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

随后克隆教程仓库并进入对应目录，后续所有命令均假设你已位于该目录下：

git clone https://github.com/grafana/alloy-scenarios.git cd alloy-scenarios/k8s/logs

第三步：部署 Loki

使用 Loki Helm chart 以最小资源占用部署 Loki（单二进制模式），并启用其默认的 MinIO 存储后端：

helm install --values loki-values.yml loki grafana-community/loki -n meta

该命令将 Loki 部署到meta命名空间，values文件指定了 Loki 的资源配置。关于 Loki Helm chart 的更多配置细节，可参考仓库内的 production/helm/loki 目录及其 README.md。

注意：教程中的loki-values.yml针对资源受限的演示集群做了裁剪：关闭了缓存、关闭 Loki Canary 自监控，并限制 Loki 的 CPU/内存配额。整个部署过程最多需要约1 分钟。

从源码结构看，单二进制模式在 chart 中有专门的模板支撑：production/helm/loki/templates/single-binary/目录下定义了 StatefulSet（statefulset.yaml）、Service、HPA、PDB 等资源。chart 内置的 single-binary-values.yaml 是一个很好的参考：它将deploymentMode设为SingleBinary、singleBinary.replicas设为 1，同时把 backend/read/write 以及其他各组件的replicas归零，并显式开启minio.enabled: true。

关于 MinIO 存储，values.yaml 中的默认配置为minio.enabled: false（生产环境由你显式提供对象存储），但启用后会创建chunks、ruler、admin三个默认 bucket 和一个logs-user读写账号。本教程的loki-values.yml正是通过开启该内置 MinIO 来完成"开箱即用"的演示闭环。

第四步：部署 Grafana

将 Grafana 部署到meta命名空间，用于可视化 Loki 中的日志：

helm install --values grafana-values.yml grafana grafana/grafana --namespace meta

grafana-values.yml中有两个关键配置项值得注意：

登录凭据：adminUser与adminPassword，本教程中的值分别为admin和adminadminadmin。推荐做法是使用 Kubernetes Secret 或让 Grafana 自动生成密码，避免明文写在配置文件中。
数据源配置：通过datasources段声明 Grafana 使用的数据源，这里定义一个名为Loki的 Loki 数据源：

datasources: datasources.yaml: apiVersion: 1 datasources: - name: Loki type: loki access: proxy orgId: 1 url: http://loki-gateway.meta.svc.cluster.local:80 basicAuth: false isDefault: false version: 1 editable: false

url指向Loki gateway：这是 Loki Helm chart 在 Loki API 前提供的一个统一入口 Service，负责日志写入与查询的路由。URL 格式为http://loki-gateway.<NAMESPACE>.svc.cluster.local:80。如果你把 Loki 部署到其他命名空间或使用了不同名称，必须同步修改该url。

从源码看，gateway 默认由 chart 启用并基于 Nginx 实现：values.yaml 明确说明"chart 默认部署一个 Nginx 容器作为 gateway 负责流量路由（可选做认证）"，默认镜像为nginxinc/nginx-unprivileged、容器端口8080，对应的部署模板见 deployment-gateway-nginx.yaml。

第五步：部署 Kubernetes Monitoring Helm chart

Kubernetes Monitoring Helm chart 负责采集、抓取并把 Kubernetes 遥测数据转发到 Grafana 技术栈，支持指标、日志、追踪与持续性能分析（continuous profiling）。本教程只启用其中的 Pod 日志与集群事件采集：

helm install --values ./k8s-monitoring-values.yml k8s grafana/k8s-monitoring -n meta

完整的k8s-monitoring-values.yml如下：

--- cluster: name: meta-monitoring-tutorial destinations: - name: loki type: loki url: http://loki-gateway.meta.svc.cluster.local/loki/api/v1/push clusterEvents: enabled: true collector: alloy-logs namespaces: - meta - prod nodeLogs: enabled: false podLogs: enabled: true gatherMethod: kubernetesApi collector: alloy-logs labelsToKeep: ["app_kubernetes_io_name","container","instance","job","level","namespace","service_name","service_namespace","deployment_environment","deployment_environment_name"] structuredMetadata: pod: pod # Set structured metadata "pod" from label "pod" namespaces: - meta - prod # Collectors alloy-singleton: enabled: false alloy-metrics: enabled: false alloy-logs: enabled: true # Required when using the Kubernetes API to pod logs alloy: mounts: varlog: false clustering: enabled: true alloy-profiles: enabled: false alloy-receiver: enabled: false

逐项拆解这份配置：

cluster.name：设为meta-monitoring-tutorial，这是一个静态标签，会附加到 Kubernetes Monitoring chart 采集的所有日志上。
destinations：定义名为loki的转发目标，url指向 Loki gateway 的推送端点/loki/api/v1/push。若 Loki 部署在其他命名空间或完全不同的位置，需同步修改该url。
集群事件与 Pod 日志采集：
- collector：指定使用哪个采集器，这里统一使用alloy-logs；
- labelsToKeep：指定采集日志时保留的标签。注意它不会丢弃日志，只是避免把高基数（high cardinality）标签（例如本配置中刻意移除了pod）直接落到 Loki 的索引标签上；
- structuredMetadata：定义结构化元数据。这里把pod设为结构化元数据，从而在查询时仍能保留 Pod 名称，又无需将其作为需要索引的标签；
- namespaces：限定从哪些命名空间采集日志，这里是meta与prod。
禁用节点日志：本教程关闭nodeLogs，因为它需要挂载/var/log/journal，超出本教程范围。
按需部署采集器：该 chart 只部署你实际需要的东西。这里只启用了alloy-logs（并配套mounts.varlog: false、启用 clustering），其余 collector（metrics、profiles、receiver、singleton）全部关闭。如果还需要采集 K8s 指标、追踪或持续性能分析数据，再分别启用对应 collector 即可。

第六步：访问 Grafana

通过 port-forward 将 Grafana 服务映射到本地 3000 端口：

export POD_NAME=$(kubectl get pods --namespace meta -l "app.kubernetes.io/name=grafana,app.kubernetes.io/instance=grafana" -o jsonpath="{.items[0].metadata.name}") && \ kubectl --namespace meta port-forward $POD_NAME 3000 --address 0.0.0.0

提示：port-forward 会占用当前终端，按Ctrl + C即可停止。

浏览器访问 http://localhost:3000，使用默认凭据admin/adminadminadmin登录。推荐第一站是Logs Drilldown（日志下钻视图），它无需手写查询即可自动可视化与探索日志：

http://localhost:3000/a/grafana-lokiexplore-app

第七步：（可选）查看 Alloy UI

Kubernetes Monitoring chart 通过 Grafana Alloy 采集并转发集群遥测数据，chart 帮你屏蔽了手写 Alloy 配置的过程。如果想了解采集管线的构成，可以打开 Alloy UI：

export POD_NAME=$(kubectl get pods --namespace meta -l "app.kubernetes.io/name=alloy-logs,app.kubernetes.io/instance=k8s-alloy-logs" -o jsonpath="{.items[0].metadata.name}") && \ kubectl --namespace meta port-forward $POD_NAME 12345 --address 0.0.0.0

浏览器访问 http://localhost:12345 即可查看 Alloy 的采集管线与组件运行状态。

第八步：向`prod`部署示例应用

最后，向prod命名空间部署一个会产生日志的示例应用。本教程以 Grafana Tempo（分布式追踪后端）充当"业务应用"来生成日志：

helm install tempo grafana/tempo-distributed -n prod

正常情况下 Tempo 应与 Loki、Grafana 同处meta命名空间，这里为了演示故意把它当作prod中的主应用来产生日志。

再次暴露 Grafana：

export POD_NAME=$(kubectl get pods --namespace meta -l "app.kubernetes.io/name=grafana,app.kubernetes.io/instance=grafana" -o jsonpath="{.items[0].metadata.name}") && \ kubectl --namespace meta port-forward $POD_NAME 3000 --address 0.0.0.0

访问http://localhost:3000/a/grafana-lokiexplore-app即可查看 Tempo 产生的日志。

总结与进阶方向

至此，你已经完成了完整的链路搭建：Alloy 采集meta/prod命名空间的 Pod 日志与 Kubernetes 事件 → 推送到 Loki gateway → 写入 Loki（单二进制模式 + MinIO 存储）→ 通过 Grafana 的 Logs Drilldown 可视化查询。整个过程只需几条 Helm 命令，足以证明 Loki 与 Kubernetes 监控生态"开箱即用"的集成体验。

本教程部署的是各组件的最小化演示版本，生产化还需要进一步探索：

Loki 的规模化：结合 production/helm/loki/values.yaml 中的deploymentMode，按日志量评估从SingleBinary升级到SimpleScalable甚至Distributed，并为分布式模式接入 S3/GCS/Azure Blob 等生产级对象存储；
存储与高可用：将内置 MinIO 替换为托管对象存储，为 gateway、组件开启多副本与 HPA/PDB；
采集策略调优：在k8s-monitoring-values.yml中按需启用 metrics/traces/profiling 采集器，细化labelsToKeep与structuredMetadata以控制标签基数；
监控自身：Loki Helm chart 支持自监控（self-monitoring），可结合 Loki Canary 持续验证写入链路，相关测试代码见 src/helm-test/canary_test.go。

Grafana 与 Kubernetes Monitoring Helm chart 独立于本仓库维护，其完整的参数说明可查阅各自 Helm chart 的官方文档（Loki Helm chart 的仓库内资料见 production/helm/loki/README.md 与 docs/sources/setup 目录）。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析