一、为什么监控平台需要持久化?

kubectl get pods 看起来一切正常,并不等于监控系统具备可靠性。尤其是第一次用 Helm 安装 kube-prometheus-stack 时,常见三个问题:

  1. Prometheus 重建后历史时序数据消失:因为使用了临时存储,或者新的实例没有挂载原来的 PVC。
  2. Grafana 修改的配置与自建 Dashboard 丢失:Grafana 默认数据库文件需要持久化存储,不能只依靠 Pod 文件系统。
  3. Alertmanager 静默记录丢失:告警路由配置可来自 Secret,但 Silences 等运行状态仍需存储。

所以本篇目标不是简单“让 Pod Running”,而是建立一套 Helm 配置有版本、核心服务可控调度、PVC 可检查、Pod 重建后数据可验证 的可复现流程。

特别注意:持久化 ≠ 跨节点高可用。openebs-hostpath 属于本地存储:Pod 在同一节点重建可重新挂载原数据,但节点磁盘故障、误删 PVC/PV 或重建节点可能导致数据丢失。本文方案定位为单节点实验室监控持久化,不是多副本生产存储方案。

二、实验环境和目标架构

节点地址角色
h11192.168.6.11Kubernetes control-plane、执行 Helm 和 kubectl
h12192.168.6.12业务工作节点
h13192.168.6.13Storage/Stateful 工作节点
h14192.168.6.14NFS Server + 工作节点
h15192.168.6.15Observability 工作节点
h16192.168.6.16集群外实验和访问测试客户端

本篇规划:

  • Kubernetes:v1.28.15
  • Namespace:monitoring
  • Helm Release:monitoring
  • Helm Chart:prometheus-community/kube-prometheus-stack 版本 65.8.1
  • NodeSelector:nativeopslab.io/role: observability
  • StorageClass:openebs-hostpath
  • Prometheus:5Gi PVC、保留 2d,retentionSize: 3GB
  • Grafana:2Gi PVC
  • Alertmanager:2Gi PVC
                  Kubernetes cluster
h11 (Helm/kubectl)
  |
  +---- monitoring namespace
              |
              +-- Prometheus Operator  ----> h15
              +-- Grafana -----------------> h15 ---- PVC 2Gi
              +-- Prometheus -------------> h15 ---- PVC 5Gi
              +-- Alertmanager -----------> h15 ---- PVC 2Gi
              |
              +-- node-exporter ----------> 各被监控节点(DaemonSet)
              +-- kube-state-metrics -----> 按其自身调度配置

StorageClass: openebs-hostpath
PersistentVolume: h15 上的本地持久卷目录

为什么不把所有 Pod 都调度到 h15? Prometheus、Grafana、Alertmanager、Operator 是重点;node-exporter 是 DaemonSet,应当覆盖需要监控的节点。如果把 node-exporter 也限制到 h15,就会丢失其他节点的宿主机指标。kube-state-metrics 不自动等于已绑定到 h15,需看实际 Values。

三、部署前检查:不要直接覆盖原来的监控环境

下面命令默认在 h11 上执行。

3.1 检查节点标签、存储类和资源

kubectl get nodes -L nativeopslab.io/role
kubectl get node h15 --show-labels
kubectl get sc
kubectl get sc openebs-hostpath -o yaml
kubectl get ns monitoring
ssh [email protected] 'free -h; df -hT; df -i'

应确认:

  • h15 为 Ready,且存在 nativeopslab.io/role=observability。

  • openebs-hostpath 的 provisioner 和 volumeBindingMode 处于预期状态,典型模式是 WaitForFirstConsumer。

  • h15 可用内存、CPU、磁盘空间可满足新增监控负载及本地 PV 占用。

  • 若已安装监控,不要重新初始化或重复安装。

如果缺少预期标签,先确认你确实要把 h15 作为监控节点,再执行:

kubectl label node h15 nativeopslab.io/role=observability --overwrite

3.2 查看已有 Release 与 PVC

helm list -A
kubectl -n monitoring get deploy,sts,pod,pvc -o wide
kubectl get pv -o wide

如果已经有 monitoring Release,先备份:

mkdir -p ~/NativeOpsLab/manifests/monitoring/backup
cd ~/NativeOpsLab/manifests/monitoring
umask 077
helm -n monitoring get values monitoring -o yaml > backup/values-before.yaml
helm -n monitoring get manifest monitoring > backup/manifest-before.yaml
helm -n monitoring history monitoring > backup/history-before.txt
kubectl -n monitoring get pvc -o yaml > backup/pvc-before.yaml
kubectl get pv -o yaml > backup/pv-before.yaml

Helm Values 和清单可能包含密码、地址或其他敏感配置。备份目录不要直接公开提交到 GitHub。如果已存在 PVC,其 StorageClass、绑定节点和历史数据优先级高于本文示例。不要为了套用新示例删除 PVC,也不要无备份地强行修改不可变 PVC 字段。

四、理解三个重要概念

4.1 Helm Values:只维护一个源文件

helm upgrade --install 通过 -f values-monitoring.yaml 指定自己的参数。Helm 负责渲染 Kubernetes 资源;Prometheus Operator 再根据 Prometheus、Alertmanager 自定义资源生成 StatefulSet。

必须区分三个配置入口:

组件Values 键路径
Grafana PVCgrafana.persistence
Prometheus PVCprometheus.prometheusSpec.storageSpec
Alertmanager PVCalertmanager.alertmanagerSpec.storage

这三者层级不同,不能统一把 persistence 写在每个组件下。

4.2 NodeSelector:约束 Pod 的调度位置

nodeSelector:
  nativeopslab.io/role: observability

节点没有这个标签,或者 h15 不能满足资源、污点和其他调度约束时,Pod 就可能 Pending。此外,已有 Local PV 所在节点如果与新 NodeSelector 不一致,也可能调度失败。

4.3 OpenEBS Hostpath:绑定节点的本地 PV

OpenEBS Local PV Hostpath 通常通过 WaitForFirstConsumer:先综合 Pod 调度约束选择节点,再在对应节点分配本地持久卷。这不是网络共享存储,也不具有跨节点自动复制能力。

这里不要使用 Pod 的 spec.nodeName 来取代 NodeSelector;对于这种延迟绑定模式,绕过调度器可能使 PVC 保持 Pending。

五、完整配置:values-monitoring.yaml

在 h11 创建目录:

mkdir -p ~/NativeOpsLab/manifests/monitoring
cd ~/NativeOpsLab/manifests/monitoring

文件完整内容如下:

# NativeOpsLab / kube-prometheus-stack 65.8.1

grafana:
  nodeSelector:
    nativeopslab.io/role: observability
  persistence:
    enabled: true
    type: pvc
    storageClassName: openebs-hostpath
    accessModes:
      - ReadWriteOnce
    size: 2Gi
  resources:
    requests:
      cpu: 100m
      memory: 128Mi
    limits:
      memory: 512Mi

prometheusOperator:
  nodeSelector:
    nativeopslab.io/role: observability
  resources:
    requests:
      cpu: 100m
      memory: 128Mi
    limits:
      memory: 512Mi

prometheus:
  prometheusSpec:
    replicas: 1
    nodeSelector:
      nativeopslab.io/role: observability
    retention: 2d
    retentionSize: 3GB
    resources:
      requests:
        cpu: 200m
        memory: 512Mi
      limits:
        memory: 2Gi
    storageSpec:
      volumeClaimTemplate:
        spec:
          storageClassName: openebs-hostpath
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 5Gi

alertmanager:
  alertmanagerSpec:
    replicas: 1
    nodeSelector:
      nativeopslab.io/role: observability
    resources:
      requests:
        cpu: 50m
        memory: 96Mi
      limits:
        memory: 256Mi
    storage:
      volumeClaimTemplate:
        spec:
          storageClassName: openebs-hostpath
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 2Gi

为什么 Grafana 选择 type: pvc?

这里延续 #03 的设计,让 Grafana 使用 PVC 持久化,同时保留 Grafana 子 Chart 常规的 Deployment 形式。与 type: sts 不同,不强制修改 Grafana 工作负载类型。对已有 Release 特别重要:不要为了持久化而随意更换 Deployment / StatefulSet 类型或替换已经绑定的持久卷。

为什么 Prometheus 有两个保留参数?

retention: 2d 指定时间维度,retentionSize: 3GB 指定 TSDB 的磁盘保留目标。它们不保证整个文件系统始终只用 3GB;WAL、检查点及文件系统开销还需预留空间。Prometheus 的 5Gi PVC 是容量请求,不等于 retentionSize。

OpenEBS Hostpath 的 PVC 容量是否被文件系统硬性限制,取决于存储实现和配额配置;不要仅凭申领 5Gi 就认定宿主机磁盘绝不可能被写满。定期检查 h15 的文件系统实际可用空间。

六、先验证 Values,再升级 Helm

6.1 检查 Chart 版本

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update
helm show chart prometheus-community/kube-prometheus-stack --version 65.8.1

本系列为了实验结果可复现,固定为 65.8.1。Chart 的 appVersion 是 v0.77.2(指 Operator 版本),与 Helm Chart 版本不是一回事。切换 Chart 大版本必须单独评估 CRD 和模板变更。

6.2 本地渲染 Helm 模板

helm template monitoring prometheus-community/kube-prometheus-stack \
  --version 65.8.1 \
  -n monitoring \
  -f values-monitoring.yaml \
  > rendered-monitoring.yaml

检查 Prometheus、Alertmanager 自定义资源和 Grafana 的持久化配置是否出现在渲染结果中。helm template 只是本地渲染,不代表真实 CSI、调度、节点容量已经通过验证。

6.3 首次安装或更新

helm upgrade --install monitoring \
  prometheus-community/kube-prometheus-stack \
  --version 65.8.1 \
  -n monitoring \
  --create-namespace \
  -f values-monitoring.yaml \
  --wait --timeout 15m

如果原来存在无持久化的 Prometheus / Grafana 目录,添加 PVC 后不是“旧容器数据自动迁移到新盘”。 旧数据若需要保留,必须先做备份/迁移方案。本文适合空白部署或已经使用同一持久化设计的版本迭代。遇到 StorageClass 变更、Grafana 工作负载切换、Operator CRD 大版本变更时,先停止变更,核对现有资源。

七、部署完成后必须验收的 8 项

7.1 查看 Helm 与工作负载

helm -n monitoring status monitoring
kubectl -n monitoring get pod -o wide
kubectl -n monitoring get deploy,sts,ds
kubectl -n monitoring get prometheus,alertmanager

主要组件应该健康。并非所有 monitoring Pod 都在 h15:node-exporter 应遍布受监控节点。Grafana、Prometheus、Alertmanager、Operator 才是本文明确设置了 h15 NodeSelector 的目标。

7.2 PVC 是否已绑定

kubectl -n monitoring get pvc -o wide
kubectl get pv -o wide
kubectl get sc openebs-hostpath

初次安装时,看到 PVC 短暂 Pending 不一定是错误:WaitForFirstConsumer 允许存储等待 Pod 调度之后再完成绑定。若持续 Pending,继续观察事件。

7.3 PVC 的 StorageClass 和容量

kubectl -n monitoring get pvc \
  -o custom-columns='NAME:.metadata.name,STATUS:.status.phase,STORAGECLASS:.spec.storageClassName,CAPACITY:.status.capacity.storage,VOLUME:.spec.volumeName'

验收标准:Grafana、Prometheus、Alertmanager 对应 PVC 都存在,StorageClass 为 openebs-hostpath,最终状态是 Bound;容量分别对应 2Gi、5Gi、2Gi。

7.4 Pod 是否调度到了 h15

kubectl -n monitoring get pods -o wide
kubectl -n monitoring describe pod <实际Pod名称>

用实际 Pod 名替换占位符;重点检查 Node、Node-Selectors 和 Events。

7.5 检查 PV 的 NodeAffinity

kubectl -n monitoring get pvc
kubectl get pv <实际PV名称> -o yaml

OpenEBS Local PV 通常会在 PV 上记录绑定节点的位置约束,确认它与调度到 h15 的 Pod 匹配。

7.6 查看文件系统占用

ssh [email protected] 'df -hT; df -i'

OpenEBS Hostpath 默认的本地目录通常位于 /var/openebs/local,但请以现场 StorageClass 参数和 PV 路径为准,不能直接假定每个集群都是同一个目录。

7.7 验证 Prometheus 采集历史数据

先检查 Services:

kubectl -n monitoring get svc

按实际 Service 名称执行端口转发(以下是此前 #03 的约定名称):

kubectl -n monitoring port-forward svc/monitoring-kube-prometheus-prometheus 9090:9090

在有权限访问此回环端口的主机上打开 http://127.0.0.1:9090,执行:

up

先记录有数据的时间范围,再进行受控 Pod 重建验证。重建之后 up 恢复为 1,仅证明当前监控恢复,不足以证明历史数据没有丢失。 需要继续查询重建之前已存在的时间区间。

7.8 验证 Grafana Dashboard 保存

检查 Grafana Service:

kubectl -n monitoring get svc | grep grafana
kubectl -n monitoring port-forward svc/monitoring-grafana 3000:80

在 Grafana UI 中新建一个明确命名的测试 Dashboard(例如 NativeOpsLab PVC Test),保存后记录名称。之后按下文进行受控重建,检查该 Dashboard 是否仍能打开。优先使用自己创建的 Dashboard测试,别仅依赖 Chart 自动下发的预置面板,因为它们可以被 Sidecar 自动重新生成。

八、如何验证 Pod 重建后数据仍然存在?

只在已备份、PVC Bound、实验环境可中断时测试。 如果这套监控正在承担真实生产告警职责,不应直接进行人为中断。

  1. 先记录 Prometheus 历史指标时间段以及 Grafana 自建 Dashboard 名称。
  2. 使用 kubectl -n monitoring get deploy,sts 确认当前工作负载名称。
  3. 对 Grafana 执行滚动重启(以下名称符合 monitoring Release 的常见命名):
kubectl -n monitoring rollout restart deployment/monitoring-grafana
kubectl -n monitoring rollout status deployment/monitoring-grafana --timeout=5m
  1. 再次检查 Grafana Dashboard 是否存在、PVC 是否仍 Bound。
  2. 需要进一步检查 Prometheus / Alertmanager 时,应先识别实际 StatefulSet,选定低风险时段按组件逐个重启,等每个组件恢复 Ready 再验证,避免一次性重启整个监控系统。

验收标准:Pod UID 发生变化、PVC 保持原来的 Volume 绑定,Grafana 测试 Dashboard 仍在,Prometheus 重启前的历史时间窗口仍能查询到数据。对于 Alertmanager,如要验证 Silences 持久化,应使用不会影响真实告警的测试用 Silence,并确认重启后仍存在。

这里验证的是 Pod 重建 + 相同节点复用 PVC;它不是“h15 整机损毁后数据恢复”的验证。

九、常见故障:看到什么、怎么排查?

故障 1:Pod Pending

kubectl -n monitoring describe pod <实际Pod名称>
kubectl get node h15 --show-labels
kubectl describe node h15

可能原因:h15 标签不匹配、节点资源不足、污点限制、Local PV 节点亲和性冲突。不要通过直接修改 nodeName 绕过调度器。

故障 2:PVC 一直 Pending

kubectl -n monitoring describe pvc <实际PVC名称>
kubectl get sc openebs-hostpath -o yaml
kubectl -n monitoring get events --sort-by=.lastTimestamp | tail -n 40

可能原因:Provisioner 不健康、Pod 无法调度、VolumeBindingMode 与调度约束不匹配、节点磁盘或权限问题。优先查具体 Events,而不是直接删 PVC。

故障 3:Grafana 数据没保存

kubectl -n monitoring get deploy,sts | grep grafana
kubectl -n monitoring get pvc | grep grafana
kubectl -n monitoring describe pod <Grafana实际Pod名称>

检查是否仍使用 emptyDir,实际数据目录 /var/lib/grafana 是否对应 PVC,是否曾切换到另一个 PVC,是否有写入权限问题。

故障 4:Prometheus 启动失败、只读或 WAL 报错

kubectl -n monitoring logs <Prometheus实际Pod名称> -c prometheus --tail=100
kubectl -n monitoring describe pod <Prometheus实际Pod名称>
ssh [email protected] 'df -hT; df -i'

常见检查方向:卷是否挂载成功、磁盘和 inode 是否耗尽、权限与文件系统是否只读、资源限制是否过低、Prometheus TSDB/WAL 是否异常。不要直接删除 WAL 或 TSDB 数据目录;应先检查日志、备份现有数据,再决定恢复方案。

故障 5:Helm 升级后 PVC 没有变化

helm -n monitoring get values monitoring -o yaml
helm -n monitoring get manifest monitoring | grep -nE 'storageClassName|volumeClaimTemplates'
kubectl -n monitoring get pvc -o wide

检查 Helm Values 是否写错层级、是否实际升级成功,以及旧 PVC 是否已经固定了不可变配置。修改 Helm YAML 不代表 Kubernetes 自动更换了已存在 PVC 的 StorageClass。

十、生产环境风险与边界

1. Local PV 不是高可用存储。 h15 故障后不能保证另一节点自动接管原数据。需要高可用时应评估复制存储、远程指标存储、备份与恢复等独立方案。

2. PVC Bound 不是备份。 还应有可验证的备份及恢复流程。特别关注 OpenEBS StorageClass 的 reclaimPolicy,Delete 策略下删除 PVC 可能连带删除存储数据。

3. 持久化不保证安全。 Grafana 管理员口令、Prometheus/Alertmanager UI 访问权限、网络策略、备份文件权限同样重要。优先使用受控的 kubectl port-forward 或经认证的入口;不要为了测试随意将管理接口暴露公网。

4. 监控容量需要估算。 本文 5Gi Prometheus + 2Gi Grafana + 2Gi Alertmanager 是小型实验室配置示例,不是所有业务通用的生产容量。要结合抓取目标、样本量、保留时间、磁盘余量和写入速率调整。

5. Helm 与 Git 必须有对应关系。 Values、Chart 版本、备份及验收记录应当保留在版本管理流程中;Secret 和敏感备份不要直接上传公开仓库。

十一、结语

Kubernetes 监控持久化的正确目标不是“给 Values 加几个 storageClassName 字段”,而是完整验证:

Helm Values → NodeSelector → Pod 调度 → PVC/PV 绑定 → 数据写入 → Pod 重建 → 历史数据仍可用。

这是实验室从“部署一个可以打开页面的监控系统”,迈向“具有基本可靠性与可运维性的平台”的关键一步。

官方参考资料

  • kube-prometheus-stack 65.8.1 官方 Values:https://raw.githubusercontent.com/prometheus-community/helm-charts/kube-prometheus-stack-65.8.1/charts/kube-prometheus-stack/values.yaml
  • kube-prometheus-stack 65.8.1 Chart.yaml:https://raw.githubusercontent.com/prometheus-community/helm-charts/kube-prometheus-stack-65.8.1/charts/kube-prometheus-stack/Chart.yaml
  • Kubernetes StorageClass / WaitForFirstConsumer:https://kubernetes.io/docs/concepts/storage/storage-classes/
  • OpenEBS Local PV Hostpath:https://openebs.io/docs/main/user-guides/local-storage-user-guide/local-pv-hostpath/configuration/hostpath-storageclass-parameters