概述

kube-state-metrics (KSM) 是一个简单的服务，它监听 Kubernetes API 服务器并生成有关对象状态的指标。（请参阅下面的指标部分中的示例。）它不专注于单个 Kubernetes 组件的健康状况，而是关注内部各种对象的健康状况，如部署、节点和 Pod。

kube-state-metrics 的目标是从 Kubernetes API 对象生成指标，而不进行修改。这确保了 kube-state-metrics 提供的功能与 Kubernetes API 对象本身具有相同的稳定性。反过来，这意味着在某些情况下，kube-state-metrics 可能不会显示与 kubectl 完全相同的值，因为 kubectl 应用了某些启发式方法来显示易于理解的信息。kube-state-metrics 公开未经修改的 Kubernetes API 原始数据，这样用户就可以获得所需的所有数据，并根据需要进行启发式处理。

指标通过 HTTP 端点 /metrics 在监听端口（默认为 8080）上公开。它们以纯文本形式提供。它们设计用于由 Prometheus 本身或兼容 Prometheus 客户端端点抓取的抓取器消费。您也可以在浏览器中打开 /metrics 查看原始指标。请注意，/metrics 端点上公开的指标反映了 Kubernetes 集群的当前状态。当 Kubernetes 对象被删除时，它们在 /metrics 端点上将不再可见。

[!注意] 本 README 是从模板生成的。请在那里进行更改并运行 make generate-template。

最多会记录 5 个 kube-state-metrics 和 5 个 Kubernetes 发布版本。通常建议使用最新版本的 kube-state-metrics。如果您运行的是非常新的 Kubernetes 版本，您可能需要使用未发布的版本以获得完整的支持资源范围。如果您运行的是旧版本的 Kubernetes，您可能需要运行旧版本以获得对所有资源的完全支持。请注意，维护者只会支持最新版本。旧版本可能会得到社区感兴趣用户的支持。

kube-state-metrics	Kubernetes client-go 版本
v2.9.2	v1.26
v2.10.1	v1.27
v2.11.0	v1.28
v2.12.0	v1.29
v2.13.0	v1.30
main	v1.30

资源组版本兼容性

Kubernetes 中的资源可能会发展，即在不同的 Kubernetes 版本中，资源的组版本可能从 alpha 变为 beta，最终变为 GA。目前，kube-state-metrics 只会使用最新版本中可用的最旧 API。

容器镜像

最新的容器镜像可以在以下位置找到：

registry.k8s.io/kube-state-metrics/kube-state-metrics:v2.13.0（架构：amd64、arm、arm64、ppc64le 和 s390x）
在这里查看所有多架构镜像

指标文档

基于 Kubernetes alpha API 的任何资源和指标都不包含在任何稳定性保证中，可能会在任何给定的版本中发生变化。

有关公开指标的更多信息，请参阅 docs 目录。

标签名称冲突解决

*_labels 系列指标将 Kubernetes 标签作为 Prometheus 标签公开。由于 Kubernetes 在允许标签名称中使用的字符方面比 Prometheus 更宽松，我们会自动将不支持的字符转换为下划线。例如，app.kubernetes.io/name 变为 label_app_kubernetes_io_name。

当多个 Kubernetes 标签（如 foo-bar 和 foo_bar）被转换为相同的 Prometheus 标签 label_foo_bar 时，这种转换可能会产生冲突。

Kube-state-metrics 会自动添加后缀 _conflictN 来解决这种冲突，因此它将上述标签转换为 label_foo_bar_conflict1 和 label_foo_bar_conflict2。

如果您希望对这种冲突的解决方式有更多控制，您可能需要考虑在堆栈的不同层面解决这个问题，例如，使用准入 Webhook 来标准化 Kubernetes 标签，确保不存在可能的冲突。

Kube-state-metrics 自身指标

kube-state-metrics 在 --telemetry-host 和 --telemetry-port（默认为 8081）下公开其自身的一般进程指标。

kube-state-metrics 还公开了列表和监视成功和错误指标。这些可用于计算列表或监视资源的错误率。如果您在指标中遇到这些错误，很可能是配置或权限问题，下一步应该查看 kube-state-metrics 的日志。

上述指标的示例：

kube_state_metrics_list_total{resource="*v1.Node",result="success"} 1
kube_state_metrics_list_total{resource="*v1.Node",result="error"} 52
kube_state_metrics_watch_total{resource="*v1beta1.Ingress",result="success"} 1

kube-state-metrics 还公开了一些 HTTP 请求指标，例如：

http_request_duration_seconds_bucket{handler="metrics",method="get",le="2.5"} 30
http_request_duration_seconds_bucket{handler="metrics",method="get",le="5"} 30
http_request_duration_seconds_bucket{handler="metrics",method="get",le="10"} 30
http_request_duration_seconds_bucket{handler="metrics",method="get",le="+Inf"} 30
http_request_duration_seconds_sum{handler="metrics",method="get"} 0.021113919999999998
http_request_duration_seconds_count{handler="metrics",method="get"} 30

kube-state-metrics 还公开了构建和配置指标：

kube_state_metrics_build_info{branch="main",goversion="go1.15.3",revision="6c9d775d",version="v2.0.0-beta"} 1
kube_state_metrics_shard_ordinal{shard_ordinal="0"} 0
kube_state_metrics_total_shards 1

kube_state_metrics_build_info 用于公开版本和其他构建信息。有关信息模式的更多用法，请查看这里的博客文章。分片指标公开了 --shard 和 --total-shards 标志，可用于验证运行时配置，请参见 /examples/prometheus-alerting-rules。

kube-state-metrics 还公开了关于其配置文件和自定义资源状态配置文件的指标：

kube_state_metrics_config_hash{filename="crs.yml",type="customresourceconfig"} 2.38272279311849e+14
kube_state_metrics_config_hash{filename="config.yml",type="config"} 2.65285922340846e+14
kube_state_metrics_last_config_reload_success_timestamp_seconds{filename="crs.yml",type="customresourceconfig"} 1.6704882592037103e+09
kube_state_metrics_last_config_reload_success_timestamp_seconds{filename="config.yml",type="config"} 1.6704882592035313e+09
kube_state_metrics_last_config_reload_successful{filename="crs.yml",type="customresourceconfig"} 1
kube_state_metrics_last_config_reload_successful{filename="config.yml",type="config"} 1

扩展 kube-state-metrics

资源建议

kube-state-metrics 的资源使用随集群中 Kubernetes 对象(Pod/节点/部署/Secret 等)的规模而变化。在某种程度上,集群中的 Kubernetes 对象数量与集群的节点数成正比。

作为一般规则,你应该分配:

250MiB 内存
0.1 个 CPU 核心

注意,如果 CPU 限制设置得太低,kube-state-metrics 的内部队列将无法足够快地处理,随着队列长度增加会导致内存消耗增加。如果你遇到由高内存分配或 CPU 节流引起的问题,请尝试增加 CPU 限制。

延迟

在一个 100 节点集群的扩展测试中,延迟数据如下:

"Perc50": 259615384 ns,
"Perc90": 475000000 ns,
"Perc99": 906666666 ns.

关于成本的说明

默认情况下,kube-state-metrics 会暴露集群中事件的多个指标。如果你的集群中有大量频繁更新的资源,你可能会发现这些指标会摄入大量数据。这可能会在某些云提供商那里产生高昂的成本。请花点时间配置你想要暴露的指标,并查阅 Kubernetes 环境的文档,以避免意外的高成本。

kube-state-metrics 与 metrics-server 的比较

metrics-server 是一个受 Heapster 启发的项目,它的实现是为了服务于 Kubernetes 监控架构中核心指标管道的目标。它是一个集群级组件,通过 Metrics API 定期从所有 Kubernetes 节点的 Kubelet 抓取指标。这些指标被聚合、存储在内存中,并以 Metrics API 格式提供服务。metrics-server 只存储最新的值,不负责将指标转发到第三方目的地。

kube-state-metrics 专注于从 Kubernetes 对象状态生成全新的指标(例如基于部署、副本集等的指标)。它在内存中保存 Kubernetes 状态的完整快照,并持续基于此生成新的指标。和 metrics-server 一样,它也不负责将其指标导出到任何地方。

将 kube-state-metrics 作为一个独立的项目还使得可以从 Prometheus 等监控系统访问这些指标。

水平分片

为了水平分片 kube-state-metrics,已经实现了一些自动分片功能。它通过以下标志进行配置:

--shard (从零开始索引)
--total-shards

分片是通过对 Kubernetes 对象的 UID 进行 md5 sum,然后与分片总数进行模运算来完成的。每个分片决定相应的 kube-state-metrics 实例是否处理该对象。请注意,这意味着即使进行了分片,所有 kube-state-metrics 实例仍将有所有对象的网络流量和反序列化对象的资源消耗,而不仅仅是它们负责的对象。要进一步优化这一点,Kubernetes API 需要支持分片的列表/监视功能。在最佳情况下,每个分片的内存消耗将比未分片设置的 1/n。通常,kube-state-metrics 需要进行内存和延迟优化,以便能够快速向 Prometheus 返回其指标。减少 kube-state-metrics 和 kube-apiserver 之间延迟的一种方法是使用 --use-apiserver-cache 标志运行 KSM。除了减少延迟外,此选项还将降低 etcd 的负载。

应谨慎使用分片,并应设置额外的监控,以确保分片设置正确且正常运行(例如,为总分片中的每个分片配置实例)。

自动分片

自动分片允许每个分片在部署在 StatefulSet 中时发现其名义位置,这对于自动配置分片很有用。这是一个实验性功能,可能会被破坏或无预警移除。

要启用自动分片,必须通过 StatefulSet 运行 kube-state-metrics,并通过 --pod 和 --pod-namespace 标志将 pod 名称和命名空间传递给 kube-state-metrics 进程。演示自动分片功能的示例清单可以在 /examples/autosharding 中找到。

这种部署分片的方式在你想通过单个 Kubernetes 资源(在这种情况下是单个 StatefulSet)管理 KSM 分片而不是每个分片使用一个 Deployment 时很有用。当部署大量分片时,这种优势可能特别显著。

使用自动分片设置的缺点来自 StatefulSet 支持的滚动更新策略。当由 StatefulSet 管理时,pod 会一个接一个地被替换,每个 pod 首先被终止然后重新创建。除了这种滚动更新较慢之外,它还会导致每个分片短暂停机。如果 Prometheus 在滚动更新期间进行抓取,可能会错过 kube-state-metrics 导出的一些指标。

用于 pod 指标的 Daemonset 分片

对于 pod 指标,可以使用以下标志按节点进行分片:

--node=$(NODE_NAME)

每个 kube-state-metrics pod 使用 FieldSelector (spec.nodeName) 来仅在同一节点上监视/列出 pod 指标。

一个 daemonset kube-state-metrics 示例:

apiVersion: apps/v1
kind: DaemonSet
spec:
  template:
    spec:
      containers:
      - image: registry.k8s.io/kube-state-metrics/kube-state-metrics:IMAGE_TAG
        name: kube-state-metrics
        args:
        - --resource=pods
        - --node=$(NODE_NAME)
        env:
        - name: NODE_NAME
          valueFrom:
            fieldRef:
              apiVersion: v1
              fieldPath: spec.nodeName

要跟踪未分配的 pod 的指标,你需要添加一个额外的部署并设置 --track-unscheduled-pods,如下例所示:

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - image: registry.k8s.io/kube-state-metrics/kube-state-metrics:IMAGE_TAG
        name: kube-state-metrics
        args:
        - --resources=pods
        - --track-unscheduled-pods

其他指标可以通过水平分片进行分片。

设置

使用 go get 将此项目安装到你的 $GOPATH:

go get k8s.io/kube-state-metrics

构建 Docker 容器

只需在此根文件夹中运行以下命令,它将创建一个独立的、静态链接的二进制文件并构建一个 Docker 镜像:

make container

使用

只需构建 kube-state-metrics 并在 Kubernetes pod 内运行它,该 pod 应具有对 Kubernetes 集群具有只读访问权限的服务账户令牌。

prometheus-operator/kube-prometheus 堆栈的用户

(kube-prometheus) 堆栈将 kube-state-metrics 作为其组件之一安装;如果你正在使用 kube-prometheus 堆栈,则不需要安装 kube-state-metrics。

如果你想修改 kube-prometheus 的默认配置,例如启用非默认指标,请查看自定义 Kube-Prometheus。

Kubernetes 部署

要部署此项目,你可以简单地运行 kubectl apply -f examples/standard,这将创建一个 Kubernetes 服务和部署。(注意:如果你的 kubernetes 集群版本不是 1.8+,请调整某些资源的 apiVersion,查看 yaml 文件以获取更多信息)。

为了让 Prometheus 发现 kube-state-metrics 实例,建议为 kube-state-metrics 创建一个特定的 Prometheus 抓取配置,该配置可以获取两个指标端点。不建议使用基于注解的发现,因为只能选择其中一个端点,而且在大多数情况下,kube-state-metrics 有特殊的身份验证和授权要求,因为它基本上通过指标端点授予对大多数可用信息的读取访问权限。

注意: Google Kubernetes Engine (GKE) 用户 - GKE 有严格的角色权限,这将阻止创建 kube-state-metrics 角色和角色绑定。要解决这个问题,你可以通过运行以下一行命令来为你的 GCP 身份赋予 cluster-admin 角色:

kubectl create clusterrolebinding cluster-admin-binding --clusterrole=cluster-admin --user=$(gcloud info --format='value(config.account)')

请注意,你的 GCP 身份区分大小写,但截至 Google Cloud SDK 221.0.0 版本,gcloud info 不区分大小写。这意味着如果你的 IAM 成员包含大写字母,上述一行命令可能对你不起作用。如果在运行上述命令和 kubectl apply -f examples/standard 后收到 403 禁止响应,请在 https://console.cloud.google.com/iam-admin/iam?project=PROJECT_ID 检查与你的账户关联的 IAM 成员。如果它包含大写字母,你可能需要将上述命令中的 --user 标志设置为 https://console.cloud.google.com/iam-admin/iam?project=PROJECT_ID 中列出的区分大小写的角色。

运行上述命令后,如果看到 Clusterrolebinding "cluster-admin-binding" created,则可以继续设置此服务。

健康检查端点

以下健康检查端点可用(self 指的是遥测端口,而 main 指的是暴露端口):

/healthz（在main上公开）：如果应用程序正在运行，则返回200状态码。我们建议将此用于启动探针。
/livez（在main上公开）：如果应用程序不受Kubernetes API服务器中断的影响，则返回200状态码。我们建议将此用于存活探针。
/readyz（在self上公开）：如果应用程序准备好接受请求并公开指标，则返回200状态码。我们建议将此用于就绪探针。

请注意，不建议在代理公开数据时将遥测指标端点用于任何探针。

受限权限环境

如果您想在没有cluster-reader角色的环境中运行kube-state-metrics，您可以：

创建一个服务账户

apiVersion: v1
kind: ServiceAccount
metadata:
  name: kube-state-metrics
  namespace: 部署kube-state-metrics的命名空间

为其在特定命名空间上赋予view权限（使用roleBinding）（注意：您可以将此roleBinding添加到所有您希望服务账户访问的命名空间）

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: kube-state-metrics
  namespace: project1
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: view
subjects:
  - kind: ServiceAccount
    name: kube-state-metrics
    namespace: 部署kube-state-metrics的命名空间

然后在kube-state-metrics部署配置中指定一组命名空间（使用--namespaces选项）和一组您的服务账户有权访问的Kubernetes对象（使用--resources）

spec:
  template:
    spec:
      containers:
      - name: kube-state-metrics
        args:
          - '--resources=pods'
          - '--namespaces=project1'

有关可用参数的完整列表，请参阅docs/developer/cli-arguments.md中的文档

Helm Chart

从kube-state-metrics图表v2.13.3（kube-state-metrics镜像v1.9.8）开始，官方Helm图表在prometheus-community/helm-charts中维护。从kube-state-metrics图表v3.0.0开始，仅支持v2.0.0+版本的kube-state-metrics镜像。