Kubernetes 系统组件的度量

系统组件指标可以更好地了解它们的内部情况。指标对于构建仪表盘和告警特别有用。

Kubernetes 组件以 Prometheus 格式 发送指标。这种格式是结构化的纯文本，设计目的是为了让人和机器都能阅读。

Kubernetes 中的指标

在大多数情况下，指标可以通过 HTTP 服务器的 /metrics 端点获取。对于默认不暴露端点的组件，可以使用 --bind-address 标志启用它。

这些组件的示例

在生产环境中，你可能需要配置 Prometheus Server 或其他指标收集器，以定期收集这些指标，并将其存储在某种时间序列数据库中。

请注意，kubelet 还在 /metrics/cadvisor、/metrics/resource 和 /metrics/probes 端点暴露指标。这些指标的生命周期不同。

如果你的集群使用 RBAC，读取指标需要通过用户、组或 ServiceAccount 的授权，该用户、组或 ServiceAccount 具有允许访问 /metrics 的 ClusterRole。例如：

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: prometheus
rules:
  - nonResourceURLs:
      - "/metrics"
    verbs:
      - get

指标生命周期

Alpha 指标 → 稳定指标 → 弃用指标 → 隐藏指标 → 删除指标

Alpha 指标没有稳定性保证。这些指标可能随时修改或删除。

稳定指标保证不会改变。这意味着：

  • 没有弃用签名的稳定指标不会被删除或重命名
  • 稳定指标的类型不会被修改

弃用指标计划删除，但仍可使用。这些指标包含关于它们何时被弃用的版本信息。

例如

  • 弃用前

    # HELP some_counter this counts things
# TYPE some_counter counter
some_counter 0

  • 弃用后

    # HELP some_counter (Deprecated since 1.15.0) this counts things
# TYPE some_counter counter
some_counter 0

隐藏指标不再发布用于抓取，但仍可使用。要使用隐藏指标，请参阅显示隐藏指标部分。

删除指标不再发布且无法使用。

显示隐藏指标

如上所述，管理员可以通过在特定二进制文件上使用命令行标志来启用隐藏指标。这旨在用作管理员的应急措施，以防他们错过了上次发布中弃用指标的迁移。

标志 show-hidden-metrics-for-version 接受一个版本，你希望显示该版本中弃用的指标。版本以 x.y 形式表示，其中 x 是主版本，y 是次版本。即使指标可能在补丁发布中被弃用，也不需要补丁版本，因为指标弃用策略是针对次要版本运行的。

该标志只能将上一个次要版本作为其值。如果管理员将上一个版本设置为 show-hidden-metrics-for-version，则所有以前隐藏的指标都将发出。不允许使用过旧的版本，因为这违反了指标弃用策略。

以指标 A 为例，假设 A 在 1.n 中被弃用。根据指标弃用策略，我们可以得出以下结论：

  • 在版本 1.n 中，该指标已被弃用，并且可以默认发出。
  • 在版本 1.n+1 中，该指标默认隐藏，可以通过命令行 show-hidden-metrics-for-version=1.n 发出。
  • 在版本 1.n+2 中，该指标应从代码库中删除。不再有应急措施。

如果你从版本 1.12 升级到 1.13，但仍依赖于在 1.12 中弃用的指标 A，则应通过命令行设置隐藏指标：--show-hidden-metrics=1.12，并记住在升级到 1.14 之前删除此指标依赖项。

组件指标

kube-controller-manager 指标

控制器管理器指标提供了关于控制器管理器性能和健康状况的重要信息。这些指标包括常见的 Go 语言运行时指标（如 go_routine 计数）和控制器特定指标（如 etcd 请求延迟或 Cloudprovider（AWS、GCE、OpenStack）API 延迟），可用于衡量集群的健康状况。

从 Kubernetes 1.7 开始，GCE、AWS、Vsphere 和 OpenStack 的存储操作提供了详细的 Cloudprovider 指标。这些指标可用于监控持久卷操作的健康状况。

例如，对于 GCE，这些指标被称为：

cloudprovider_gce_api_request_duration_seconds { request = "instance_list"}
cloudprovider_gce_api_request_duration_seconds { request = "disk_insert"}
cloudprovider_gce_api_request_duration_seconds { request = "disk_delete"}
cloudprovider_gce_api_request_duration_seconds { request = "attach_disk"}
cloudprovider_gce_api_request_duration_seconds { request = "detach_disk"}
cloudprovider_gce_api_request_duration_seconds { request = "list_disk"}

kube-scheduler 指标

功能状态： Kubernetes v1.21 [beta]

调度器公开可选指标，报告所有正在运行的 Pod 的请求资源和所需限制。这些指标可用于构建容量规划仪表板，评估当前或历史调度限制，快速识别由于资源不足而无法调度的负载，以及将实际使用情况与 Pod 请求进行比较。

kube-scheduler 标识为每个 Pod 配置的资源请求和限制；当请求或限制不为零时，kube-scheduler 报告一个指标时间序列。时间序列的标签包括：

  • 命名空间
  • Pod 名称
  • Pod 调度到的节点，如果尚未调度则为空字符串
  • 优先级
  • 为该 Pod 分配的调度器
  • 资源名称（例如，cpu）
  • 如果已知资源的单位（例如，cores）

一旦 Pod 完成（restartPolicy 为 Never 或 OnFailure 且处于 Succeeded 或 Failed Pod 阶段，或者已被删除且所有容器都处于终止状态），该序列将不再报告，因为调度器现在可以自由调度其他 Pod 运行。这两个指标被称为 kube_pod_resource_request 和 kube_pod_resource_limit。

这些指标在 HTTP 端点 /metrics/resources 上公开。它们需要对 /metrics/resources 端点进行授权，通常通过具有 get 动词的 ClusterRole 授予对 /metrics/resources 非资源 URL 的访问权限。

在 Kubernetes 1.21 中，你必须使用 --show-hidden-metrics-for-version=1.20 标志才能公开这些 Alpha 稳定性的指标。

kubelet 压力停顿信息 (PSI) 指标

特性状态： Kubernetes v1.34 [beta]

作为一项 Beta 功能，Kubernetes 允许你配置 kubelet 来收集 CPU、内存和 I/O 使用情况的 Linux 内核压力停顿信息 (PSI)。信息在节点、Pod 和容器级别收集。这些指标在 /metrics/cadvisor 端点上公开，名称如下：

container_pressure_cpu_stalled_seconds_total
container_pressure_cpu_waiting_seconds_total
container_pressure_memory_stalled_seconds_total
container_pressure_memory_waiting_seconds_total
container_pressure_io_stalled_seconds_total
container_pressure_io_waiting_seconds_total

此功能通过设置 KubeletPSI 功能门默认启用。这些信息也暴露在汇总 API 中。

你可以在理解 PSI 指标中了解如何解释 PSI 指标。

要求

压力停顿信息需要：

禁用指标

你可以通过命令行标志 --disabled-metrics 显式关闭指标。如果一个指标导致性能问题，这可能是需要做的。输入是一个被禁用指标的列表（即 --disabled-metrics=metric1,metric2）。

指标基数强制

具有无界维度的指标可能会导致它们所检测的组件出现内存问题。为了限制资源使用，你可以使用 --allow-metric-labels 命令行选项动态配置指标的标签值的允许列表。

在 Alpha 阶段，该标志只能接受一系列映射作为指标标签允许列表。每个映射的格式为 <metric_name>,<label_name>=<allowed_labels>，其中 <allowed_labels> 是可接受标签名称的逗号分隔列表。

整体格式如下：

--allow-metric-labels <metric_name>,<label_name>='<allow_value1>, <allow_value2>...', <metric_name2>,<label_name>='<allow_value1>, <allow_value2>...', ...

这是一个例子：

--allow-metric-labels number_count_metric,odd_number='1,3,5', number_count_metric,even_number='2,4,6', date_gauge_metric,weekend='Saturday,Sunday'

除了从 CLI 指定之外，这也可以在配置文件中完成。你可以使用组件的 --allow-metric-labels-manifest 命令行参数指定该配置文件的路径。以下是该配置文件内容的示例：

"metric1,label2": "v1,v2,v3"
"metric2,label1": "v1,v2,v3"

此外，cardinality_enforcement_unexpected_categorizations_total 元指标记录了基数强制期间意外分类的计数，即每当遇到与允许列表约束不符的标签值时。

下一步

上次修改时间：2025 年 8 月 4 日 晚上 11:57 PST：将“理解 PSI 指标”移至新的参考文档 (8e40772997)