kube 状态指标
v2.14.0
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 修改的原始数据，这样用户就可以获得他们需要的所有数据，并根据他们认为合适的方式执行启发式操作。
指标在侦听端口（默认 8080）上的 HTTP 端点/metrics上导出。它们以明文形式提供。它们被设计为由 Prometheus 本身或与抓取 Prometheus 客户端端点兼容的抓取工具使用。您还可以在浏览器中打开/metrics以查看原始指标。请注意， /metrics端点上公开的指标反映了 Kubernetes 集群的当前状态。当 Kubernetes 对象被删除时，它们在/metrics端点上不再可见。
笔记
本自述文件是根据模板生成的。请在那里进行更改并运行make generate-template 。
版本控制
库伯内特版本
兼容性矩阵
资源组版本兼容性
容器镜像
指标文档
标签名称冲突解决
Kube-state-metrics 自我指标
资源推荐
延迟
关于成本核算的说明
kube-state-metrics 与 Metrics-server
扩展 kube-state-metrics
自动分片
资源推荐
水平分片
Pod 指标的 Daemonset 分片
设置
构建 Docker 容器
用法
Kubernetes 部署
有限权限环境
舵图
发展
开发者贡献
社区
kube-state-metrics 使用client-go与 Kubernetes 集群进行通信。支持的 Kubernetes 集群版本由client-go决定。可以在此处找到 client-go 和 Kubernetes 集群的兼容性矩阵。所有附加兼容性只是尽力而为，或者碰巧仍然/已经受到支持。
下面最多会记录 5 个 kube-state-metrics 和 5 个 kubernetes 版本。一般来说，建议使用最新版本的 kube-state-metrics。如果您运行最新版本的 Kubernetes，您可能希望使用未发布的版本来获得全部受支持的资源。如果您运行旧版本的 Kubernetes，则可能需要运行旧版本才能完全支持所有资源。请注意，维护者只会支持最新版本。社区感兴趣的用户可能会支持旧版本。
| kube 状态指标 | Kubernetes client-go 版本 |
|---|---|
| v2.10.1 | v1.27 |
| v2.11.0 | v1.28 |
| v2.12.0 | v1.29 |
| v2.13.0 | v1.30 |
| v2.14.0 | v1.31 |
| 主要的 | v1.31 |
Kubernetes 中的资源可以进化，即资源的组版本可能会从 alpha 变为 beta，最后在不同的 Kubernetes 版本中变为 GA。目前，kube-state-metrics 将仅使用最新版本中可用的最旧的 API。
最新的容器镜像可以在以下位置找到：
registry.k8s.io/kube-state-metrics/kube-state-metrics:v2.14.0 （架构： amd64 、 arm 、 arm64 、 ppc64le和s390x ）
在此处查看所有多架构图像
任何基于 alpha Kubernetes 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 。
如果您希望更好地控制如何解决此冲突，您可能需要考虑在堆栈的不同级别上解决此问题，例如，通过使用Admission Webhook 标准化 Kubernetes 标签，以确保不存在可能的冲突。
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"} 1kube-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"} 30kube-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"} 1kube-state-metrics 的资源使用情况随着集群的 Kubernetes 对象（Pods/Nodes/Deployments/Secrets 等）大小而变化。从某种程度上来说，集群中的 Kubernetes 对象与集群的节点数成正比。
作为一般规则，您应该分配：
250MiB内存
0.1核
请注意，如果 CPU 限制设置得太低，kube-state-metrics 的内部队列将无法足够快地完成工作，从而导致随着队列长度的增长而增加内存消耗。如果您遇到因高内存分配或 CPU 限制而导致的问题，请尝试增加 CPU 限制。
在 100 个节点的集群扩展测试中，延迟数字如下：
"Perc50": 259615384 ns, "Perc90": 475000000 ns, "Perc99": 906666666 ns.
默认情况下，kube-state-metrics 公开集群中事件的多个指标。如果集群上有大量频繁更新的资源，您可能会发现大量数据被提取到这些指标中。这可能会给某些云提供商带来高昂的成本。请花一些时间配置您想要公开的指标，并查阅您的 Kubernetes 环境的文档，以避免意外的高成本。
metrics-server 是一个受到 Heapster 启发的项目，其实现是为了服务 Kubernetes 监控架构中核心指标管道的目标。它是一个集群级别的组件，通过 Metrics API 定期从 Kubelet 服务的所有 Kubernetes 节点中抓取指标。这些指标被聚合、存储在内存中并以 Metrics API 格式提供。指标服务器仅存储最新值，不负责将指标转发到第三方目的地。
kube-state-metrics 专注于从 Kubernetes 的对象状态生成全新的指标（例如基于部署、副本集等的指标）。它在内存中保存 Kubernetes 状态的完整快照，并根据它不断生成新的指标。就像指标服务器一样，它也不负责将其指标导出到任何地方。
将 kube-state-metrics 作为单独的项目还可以从 Prometheus 等监控系统访问这些指标。
为了水平分片 kube-state-metrics，已经实现了一些自动分片功能。它配置有以下标志：
--shard （零索引）
--total-shards
分片是通过获取 Kubernetes 对象 UID 的 md5 和并对其与分片总数执行模运算来完成的。每个分片决定该对象是否由相应的 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 中时发现其名义位置，这对于自动配置分片非常有用。这是一项实验性功能，可能会被破坏或删除，恕不另行通知。
要启用自动分片，kube-state-metrics 必须由StatefulSet运行，并且 pod 名称和命名空间必须通过--pod和--pod-namespace标志传递给 kube-state-metrics 进程。演示自动分片功能的示例清单可以在/examples/autosharding中找到。
当您想要通过单个 Kubernetes 资源（在本例中为单个StatefulSet ）而不是每个分片一个Deployment来管理 KSM 分片时，这种部署分片的方式非常有用。当部署大量分片时，这一优势尤其显着。
使用自动分片设置的缺点来自StatefulSet支持的部署策略。当由StatefulSet管理时，Pod 会一次替换一个，每个 Pod 首先被终止，然后重新创建。除了此类推出速度较慢之外，它们还会导致每个分片的停机时间较短。如果在部署期间发生 Prometheus 抓取，它可能会丢失 kube-state-metrics 导出的一些指标。
对于 Pod 指标，可以使用以下标志对每个节点进行分片：
--node=$(NODE_NAME)
每个 kube-state-metrics pod 使用 FieldSelector (spec.nodeName) 仅在同一节点上监视/列出 pod 指标。
守护进程集 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 映像：
make container
只需在 Kubernetes pod 内构建并运行 kube-state-metrics，该 pod 具有对 Kubernetes 集群具有只读访问权限的服务帐户令牌。
( kube-prometheus ) 堆栈安装 kube-state-metrics 作为其组件之一；如果您使用 kube-prometheus 堆栈，则不需要安装 kube-state-metrics。
如果您想修改 kube-prometheus 的默认配置，例如启用非默认指标，请查看自定义 Kube-Prometheus。
要部署此项目，您只需运行kubectl apply -f examples/standard即可创建 Kubernetes 服务和部署。 （注意：如果您的 kubernetes 集群版本不是 1.8+，请调整某些资源的 apiVersion，查看 yaml 文件以获取更多信息）。
要让 Prometheus 发现 kube-state-metrics 实例，建议为 kube-state-metrics 创建一个特定的 Prometheus scrape 配置，以获取两个指标端点。不鼓励基于注释的发现，因为只能选择一个端点，而且在大多数情况下 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 禁止响应，请检查与您的账户关联的 IAM 成员：https://console.cloud.google.com/iam-admin/iam?project=PROJECT_ID 。如果它包含大写字母，您可能需要将上述命令中的 --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，您可以：
创建一个服务帐户
api版本：v1kind：ServiceAccount元数据：名称：kube-state-metrics 命名空间：your-namespace-where-kube-state-metrics-will-deployed
赋予它对特定名称空间的view权限（使用角色绑定）（注意：您可以将此角色绑定添加到您希望服务帐户访问的所有 NS ）
api版本：rbac.authorization.k8s.io/v1kind：RoleBinding元数据：名称：kube-state-metrics 命名空间：project1roleRef：apiGroup：rbac.authorization.k8s.io 种类：集群角色 名称： 查看主题： - kind: ServiceAccountname: kube-state-metricsnamespace: your-namespace-where-kube-state-metrics-will-deployed
然后指定您的 serviceaccount 在kube-state-metrics部署配置中有权访问的一组命名空间（使用--namespaces选项）和一组 kubernetes 对象（使用--resources ）
规格：模板：规格：容器：
- 名称：kube-state-metricsargs：
- '--resources=pods' - '--namespaces=project1'有关可用参数的完整列表，请参阅 docs/developer/cli-arguments.md 中的文档
从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 映像。
开发时，通过运行以下命令针对本地 Kubernetes 集群测试指标转储：
用户可以使用
--apiserver命令行覆盖 KUBE-CONFIG 文件中的 apiserver 地址。
go install kube-state-metrics --port=8080 --telemetry-port=8081 --kubeconfig=--apiserver=
然后curl指标端点
curl localhost:8080/metrics
要在本地运行 e2e 测试，请参阅tests/README.md 中的文档。
开发时，需要遵循某些代码模式，以改善您的贡献体验以及通过 e2e 和其他 ci 测试的可能性。要了解有关它们的更多信息，请参阅 docs/developer/guide.md 中的文档。
该项目由 SIG Instrumentation 赞助。
Kubernetes 的 Slack 上还有一个 #kube-state-metrics 频道。
您还可以加入 SIG Instrumentation 邮件列表。这通常会将以下会议的邀请添加到您的日历中，其中可以讨论有关 kube-state-metrics 的主题。
SIG 定期会议：太平洋时间周四 9:30（每两周一次）。转换为您的时区。
定期分类会议：太平洋时间周四 9:30（每两周一次 - 与定期会议交替）。转换为您的时区。
