使用Prometheus监控控制节点组件指标
本文将介绍如何使用Prometheus对控制节点的kube-apiserver、kube-controller、kube-scheduler、etcd-server组件进行监控。
通过监控中心查看控制节点组件指标
云原生监控中心已支持对控制节点的kube-apiserver组件进行监控,您在集群中开通云原生监控中心后(安装云原生监控插件版本为3.5.0及以上),可以查看仪表盘中的APIServer视图,监控API指标。
如需对kube-controller、kube-scheduler、etcd-server组件进行监控,请参考以下步骤。

此3个组件监控指标不在容器基础指标范围,监控中心将该类指标上报至AOM后会进行收费,因此监控中心会默认屏蔽采集该类指标。
- 登录CCE控制台,单击集群名称进入集群。
- 在左侧导航栏中选择“配置中心”,并切换至“监控运维配置”页签,修改采集配置。
- 已开启“系统预置采集”:云原生监控插件预置了部分组件的采集策略,您可以单击系统预置采集下的“管理”,开启kube-apiserver、kube-controller、kube-scheduler、etcd-server组件的采集,并支持设置采集全量指标或采集白名单指标,您可按需采集关注的指标,有助于控制AOM数据采集成本。
- 未开启“系统预置采集”:云原生监控插件会自动创建控制节点组件的ServiceMonitor,您可以单击ServiceMonitor下的“管理”,开启kube-apiserver、kube-controller、kube-scheduler、etcd-server组件的采集,默认采集白名单指标。
自动创建的ServiceMonitor默认采集部分白名单指标,如果该指标无法满足您的诉求,请开启“系统预置采集”后进行自定义配置。
- 已开启“系统预置采集”:云原生监控插件预置了部分组件的采集策略,您可以单击系统预置采集下的“管理”,开启kube-apiserver、kube-controller、kube-scheduler、etcd-server组件的采集,并支持设置采集全量指标或采集白名单指标,您可按需采集关注的指标,有助于控制AOM数据采集成本。
- 等待5分钟后,您可前往AOM控制台,在“指标浏览”中找到集群上报的AOM实例,查看上述组件的指标。更多指标说明请参见kube-apiserver组件监控指标说明、kube-controller组件监控指标说明、kube-scheduler组件监控指标说明、etcd-server组件监控指标说明。
图1 查看指标
自建Prometheus采集控制节点组件指标
如果您需要通过Prometheus采集控制节点组件指标,可通过以下指导进行配置。

- 集群版本需要v1.19及以上。
- 在集群中需安装自建的Prometheus,您可参考Prometheus使用Helm模板进行安装。安装自建Prometheus后,还需要使用prometheus-operator纳管该Prometheus实例,具体操作步骤请参见Prometheus Operator。
由于Prometheus(停止维护)插件版本已停止演进,不再支持该功能特性,请避免使用。
- 使用kubectl连接集群。
- 修改Prometheus的ClusterRole。
kubectl edit ClusterRole prometheus -n {namespace}
在rules字段添加以下内容:rules: ... - apiGroups: - proxy.exporter.k8s.io resources: - "*" verbs: ["get", "list", "watch"]
- 创建并编辑kube-apiserver.yaml文件。
vi kube-apiserver.yaml
文件内容如下:apiVersion: monitoring.coreos.com/v1 kind: ServiceMonitor metadata: labels: app.kubernetes.io/name: apiserver name: kube-apiserver namespace: monitoring #修改为Prometheus安装的命名空间 spec: endpoints: - bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token interval: 30s metricRelabelings: - action: keep regex: (aggregator_unavailable_apiservice|apiserver_admission_controller_admission_duration_seconds_bucket|apiserver_admission_webhook_admission_duration_seconds_bucket|apiserver_admission_webhook_admission_duration_seconds_count|apiserver_client_certificate_expiration_seconds_bucket|apiserver_client_certificate_expiration_seconds_count|apiserver_current_inflight_requests|apiserver_request_duration_seconds_bucket|apiserver_request_total|go_goroutines|kubernetes_build_info|process_cpu_seconds_total|process_resident_memory_bytes|rest_client_requests_total|workqueue_adds_total|workqueue_depth|workqueue_queue_duration_seconds_bucket|aggregator_unavailable_apiservice_total|rest_client_request_duration_seconds_bucket) sourceLabels: - __name__ - action: drop regex: apiserver_request_duration_seconds_bucket;(0.15|0.25|0.3|0.35|0.4|0.45|0.6|0.7|0.8|0.9|1.25|1.5|1.75|2.5|3|3.5|4.5|6|7|8|9|15|25|30|50) sourceLabels: - __name__ - le port: https scheme: https tlsConfig: caFile: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt serverName: kubernetes jobLabel: component namespaceSelector: matchNames: - default selector: matchLabels: component: apiserver provider: kubernetes
创建ServiceMonitor:
kubectl apply -f kube-apiserver.yaml
- 创建并编辑kube-controller.yaml文件。
vi kube-controller.yaml
文件内容如下:apiVersion: monitoring.coreos.com/v1 kind: ServiceMonitor metadata: labels: app.kubernetes.io/name: kube-controller name: kube-controller-manager namespace: monitoring #修改为Prometheus安装的命名空间 spec: endpoints: - bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token interval: 15s honorLabels: true port: https relabelings: - regex: (.+) replacement: /apis/proxy.exporter.k8s.io/v1beta1/kube-controller-proxy/${1}/metrics sourceLabels: - __address__ targetLabel: __metrics_path__ - regex: (.+) replacement: ${1} sourceLabels: - __address__ targetLabel: instance - replacement: kubernetes.default.svc.cluster.local:443 targetLabel: __address__ scheme: https tlsConfig: caFile: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt jobLabel: app namespaceSelector: matchNames: - kube-system selector: matchLabels: app: kube-controller-proxy version: v1
创建ServiceMonitor:
kubectl apply -f kube-controller.yaml
- 创建并编辑kube-scheduler.yaml文件。
vi kube-scheduler.yaml
文件内容如下:apiVersion: monitoring.coreos.com/v1 kind: ServiceMonitor metadata: labels: app.kubernetes.io/name: kube-scheduler name: kube-scheduler namespace: monitoring #修改为Prometheus安装的命名空间 spec: endpoints: - bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token interval: 15s honorLabels: true port: https relabelings: - regex: (.+) replacement: /apis/proxy.exporter.k8s.io/v1beta1/kube-scheduler-proxy/${1}/metrics sourceLabels: - __address__ targetLabel: __metrics_path__ - regex: (.+) replacement: ${1} sourceLabels: - __address__ targetLabel: instance - replacement: kubernetes.default.svc.cluster.local:443 targetLabel: __address__ scheme: https tlsConfig: caFile: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt jobLabel: app namespaceSelector: matchNames: - kube-system selector: matchLabels: app: kube-scheduler-proxy version: v1
创建ServiceMonitor:
kubectl apply -f kube-scheduler.yaml
- 创建并编辑etcd-server.yaml文件。
vi etcd-server.yaml
文件内容如下:apiVersion: monitoring.coreos.com/v1 kind: ServiceMonitor metadata: labels: app.kubernetes.io/name: etcd-server name: etcd-server namespace: monitoring #修改为Prometheus安装的命名空间 spec: endpoints: - bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token interval: 15s honorLabels: true port: https relabelings: - regex: (.+) replacement: /apis/proxy.exporter.k8s.io/v1beta1/etcd-server-proxy/${1}/metrics sourceLabels: - __address__ targetLabel: __metrics_path__ - regex: (.+) replacement: ${1} sourceLabels: - __address__ targetLabel: instance - replacement: kubernetes.default.svc.cluster.local:443 targetLabel: __address__ scheme: https tlsConfig: caFile: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt jobLabel: app namespaceSelector: matchNames: - kube-system selector: matchLabels: app: etcd-server-proxy version: v1
创建ServiceMonitor:
kubectl apply -f etcd-server.yaml
- 创建完成后,访问Prometheus,单击“Status > Targets”,可以查看到Prometheus监控目标中已包含上述三个控制节点组件。
kube-apiserver组件监控指标说明
分类 |
指标清单 |
类型 |
解释 |
典型PromQL查询示例 |
---|---|---|---|---|
请求相关指标 |
apiserver_request_total |
Counter |
统计kube-apiserver接收到的所有API请求的累计数量,按多维标签分类。 例如:
|
|
apiserver_request_duration_seconds_bucket |
Histogram |
统计API请求的延迟分布,按不同标签维度(如请求类型、资源、状态码等)分组,可用于分析P50、P90、P99延迟、识别慢请求和高延迟资源、监控kube-apiserver性能瓶颈等场景。 部分关键标签说明如下:
|
|
|
apiserver_current_inflight_requests |
Gauge |
用于跟踪当前正在处理的API请求数量。该指标通常包含以下标签:
|
|
|
etcd_request_duration_seconds_bucket |
Histogram |
该指标用于记录etcd处理请求的延迟时间分布。 部分关键标签说明如下:
|
|
|
错误和限流指标 |
apiserver_flowcontrol_current_executing_requests |
Gauge |
Kubernetes API优先级与公平性(API Priority and Fairness,简称APF)机制的核心监控指标之一,用于实时反映API Server当前正在处理的请求负载情况。详情请参见API优先级和公平性。 部分关键标签说明如下:
|
|
apiserver_flowcontrol_current_inqueue_requests |
Gauge |
该指标表示当前在API Server流控队列中等待执行的请求数量,这些请求已被接收但尚未开始处理,通常是因为当前并发请求数已达到配置的限制。详情请参见API优先级和公平性。 部分关键标签说明如下:
|
||
apiserver_flowcontrol_nominal_limit_seats |
Gauge |
表示每个优先级级别(Priority Level)的理论最大并发请求配额。详情请参见API优先级和公平性。 该指标通常使用priority_level标签进行分类,标识请求所属的优先级级别(如system、workload-high等)。 |
|
|
apiserver_flowcontrol_current_limit_seats |
Gauge |
表示每个优先级级别(Priority Level)当前实际允许的最大并发请求数,可以了解当前API Server的负载情况,特别是在高负载情况下,可以判断是否需要调整流量控制策略。详情请参见API优先级和公平性。 与nominal_limit_seats不同,此值可能会受全局流量控制策略影响。 该指标通常使用priority_level标签进行分类,标识请求所属的优先级级别(如system、workload-high等)。 |
查看特定优先级当前实际允许的最大并发请求数
apiserver_flowcontrol_current_limit_seats{priority_level="system"} |
|
apiserver_flowcontrol_current_executing_seats |
Gauge |
表示某个优先级队列中当前已占用的并发资源量,反映了当前队列中正在消耗的并发资源,可以了解队列的实际负载情况。详情请参见API优先级和公平性。该指标通常使用priority_level标签进行分类,标识请求所属的优先级级别(如system、workload-high等)。 如果current_executing_seats接近current_limit_seats,表明该队列的并发资源可能即将耗尽。您可以提升集群的修改类API请求最大并发数 (max-mutating-requests-inflight)和非修改类API请求最大并发数 (max-requests-inflight)的参数取值以优化配置,操作详情请参见修改CCE集群配置。 |
|
|
apiserver_flowcontrol_current_inqueue_seats |
Gauge |
表示各优先级级别在队列中等待的请求所占用的并发资源量。详情请参见API优先级和公平性。 该指标通常使用priority_level标签进行分类,标识请求所属的优先级级别(如system、workload-high等)。 |
|
|
apiserver_flowcontrol_request_execution_seconds_bucket |
Histogram |
表示API请求执行时间的分布情况。详情请参见API优先级和公平性。 部分关键标签说明如下:
|
|
|
apiserver_flowcontrol_request_wait_duration_seconds_bucket |
Histogram |
表示API请求在队列中等待时间的分布情况。详情请参见API优先级和公平性。 部分关键标签说明如下:
|
|
|
apiserver_flowcontrol_dispatched_requests_total |
Counter |
表示已经被调度(即开始处理)的API请求总数。详情请参见API优先级和公平性。 |
|
|
apiserver_flowcontrol_rejected_requests_total |
Counter |
表示被拒绝的API请求总数。请求被拒绝通常是因为超过流量控制限制或资源不足。详情请参见API优先级和公平性。 部分关键标签说明如下:
|
|
|
apiserver_flowcontrol_request_concurrency_limit |
Gauge |
表示某个优先级队列的最大并发限制。 该指标在Kubernetes 1.30版本变为Deprecated,自1.31版本起移除,1.31及以上版本的集群中建议使用apiserver_flowcontrol_nominal_limit_seats指标代替。 |
查看当前全局并发限制 apiserver_flowcontrol_request_concurrency_limit |
|
认证和授权指标 |
apiserver_admission_controller_admission_duration_seconds_bucket |
Histogram |
表示API请求在准入控制器(Admission Controller)中的处理时间分布。 部分关键标签说明如下:
|
|
apiserver_admission_webhook_admission_duration_seconds_bucket |
Histogram |
表示Webhook准入控制器(Admission Webhook)的处理时间分布。 |
计算P99处理时间 histogram_quantile(0.99,sum(rate(apiserver_admission_webhook_admission_duration_seconds_bucket[5m])) by (le, name)) |
|
服务可用性指标 |
up |
Gauge |
表示服务的可用性。
|
查看当前服务可用性 up |
kube-controller组件监控指标说明
指标清单 |
类型 |
解释 |
典型PromQL查询示例 |
---|---|---|---|
workqueue_adds_total |
Counter |
工作队列(Workqueue)处理的新增事件(Adds)数量。 |
|
workqueue_depth |
Gauge |
当前的工作队列深度。如果队列深度长时间保持在较高水平,表明Controller不能及时处理队列中的任务,导致任务堆积。 |
查看所有队列深度
workqueue_depth |
workqueue_queue_duration_seconds_bucket |
Histogram |
任务在工作队列中存在的时长(单位:秒)。 部分关键标签说明如下:
|
|
rest_client_requests_total |
Counter |
Kubernetes客户端发起的HTTP请求次数。 部分关键标签说明如下:
|
|
rest_client_request_duration_seconds_bucket |
Histogram |
客户端HTTP请求时延。 部分关键标签说明如下:
|
|
kube-scheduler组件监控指标说明
指标清单 |
类型 |
解释 |
典型PromQL查询示例 |
---|---|---|---|
scheduler_scheduler_cache_size |
Gauge |
调度器缓存中当前保存的Node、Pod、AssumedPod(假定要调度的Pod)数量。 |
查看当前Pod的缓存数量 scheduler_scheduler_cache_size{type="pod"} |
scheduler_pending_pods |
Gauge |
当前处于待调度状态的Pod数量,可帮助识别调度瓶颈。 该指标通常使用queue标签进行分类:
|
查看特定的队列中的Pod数 scheduler_pending_pods{queue="backoff"} |
scheduler_pod_scheduling_attempts_bucket |
Histogram |
调度器尝试调度Pod的次数。 该指标通常关注le标签,取值为1、2、4、8、16、+Inf。 |
检测高频重试(>8次尝试)
sum(rate(scheduler_pod_scheduling_attempts_bucket{le="+Inf"}[5m]))- sum(rate(scheduler_pod_scheduling_attempts_bucket{le="8"}[5m])) |
etcd-server组件监控指标说明
分类 |
指标清单 |
类型 |
解释 |
典型PromQL查询示例 |
---|---|---|---|---|
etcd的Leader状态指标 |
etcd_server_has_leader |
Gauge |
etcd会将集群中的某个成员(Member)选举为“Leader”,即主节点,而其他成员则作为“Follower”,即从节点。Leader会定期向所有Member发送心跳,以保持集群稳定。 该指标etcd实例中是否存在主节点。
|
查看etcd主节点状态 etcd_server_has_leader |
etcd_server_is_leader |
Gauge |
etcd实例是否为Leader。
|
查看etcd是否为Leader etcd_server_is_leader |
|
etcd_server_leader_changes_seen_total |
Counter |
etcd累计Leader切换次数。 |
监控1小时内Leader切换频率 rate(etcd_server_leader_changes_seen_total[1h]) |
|
etcd存储指标 |
etcd_mvcc_db_total_size_in_bytes |
Gauge |
etcd数据库总文件大小。 |
计算存储空间利用率 etcd_mvcc_db_total_size_in_use_in_bytes / etcd_mvcc_db_total_size_in_bytes |
etcd_mvcc_db_total_size_in_use_in_bytes |
Gauge |
etcd实际使用的存储空间。 |
||
etcd_debugging_mvcc_keys_total |
Gauge |
etcd中存储的所有键(Key)的数量。 |
监控Key数量增长 rate(etcd_debugging_mvcc_keys_total[5m]) |
|
etcd写入性能指标 |
etcd_disk_backend_commit_duration_seconds_bucket |
Histogram |
etcd数据落盘耗时分布,即在etcd中数据变更写入到存储后端并成功提交(commit)所花费的时间。 |
计算P99写入延迟 histogram_quantile(0.99,rate(etcd_disk_backend_commit_duration_seconds_bucket[5m])) |
etcd_server_proposals_committed_total |
Gauge |
etcd成功提交的Proposal数量。 |
计算写入失败率 rate(etcd_server_proposals_failed_total[5m]) / rate(etcd_server_proposals_committed_total[5m]) |
|
etcd_server_proposals_applied_total |
Gauge |
成功应用或执行的Proposal数量。 |
计算写入成功率 rate(etcd_server_proposals_applied_total[5m]) / rate(etcd_server_proposals_committed_total[5m]) |
|
etcd_server_proposals_pending |
Gauge |
待处理的Proposal数量。 |
检测写入积压 etcd_server_proposals_pending |
|
etcd_server_proposals_failed_total |
Counter |
处理失败的Proposal数量。 |
计算写入失败率 rate(etcd_server_proposals_failed_total[5m]) / rate(etcd_server_proposals_committed_total[5m]) |
相关文档
更多关于Kubernetes系统组件指标的说明,请参见Kubernetes Metrics Reference。