一、为什么监控平台需要持久化?
kubectl get pods 看起来一切正常,并不等于监控系统具备可靠性。尤其是第一次用 Helm 安装 kube-prometheus-stack 时,常见三个问题:
- Prometheus 重建后历史时序数据消失:因为使用了临时存储,或者新的实例没有挂载原来的 PVC。
- Grafana 修改的配置与自建 Dashboard 丢失:Grafana 默认数据库文件需要持久化存储,不能只依靠 Pod 文件系统。
- Alertmanager 静默记录丢失:告警路由配置可来自 Secret,但 Silences 等运行状态仍需存储。
所以本篇目标不是简单“让 Pod Running”,而是建立一套 Helm 配置有版本、核心服务可控调度、PVC 可检查、Pod 重建后数据可验证 的可复现流程。
特别注意:持久化 ≠ 跨节点高可用。
openebs-hostpath属于本地存储:Pod 在同一节点重建可重新挂载原数据,但节点磁盘故障、误删 PVC/PV 或重建节点可能导致数据丢失。本文方案定位为单节点实验室监控持久化,不是多副本生产存储方案。
二、实验环境和目标架构
| 节点 | 地址 | 角色 |
|---|---|---|
| h11 | 192.168.6.11 | Kubernetes control-plane、执行 Helm 和 kubectl |
| h12 | 192.168.6.12 | 业务工作节点 |
| h13 | 192.168.6.13 | Storage/Stateful 工作节点 |
| h14 | 192.168.6.14 | NFS Server + 工作节点 |
| h15 | 192.168.6.15 | Observability 工作节点 |
| h16 | 192.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 PVC | grafana.persistence |
| Prometheus PVC | prometheus.prometheusSpec.storageSpec |
| Alertmanager PVC | alertmanager.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、实验环境可中断时测试。 如果这套监控正在承担真实生产告警职责,不应直接进行人为中断。
- 先记录 Prometheus 历史指标时间段以及 Grafana 自建 Dashboard 名称。
- 使用
kubectl -n monitoring get deploy,sts确认当前工作负载名称。 - 对 Grafana 执行滚动重启(以下名称符合
monitoringRelease 的常见命名):
kubectl -n monitoring rollout restart deployment/monitoring-grafana
kubectl -n monitoring rollout status deployment/monitoring-grafana --timeout=5m
- 再次检查 Grafana Dashboard 是否存在、PVC 是否仍 Bound。
- 需要进一步检查 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


