Prometheus Operator 0.94.1 运维命令详解

Prometheus Operator 日常运维命令全集实测：CRD 资源巡检（get/describe）、Operator 与实例双容器日志排障、HTTP API 四维验证、promtool 规则与配置校验、CR 扩缩容与 HUP 热加载，含 scale StatefulSet 被 Operator 回滚等陷阱实证。

Prometheus Operator监控可观测性Operator2026/10/24

Prometheus Operator 0.94.1 运维命令详解

目标：沉淀 Prometheus Operator 日常运维所需的命令——CRD 资源巡检、Operator 与实例日志排障、实例状态 API 验证、promtool 规则/配置校验、扩缩容与热加载变更操作。每条命令均为 Kubernetes v1.36.5（k3s v1.36.5+k3s1）集群、Operator v0.94.1 环境下的实测命令与真实回显。

一、环境信息

  • 集群：Kubernetes v1.36.5+k3s1 单节点（k8s-node1）；kubectl v1.36.5+k3s1、helm v3.22.1
  • Prometheus Operator：v0.94.1（kube-prometheus-stack chart 92.11.0 部署，Operator Pod 为 monitoring/kps-operator）
  • 两套 Prometheus 实例：monitoring/kps-prometheus（v3.15.0-distroless，集群自监控）与 default/main（未指定版本时 Operator 内置 v3.14.0，NodePort 30090）
  • Alertmanager：monitoring/kps-alertmanager v0.34.1（NodePort 30093）
  • promtool：v3.14.0（与 main 实例同构建，revision d7598b71，见第七章获取方式）
  • 监控资源存量（实查）：全集群 32 个 PrometheusRule、10 个 ServiceMonitor、1 个 PodMonitor

二、运维工具概览

类别工具/命令用途对应章节
资源巡检kubectl get/describe（prometheus/servicemonitor/prometheusrule…）实例与监控资源健康总览四
日志排障kubectl logsOperator 调和日志、Prometheus/Alertmanager 运行日志五
状态验证curl 实例 HTTP API配置/规则/告警/目标四维验证六
配置校验promtool check rules/config变更前离线校验，防坏配置进集群七
在线查询promtool query instant/range不开 UI 直接查指标七
变更操作kubectl patch/apply + helm upgrade扩缩容、改配置、升级（扩缩容必须走 CR）八

三、前置条件

四、日常巡检命令详解

4.1 Prometheus 实例巡检（kubectl get prometheus）

kubectl get prometheus -A

NAMESPACE    NAME             VERSION              DESIRED   READY   RECONCILED   AVAILABLE   AGE
default      main                                  1         1       True         True        9h
monitoring   kps-prometheus   v3.15.0-distroless   1         1       True         True        9h

列解读（巡检只看这四列就够）：

  • VERSION：实例运行的 Prometheus 版本；main 列为空表示 CR 未指定 spec.version，此时 Operator 使用内置默认版本；
  • DESIRED / READY：期望副本数 / 就绪副本数，不等即实例异常；
  • RECONCILED：Operator 是否已把最新声明调和到底层资源；False 说明调和失败（去 5.2 查 Operator 日志）；
  • AVAILABLE：实例整体可用性聚合状态（由 status conditions 计算，False 时 describe 看详情）。

-o wide 会多出 PAUSED 列（spec.paused: true 时 Operator 暂停调和——调试利器）：

kubectl get prometheus main -n default -o wide

NAME   VERSION   DESIRED   READY   RECONCILED   AVAILABLE   AGE   PAUSED
main             1         1       True         True        9h    false

4.2 监控资源全量巡检

一次列出三类声明资源（实测，只展示 AGE 列形态）：

kubectl get servicemonitors,podmonitors,prometheusrules -A

NAMESPACE    NAME                                                                AGE
default      servicemonitor.monitoring.coreos.com/example-app                    9h
monitoring   servicemonitor.monitoring.coreos.com/kps-alertmanager               9h
monitoring   servicemonitor.monitoring.coreos.com/kps-apiserver                  9h
monitoring   servicemonitor.monitoring.coreos.com/kps-coredns                    9h
monitoring   servicemonitor.monitoring.coreos.com/kps-grafana                    9h
monitoring   servicemonitor.monitoring.coreos.com/kps-kube-state-metrics         9h
monitoring   servicemonitor.monitoring.coreos.com/kps-kubelet                    9h
monitoring   servicemonitor.monitoring.coreos.com/kps-operator                   9h
monitoring   servicemonitor.monitoring.coreos.com/kps-prometheus                 9h
monitoring   servicemonitor.monitoring.coreos.com/kps-prometheus-node-exporter   9h

NAMESPACE   NAME                                                AGE
default     podmonitor.monitoring.coreos.com/example-app-pods   9m6s

NAMESPACE    NAME                                                                                    AGE
default      prometheusrule.monitoring.coreos.com/example-app-rules                                  9m6s
monitoring   prometheusrule.monitoring.coreos.com/kps-alertmanager.rules                             9h
monitoring   prometheusrule.monitoring.coreos.com/kps-k8s.rules.container-cpu-usage-seconds-total    9h
monitoring   prometheusrule.monitoring.coreos.com/kps-kubernetes-system                              9h
monitoring   prometheusrule.monitoring.coreos.com/kps-node-exporter                                  9h
monitoring   prometheusrule.monitoring.coreos.com/kps-prometheus-operator                            9h
...（共 32 条，中间略）

kubectl get <资源> -A 的 NAME 列自带 命名空间前缀，配合 --no-headers | wc -l 可快速统计规模（实测 32 条规则）。

4.3 Alertmanager 实例巡检

kubectl get alertmanager -A

NAMESPACE    NAME               VERSION   REPLICAS   READY   RECONCILED   AVAILABLE   AGE
monitoring   kps-alertmanager   v0.34.1   1          1       True         True        9h

4.4 describe 深挖单个实例

get 看出异常后用 describe 看 status conditions 与事件：

kubectl describe prometheus main -n default

Name:         main
Namespace:    default
Labels:       prometheus=main
Annotations:  <none>
API Version:  monitoring.coreos.com/v1
Kind:         Prometheus
Metadata:
  Creation Timestamp:  2026-10-23T07:05:53Z
  Generation:          3
  Resource Version:    35801
  UID:                 6913f6c3-e23e-4d00-97f9-5ddf5fd7f8a8
Spec:
  Evaluation Interval:  30s
  Pod Monitor Selector:
    Match Labels:
      Team:   frontend
  Port Name:  web
  Replicas:   1
  Resources:
    Requests:
...

关注点：Generation（声明变更次数）与 status.observedGeneration 是否一致——不一致说明 Operator 还没处理完最新变更；Status.Conditions 里的 message 是调和失败的直接线索。

4.5 Operator 生成的底层资源巡检

Operator 会为每个实例生成一组 Secret（配置、web TLS、TLS 资产等，实测）：

kubectl get secret -n default | grep prometheus-main

NAME                                                 TYPE     DATA   AGE
prometheus-main                                      Opaque   1      9h
prometheus-main-thanos-prometheus-http-client-file   Opaque   1      9h
prometheus-main-tls-assets-0                         Opaque   0      9h
prometheus-main-web-config                           Opaque   1      9h

对应生成 1 个 StatefulSet（kubectl get sts -n default prometheus-main，READY 1/1）。巡检底层资源能区分「CR 声明问题」与「K8s 调度问题」。

五、日志排障命令详解

5.1 Operator 日志（第一现场）

kubectl logs -n monitoring deploy/kps-operator --tail=8

实测回显（截断至 160 字符/行）：

ts=2026-10-23T16:06:40.746569569Z level=info caller=/workspace/pkg/prometheus/server/operator.go:916 msg="sync prometheus" component=prometheus-controller key=d
ts=2026-10-23T16:06:40.767945684Z level=info caller=/workspace/pkg/prometheus/server/operator.go:916 msg="sync prometheus" component=prometheus-controller key=m
ts=2026-10-23T16:09:37.471165003Z level=info caller=/go/pkg/mod/k8s.io/client-go@v0.37.0/rest/warnings.go:107 msg="Warning: v1 Endpoints is deprecated in v1.33+
ts=2026-10-23T16:11:25.062710732Z level=info caller=/workspace/pkg/admission/admission.go:251 msg="Invalid rule" component=admissionwebhook err="5:11: group \"b

日志结构（logfmt 格式）与排查映射：

字段含义排查用法
msg="sync prometheus" + key=<ns>/<name>一次调和动作正常巡检应看到 sync 后无后续 error；狂刷同一 key 即调和风暴（真实案例见 部署指南 9.1 节：双 Operator 抢调和，0.7 秒 3 次 sync）
msg="Invalid rule" + component=admissionwebhook准入校验拒绝了一个坏规则本实测提交括号不闭合的 PromQL 时出现，err 字段带行列号与 parse error 详情
level=error调和失败直接定位 CR 与原因
caller=.../warnings.goclient-go 弃用警告上游依赖提示，可忽略

实时跟随：变更窗口用 kubectl logs -f -n monitoring deploy/kps-operator 观察 sync 顺序，是判断「Operator 是否正确响应了我的变更」的最直接手段。

5.2 Prometheus 实例日志（双容器）

实例 Pod 有两个容器，日志各管一段：

kubectl logs prometheus-kps-prometheus-0 -n monitoring -c config-reloader --tail=3

level=info ts=2026-10-23T15:58:07.361654876Z caller=reloader.go:546 msg="Reload triggered" cfg_in=/etc/prometheus/config/prometheus.yaml.gz cfg_out=/e
level=info ts=2026-10-23T15:58:07.361734819Z caller=reloader.go:328 msg="started watching config file and directories for changes" cfg=/etc/prometheus
level=info ts=2026-10-23T16:05:41.675080928Z caller=reloader.go:546 msg="Reload triggered" cfg_in=/etc/prometheus/config/prometheus.yaml.gz cfg_out=/e

config-reloader 负责「检测 Operator 生成的配置变化 → 触发 Prometheus 热加载」。看到 Reload triggered 说明 CR 变更已传导到实例。

kubectl logs prometheus-kps-prometheus-0 -n monitoring -c prometheus --tail=3

time=2026-10-23T15:58:07.336Z level=INFO source=main.go:1721 msg="Loading configuration file" filename=/etc/prometheus/config_out/prometheus.env.yaml
time=2026-10-23T15:58:07.361Z level=INFO source=main.go:1763 msg="Completed loading of configuration file" db_storage=2.321µs remote_storage=1.703µs
time=2026-10-23T16:05:41.652Z level=INFO source=main.go:1721 msg="Loading configuration file" filename=/etc/prometheus/config_out/prometheus.env.yaml

Completed loading of configuration file = 新配置生效。若出现 FAILED to load configuration 级别日志，配合 4.5 的 Secret 检查与 promtool 离线校验（第七章）定位。

5.3 事件与调度排障

Pod 起不来时三连：kubectl get events -n <ns> --sort-by=.lastTimestamp | tail → kubectl describe pod <pod>（Events 段）→ kubectl describe prometheus <cr>。镜像拉取失败、PVC 未绑定、资源不足都会在 Events 留痕。

六、实例状态验证命令（HTTP API 四维验证）

以下均为对 main 实例（NodePort 30090）的实测。Prometheus 的 4 个只读端点是运维验证的「真相之源」——比看任何 UI 都可靠：

6.1 健康与就绪

curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:30090/-/healthy

HTTP 200

/-/healthy（进程存活）与 /-/ready（配置加载完成可服务）分立，两者独立探测。

6.2 配置维度：生效配置长什么样

curl -s http://localhost:30090/api/v1/status/config

返回 JSON，data.yaml 是当前生效的完整 prometheus.yml。用 grep 快速盘点抓取 job（实测）：

scrape_configs:
- job_name: serviceMonitor/default/example-app/0
- job_name: podMonitor/default/example-app-pods/0

job 命名规律 <资源类型>/<命名空间>/<资源名>/<端点序号>——从 job 名直接反查是哪个 CRD 生效，排障极其高效。

6.3 规则与告警维度

curl -s http://localhost:30090/api/v1/rules

group: example-app.rules
  recording job:http_requests:rate5m health=ok
  alerting ExampleAppAlwaysFiringDemo health=ok state=firing

curl -s http://localhost:30090/api/v1/alerts

ExampleAppAlwaysFiringDemo firing demo

health=ok（表达式合法）、state=inactive→pending→firing（告警生命周期）是规则维度的两个关键状态。

6.4 目标维度

curl -s "http://localhost:30090/api/v1/targets?state=active"

default/example-app-pods http://10.42.0.5:8080/metrics unknown
example-app http://10.42.0.5:8080/metrics up

state=active/dropped 分别看抓取目标与被 relabel 丢弃的目标；health 取值 up/down/unknown。

6.5 Alertmanager 侧验证（v2 API）

curl -s http://localhost:30093/api/v2/status

config.original 字段即 Alertmanager 生效配置（含 Operator 合并的命名空间级路由 monitoring/demo-webhook/demo-webhook，详见 配置与 CRD 详解 8.2 节）。

七、promtool 校验命令详解

7.1 promtool 从哪来（实测获取方式）

promtool 随 Prometheus 一起发布。最省事的来源就是你自己的 Prometheus 实例 Pod——官方镜像内置 promtool，版本与实例完全一致（本次实测提取自 default/prometheus-main-0 的 prometheus 容器，校验出 version 3.14.0 ... revision: d7598b7141418fa35be2b5ec5d0fefb634199610，与实例 /api/v1/status/buildinfo 的 revision 完全一致）：

kubectl exec prometheus-main-0 -n default -c prometheus -- cat /bin/promtool > /usr/local/bin/promtool
chmod +x /usr/local/bin/promtool
promtool --version

promtool, version 3.14.0 (branch: HEAD, revision: d7598b7141418fa35be2b5ec5d0fefb634199610)
  build user:       root@f423027f4410
  build date:       20260817-16:49:19
  go version:       go1.26.6
  platform:         linux/amd64
  tags:             netgo,builtinassets

（也可从 prometheus.io 官方下载对应平台 tar 包安装；生产节点建议用与实例一致的同版本 promtool 校验。）

7.2 promtool check rules：变更前校验规则文件

准备规则文件：PrometheusRule CR 的 spec.groups 即 promtool 认识的规则文件主体，用 yaml 转换后校验（本实测将 example-app-rules 的 groups 提取为 /root/example-app-rules.yaml）。

校验合法规则（实测）：

promtool check rules /root/example-app-rules.yaml

Checking /root/example-app-rules.yaml
  SUCCESS: 2 rules found

校验坏规则（expr: sum(rate(http_requests_total[5m])) >，括号不闭合，实测）：

promtool check rules /root/bad.rules.yaml

Checking /root/bad.rules.yaml
  FAILED:
/root/bad.rules.yaml: 5:11: group "bad.rules", rule 1, "BadPromQL": could not parse expression: 1:32: parse error: unexpected ")" in subquery or range, expected ":" or "]"

echo $?

1

退出码 1，可直接接入 CI：GitOps 流水线在 apply 前跑 promtool check rules，与 Operator 的准入校验（API Server 层拒绝，见 5.1 日志实录）形成双保险——本地 CI 拦一次，集群准入再拦一次。

7.3 promtool check config：校验完整实例配置

导出实例生效配置后校验（实测，配置导出为 /tmp/main-config.yaml 后校验）：

curl -s http://localhost:30090/api/v1/status/config | python3 -c "import json,sys; open('/tmp/main-config.yaml','w').write(json.load(sys.stdin)['data']['yaml'])"
promtool check config /tmp/main-config.yaml

Checking /tmp/main-config.yaml
 SUCCESS: /tmp/main-config.yaml is valid prometheus config file syntax

适用场景：手工排障时对配置做语法层排除，或校验要外发给其他环境的配置。

7.4 promtool query：不开 UI 直查指标

promtool query instant http://localhost:30090 'up{job=~"example-app"}'

up{container="example-app", endpoint="web", instance="10.42.0.5:8080", job="example-app", namespace="default", pod="example-app-84bddd89d7-ls42n", service="example-app"} => 1 @[1792773050.452]

instant 查瞬时值、range 查时间区间、series 查标签集。适合 SSH 会话内快速验证指标与表达式（配合 promtool query instant <url> --eval 'expr' 形式的调试）。

八、变更类命令详解

8.1 扩缩容：必须 patch CR，不能 scale StatefulSet

正确姿势——patch Prometheus CR（实测 1→2 副本）：

kubectl patch prometheus main -n default --type merge -p '{"spec":{"replicas":2}}'

prometheus.monitoring.coreos.com/main patched

约半分钟后观察（实测）：

kubectl get sts,pods -n default

NAME                               READY   AGE
statefulset.apps/prometheus-main   2/2     9h

NAME                               READY   STATUS    RESTARTS        AGE
pod/example-app-84bddd89d7-ls42n   1/1     Running   1 (3h58m ago)   9h
pod/prometheus-main-0              2/2     Running   0               18m
pod/prometheus-main-1              2/2     Running   0               25s

新 Pod prometheus-main-1 由 Operator 自动创建。缩容同理（replicas 改回 1，实测回 1/1）。

反面教材（实测）——直接 scale StatefulSet 会被 Operator 秒级调和回 CR 声明值：

kubectl scale sts prometheus-main -n default --replicas=3

statefulset.apps/prometheus-main scaled

kubectl get sts prometheus-main -n default

NAME              READY   AGE
prometheus-main   1/1     9h

scale 命令回显成功，但 Operator 在下一次调和循环立即把副本数恢复为 CR 声明的 1——Command line scale 与声明式调和的对抗中，Operator 永远获胜。扩缩容唯一正确入口是 CR 的 spec.replicas（分片同理 spec.shards）。

8.2 触发热加载

多数变更无需手工干预：Operator 生成新配置 Secret → config-reloader 检测 → 自动 reload（日志链见 5.2）。若需手工强制重载配置（不重启进程）：

kubectl exec prometheus-main-0 -n default -c prometheus -- kill -HUP 1

实测执行后实例日志立即出现：

time=2026-10-23T16:17:21.656Z level=INFO source=main.go:1690 msg="Loading configuration file" filename=/etc/prometheus/config_out/prometheus.env.yaml
time=2026-10-23T16:17:21.657Z level=INFO source=main.go:1729 msg="Completed loading of configuration file" ... totalDuration=1.212632ms

💡 注意：curl -X POST http://<实例>/-/reload 需要 Prometheus 启动参数 --web.enable-lifecycle，kube-prometheus-stack 默认未开启，因此 HUP 信号（SIGHUP 无需额外参数）是默认部署下更通用的热加载方式。

8.3 升级与版本变更

  • Helm 形态：helm upgrade kps prometheus-community/kube-prometheus-stack ...，完整实录（含 history/rollback）见 部署指南第八章；
  • CR 形态：kubectl patch prometheus <name> -p '{"spec":{"version":"v3.15.0"}}'，Operator 重建 StatefulSet 滚动升级；
  • 升级前用 promtool 校验存量规则在新版本的兼容性，升级后用 4.1 的 get prometheus 确认 READY/AVAILABLE。

8.4 暂停调和（调试利器）

kubectl patch prometheus main -n default --type merge -p '{"spec":{"paused":true}}'

spec.paused: true 后 Operator 停止对底层资源做调和（4.1 巡检时 PAUSED 列变 true），用于紧急止血或手工介入底层资源；调试完记得 paused: false 恢复。

九、注意事项

  1. 扩缩容入口唯一：CR 的 spec.replicas/spec.shards（8.1 实测 scale 会被回滚）；
  2. 双 Operator 互斥：同一集群只保留一个全集群监听的 Operator（风暴实录见部署指南 9.1）；
  3. 校验前置：规则变更先过 promtool check rules（本地 CI）再依赖准入校验（集群），FAILED 退出码 1 可直接驱动流水线失败；
  4. 日志先行：CRD 层异常先看 Operator 日志（msg=sync/Invalid rule/error），实例层异常再看 prometheus/config-reloader 双容器日志；
  5. API 验证闭环：任何「改了没生效」的疑虑，用 /api/v1/status/config → /api/v1/rules → /api/v1/targets 三步闭环定位（配置合并了吗 → 规则加载了吗 → 目标抓到了吗）；
  6. promtool 版本对齐：校验用与实例同版本的 promtool，避免版本间语法差异误报；
  7. metrics 端口自监控：Operator 自身暴露 prometheus_operator_* 指标（0.94.0 起 status conditions 也指标化），监控 Operator 的最好方式是用 Prometheus 监控它（kube-prometheus-stack 已内置 kps-operator ServiceMonitor，见 4.2）。

十、常见问题（FAQ）

Q1：kubectl get prometheus 的 RECONCILED 一直是 False？ 看 kubectl logs -n <operator 所在 ns> deploy/<operator> 的 error 日志；常见原因：CRD 版本不匹配、RBAC 不足、CR 字段校验失败。排除后仍 False 可用 spec.paused 往返触发重新调和。

Q2：改了 ServiceMonitor，targets 一直不变？ 按第六章三步闭环：status/config 里有没有新 job → 没有则是 Operator 没选中（查 labels 与 Prometheus CR 的 selector，见 配置与 CRD 详解 11.1 节实录）→ 有 job 但 targets 无则看 -c prometheus 日志的 reload 与 scrape error。

Q3：告警规则 health=ok 但一直不 firing？ 检查 expr 结果是否真的为真（promtool query instant 直接验证表达式，见 7.4）；for 时长未满足时 state 为 pending。

Q4：promtool 在节点上不存在？ 从实例 Pod 提取（7.1 实测方法），或从 prometheus.io 下载与实例同版本 tar 包安装。

Q5：怎么确认我的 PrometheusRule 被哪个实例加载？ kubectl get prometheus <name> -o jsonpath='{.spec.ruleSelector}' 对照规则 labels；再用 /api/v1/rules 按组名确认（组名在规则文件中唯一，全集群同名组注意区分）。

十一、参考链接