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（每兩週一次 - 與定期會議交替）。轉換為您的時區。
