kube-state-metrics v2.0.0 の変更点調査

はじめに

このページでは kube-state-metrics v2.0.0 に関連する変更内容をまとめています。
(2020/12/4 執筆時点では、v2.0.0-beta が最新となっております。)

• https://github.com/kubernetes/kube-state-metrics/releases

kube-state-metrics とは

以下が公式の Overview から一部抜粋してきた説明文になります。

kube-state-metrics is a simple service that listens to the Kubernetes API server and generates metrics about the state of the objects.

上記の説明に書いてある通り、 Kubernetes の API server を定期的に確認して Kubernetes のオブジェクトの状態をメトリクスとして提供してくれます。

kube-state-metrics の利用用途

kube-state-metrics から取得できるメトリクスは、主に以下の3つの用途で利用されることが多いです。

• ダッシュボード
• アラート
• Horizontal Pod Autoscaler 等の kubernetes のその他の機能の入力データ

ダッシュボード

Prometheus や Grafana 等のプロダクトと組み合わせて、Kubernetes の状態を可視化するためのダッシュボードに使用します。以下の画像は、Grafana Labs の公式サイトで共有されているダッシュボード の一例になります。

その他にも、Grafana の公式サイトの方が色々な方がダッシュボードを作成して共有してくれていますが、多くのものの中で kube-state-metrics が活用されています。

アラート

Prometheus や Alertmanager 等のプロダクトと組み合わせて、Kubernetes の状態を監視するためのアラートに使用します。以下は kube-state-metrics の公式サイトにあるアラートルールの example になります

groups:
- name: kube-state-metrics
  rules:
  - alert: KubeStateMetricsListErrors
    annotations:
      description: kube-state-metrics is experiencing errors at an elevated rate in
        list operations. This is likely causing it to not be able to expose metrics
        about Kubernetes objects correctly or at all.
      summary: kube-state-metrics is experiencing errors in list operations.
    expr: |
      (sum(rate(kube_state_metrics_list_total{job="kube-state-metrics",result="error"}[5m]))
        /
      sum(rate(kube_state_metrics_list_total{job="kube-state-metrics"}[5m])))
      > 0.01
    for: 15m
    labels:
      severity: critical
  - alert: KubeStateMetricsWatchErrors
    annotations:
      description: kube-state-metrics is experiencing errors at an elevated rate in
        watch operations. This is likely causing it to not be able to expose metrics
        about Kubernetes objects correctly or at all.
      summary: kube-state-metrics is experiencing errors in watch operations.
    expr: |
      (sum(rate(kube_state_metrics_watch_total{job="kube-state-metrics",result="error"}[5m]))
        /
      sum(rate(kube_state_metrics_watch_total{job="kube-state-metrics"}[5m])))
      > 0.01
    for: 15m
    labels:
      severity: critical

Horizontal Pod Autoscaler 等の kubernetes のその他の機能入力データ

Horizontal Pod Autoscaler や Custom Scheduler の入力データとしてメトリクスを使用するケースがありますが、その際の入力データの一つとして kube-state-metrics を活用するケースがあります。ダッシュボードやアラートに比べて利用してるケースはまだ少ないと思いますが、利用している場合は、kube-state-metrics のアップグレードする際に利用しているメトリクス名に対する変更がないか等の確認が必要になります。

kube-state-metrics が v2.0.0 にアップデートされる背景

deprecated なメトリクスや、あまり良くない名前や挙動をするメトリクスも増えてきたので、ここで一度時間をかけて kube-state-metrics 整理しようという話になり v2.0.0 にすることになりました。細かい背景を知りたい方は、こちらの issue (kube-state-metrics Breaking Release aka 2.0) をご確認ください。

また、参考に kube-state-metrics が v1.0.0 になった際の issue (1.0 stabilization) はこちらになりますので、興味のある方は合わせてご確認ください。

kube-state-metrics のリリースについて

kube-state-metrics は、release candidate (e.g. v1.2.0-rc.0) が出てから、７日間の間に新たな bug の報告等がなければ、 stable release (e.g. v1.2.0) するというリリースのルールになっています。通常は3ヶ月に一回程度の頻度で新しいバージョンが出ます。さらに詳しく知りたい方はこちらをご確認ください。

kube-state-metrics v2.0.0系の直近のリリースについて

通常のリリースでは、rc 版が出るだけになりますが、今回は破壊的な変更を多く含むメジャーバージョンの更新になるため、alpha版のリリースが行われ丁寧に確認しながら、リリースが行われています。

kube-state-metrics	Release
v2.0.0-beta	2020-12-04
v2.0.0-alpha.3	2020-11-19
v2.0.0-alpha.2	2020-10-27
v2.0.0-alpha.1	2020-10-06
v2.0.0-alpha	2020-09-16

各マイナーバージョンの最新のリリース

概ね3ヶ月毎にマイナーバージョンが更新されるいることがわかります。v1.9.0系だけは、v2.0.0系のリリース対応のために次のリリースが止まっているのでパッチバージョンが続いているかたちになります。

kube-state-metrics	Release
v2.0.0-beta	2020-12-04
v1.9.7	2020-05-24
v1.8.0	2019-10-01
v1.7.2	2019-08-05
v1.6.0	2019-05-06
v1.5.0	2019-01-10
v1.4.0	2018-08-22
v1.3.1	2018-04-12
v1.2.0	2018-01-15
v1.1.0	2017-10-19
v1.0.1	2017-08-24
v0.5.0	2017-05-03
v0.4.1	2017-02-11
v0.3.0	2016-10-18
v0.2.0	2016-09-15
v0.1.0	2016-03-10

v1.7.0系もパッチバージョンが複数回出てますが、これは v1.7.2 で security issue に対応したためになります。

参考：https://github.com/kubernetes/kube-state-metrics/releases

kube-state-metrics と kubernetes の対応関係

以下の表は、公式のGitHub の情報になります。対応関係については kube-state-metrics で使用している [client-go] (https://github.com/kubernetes/kube-state-metrics#kubernetes-version) に依存しています。以下のような対応関係はありますが、 kube-state-metrics のアップデートに伴うメトリクス名の変更等の影響もあるので、必ず自分の使用している環境でダッシュボードやアラートに影響がないか確認するようにして下さい。特にアラートに関する変更確認漏れがある場合には、サービスに何か障害があった場合に気づけなくなる可能性が出てきますので特に注意が必要です。

(こちらの情報については、利用する際に最新の情報をご確認ください)

| kube-state-metrics | Kubernetes 1.15 | Kubernetes 1.16 | Kubernetes 1.17 | Kubernetes 1.18 | Kubernetes 1.19 |
|--------------------|---------------------|---------------------|----------------------|----------------------|----------------------|
| v1.8.0 | ✓ | - | - | - | - |
| v1.9.7 | - | ✓ | - | - | - |
| v2.0.0-beta | - | - | -/✓ | -/✓ | ✓ |
| master | - | - | -/✓ | -/✓ | ✓ |

• ✓ Fully supported version range.
• - The Kubernetes cluster has features the client-go library can't use (additional API objects, deprecated APIs, etc).

参考： https://github.com/kubernetes/kube-state-metrics#kubernetes-version

kube-state-metrics の v2.0.0 での変更点

変更点の簡単なサマリー

• CLI falg に --labels-metric-allow-list が追加されたことによる kube_<オブジェクト名>_labels 形式のメトリクスの出力が制限されるようになります。
  kube-state-metrics は kubernetes のオブジェクトについている label の情報をメトリクスの label として出力する機能がありましたが、今までは全ての label をメトリクスに出力する仕様でしたが、データ量が多く制限したいというニーズが高まってきたため、allow-list で指定したものだけをメトリクスとして出力するように変更が加えられました。

  • --labels-metric-allow-list　の指定する際のイメージ
    kubernetes の各オブジェクト単位に出力したい label を指定していく

    --labels-metric-allow-list=namespaces=[k8s-label-1,k8s-label-n,...],pods=[app],...
    

　　　　
- 出力されるメトリクスのイメージ
以下のような kube_<オブジェクト名>_labels のメトリクスに指定した label の情報が出力される。何も指定しない場合は、 namespace と オブジェクト名だけが以下のように出力される

    ```diff
    # HELP kube_deployment_labels Kubernetes labels converted to Prometheus labels.
    # TYPE kube_deployment_labels gauge
    + kube_deployment_labels{namespace="kube-system",deployment="coredns"} 1
    + kube_deployment_labels{namespace="local-path-storage",deployment="local-path-provisioner"} 1
    + kube_deployment_labels{namespace="kube-system",deployment="kube-state-metrics"} 1
    ```

• CLI falg 名の変更
  以下のように、CLI falg 名が変更になります。機能的な変更はありませんが、既に使用している場合はアップグレード時に必要に応じて変更して下さい。

  • --namespace -> --namespaces
  • --collectors -> --resources
  • --metric-whitelist -> --metric-allowlist
  • --metric-blacklist -> --metric-denylist

• deprecatedd なメトリクスの削除
  以前より、以下のようにアナウンスされていたメトリクスが削除されています。

  • The following non-generic resource metrics for pods are marked deprecated. They will be removed in kube-state-metrics v2.0.0.
    kube_pod_container_resource_requests and kube_pod_container_resource_limits are the replacements with resource labels
    representing the resource name and unit labels representing the resource unit.
    > - kube_pod_container_resource_requests_cpu_cores
    > - kube_pod_container_resource_limits_cpu_cores
    > - kube_pod_container_resource_requests_memory_bytes
    > - kube_pod_container_resource_limits_memory_bytes
  • The following non-generic resource metrics for nodes are marked deprecated. They will be removed in kube-state-metrics v2.0.0.
    kube_node_status_capacity and kube_node_status_allocatable are the replacements with resource labels
    representing the resource name and unit labels representing the resource unit.
    > - kube_node_status_capacity_pods
    > - kube_node_status_capacity_cpu_cores
    > - kube_node_status_capacity_memory_bytes
    > - kube_node_status_allocatable_pods
    > - kube_node_status_allocatable_cpu_cores
    > - kube_node_status_allocatable_memory_bytes

• メトリクス名の変更
  camelCase になっていたメトリクス名が、 snake_case に統一されたり、省略形になっていたものがフルネームを使用したりと、多数のメトリクス名の変更が行われています。アップグレード時には必ず、自身の環境のダッシュボードやアラートに等に影響がないことを確認するようにして下さい。変更の量が多いので、簡単なまとめをこちらに作りましたのでご活用ください。

  • camelCase から snake_case に修正された例

    # camelCase  
    - reclaimPolicy 
    - volumeBindingMode
    
    # snake_case
    + reclaim_policy
    + volume_binding_mode
    

  • 省略形がフルネームに修正された例

    - kube_hpa_*
    + kube_horizontalpodautoscaler_*
    

メトリクス名については多数の変更が行われたので、自身の利用しているメトリクスについて変更があったかどうかを必ず確認するようにして下さい。

• 新規メトリクスや既存のメトリクスに対する 新規 label の追加
  多数のメトリクスが追加されているので一例だけここで紹介します。

  • DaemonSets のメトリクスに kube_daemonset_status_observed_generation が追加されました。

    # HELP kube_daemonset_status_observed_generation The most recent generation observed by the daemon set controller.
    # TYPE kube_daemonset_status_observed_generation gauge
    + kube_daemonset_status_observed_generation{daemonset="ds1",namespace="ns1"} 2
    

  • このメトリクスが存在する以前は DaemonSet の rollout 完了確認を以下のような方法で行う必要がありましたが、このメトリクスの追加により改善されました

    observedGeneration == generation &&
    currentNumberScheduled == desiredNumberScheduled &&
    numberMisscheduled == 0 && 
    updatedNumberScheduled == desiredNumberScheduled &&
    numberAvailable == desiredNumberScheduled
    

アップグレード時の注意点

• 気をつけるべき kube-state-metrics の確認観点

1. メトリクス名の変更の確認
   メトリクス名の変更については後方互換性のない変更になるため、必ず確認するようにして下さい。各メトリクスの詳細な情報については、公式の Github のこちらをご確認下さい。

2. CLI flags の変更の確認
   起動時の引数になります。こちらも後方互換性のない変更になるため、使用しているものがある場合は確認して変更して下さい。詳細についてはこちらをご確認下さい。

3. 起動ログの確認
   アップデート後の起動時のログについては必ず確認するようにして下さい。

   • 以下は起動時のエラーログの例になります
     kube-state-metrics はメトリクスを取得するオブジェクトに応じて、対象に対する権限の付与が必要になります

     ```
     E1125 06:22:30.554709       1 reflector.go:127] k8s.io/kube-state-metrics/internal/store/builder.go:358: Failed to watch *v1.Ingress: failed to list *v1.Ingress: ingresses.networking.k8s.io is forbidden: User "system:serviceaccount:kube-system:kube-state-metrics" cannot list resource "ingresses" in API group "networking.k8s.io" at the cluster scope: No policy matched.
     E1125 06:22:30.563241       1 reflector.go:127] k8s.io/kube-state-metrics/internal/store/builder.go:358: Failed to watch *v1.Lease: failed to list *v1.Lease: leases.coordination.k8s.io is forbidden: User "system:serviceaccount:kube-system:kube-state-metrics" cannot list resource "leases" in API group "coordination.k8s.io" in the namespace "kube-node-lease": No policy matched.
     ```
     

   • エラーメッセージに対応した ClusterRole を付与します。
     今回はあくまで例なので、表示されたエラーメッセージに合わせて対処して下さい

     ```yaml
     - apiGroups:
       - networking.k8s.io
       resources:
       - ingresses
       verbs:
       - list
       - watch
     - apiGroups:
       - coordination.k8s.io
       resources:
       - leases
       verbs:
       - list
       - watch
     ```
     

   • 再度、起動ログを確認します。
     以下のようにエラーが出ないことを確認して下さい

     ```
     I1204 06:41:44.489517       1 main.go:239] Running with Kubernetes cluster version: v1.19. git version: v1.19.4. git tree state: clean. commit: d360454c9bcd1634cf4cc52d1867af5491dc9c5f. platform: linux/amd64
     I1204 06:41:44.489868       1 main.go:241] Communication with server successful
     I1204 06:41:44.490925       1 main.go:197] Starting metrics server: 0.0.0.0:8080
     I1204 06:41:44.490986       1 metrics_handler.go:96] Autosharding disabled
     I1204 06:41:44.491011       1 main.go:186] Starting kube-state-metrics self metrics server: 0.0.0.0:8081
     I1204 06:41:44.491975       1 builder.go:164] Active resources: certificatesigningrequests,configmaps,cronjobs,daemonsets,deployments,endpoints,horizontalpodautoscalers,ingresses,jobs,leases,limitranges,mutatingwebhookconfigurations,namespaces,networkpolicies,nodes,persistentvolumeclaims,persistentvolumes,poddisruptionbudgets,pods,replicasets,replicationcontrollers,resourcequotas,secrets,services,statefulsets,storageclasses,validatingwebhookconfigurations,volumeattachments
     ```
     

※ kube-state-metrics で取得するメトリクスに応じて、対応する権限を付与する必要がありますが、こちらを参考に必要に応じて権限を付与して下さい

• kube-state-metrics の変更による影響調査観点
  上述の kube-state-metrics の利用用途の繰り返しになりますが、以下の3つの観点については必ず影響がないか確認するようにして下さい。

  • ダッシュボード
  • アラート
  • Horizontal Pod Autoscaler 等の kubernetes のその他の機能入力データ

変更点の詳細

以下が kube-state-metrics v2.0.0 の各変更点の内容になります。
(2020/12/4 執筆時点)

• https://github.com/kubernetes/kube-state-metrics/releases

がついた文章は、CHANGELOGの公式内容ではなく筆者の補足です。

v2.0.0-alpha / 2020-09-16

Changes（変更）

• --labels-allow-list を使用することで、ユーザが指定した label の情報だけがメトリクスとして出力されるようになります#1125

  • kubernetes のオブジェクトに付与されている label をメトリクスとして出力する *_labels が現状で高い cardinality であるため、それを抑制するために Allow list で指定するよう変更になりました。
  • *_labels のメトリクスが自動で出力されなくなったため、現在 *_labels のメトリクスを利用中の場合はアップグレードする際に 起動時の --labels-allow-list の flag を設定する必要があります。設定方法の例は以下になります。

    --labels-allow-list kube_deployment_labels=[label_app,label_env],kube_pod_labels=[label_app,label_env]
    

• DaemonSet の kube_daemonset_updated_number_scheduled のメトリクス名が kube_daemonset_status_updated_number_scheduled に変更されました #1181

  • kube-state-metrics では status に関するメトリクスについては、kube_<オブジェクト名>_status_* の形式となっていますが、今回対象とのなったメトリクスがそのルールに則っていなかったための修正になります。

• 以下のメトリクスが追加されました #1168
  Metrics

  • kube_pod_container_resource_requests

  • kube_pod_container_resource_limits

  • kube_pod_overhead

  • kube_pod_init_container_resource_limits

  • kube_pod_init_container_resource_requests

    v2.0.0-alpha.2 の #1278 の中で、以下のメトリクスに関しては revert されていますが内容については後述します

  • kube_pod_container_resource_requests

  • kube_pod_container_resource_limits

  kube_pod_overhead については k8s の公式サイトのこちら をご確認ください。公式サイト上で以下のように記載されていますが、 該当の機能がこの変更で追加されました

  A kube_pod_overhead metric is available in kube-state-metrics to help identify when PodOverhead is being utilized and to help observe stability of workloads running with a defined Overhead. This functionality is not available in the 1.9 release of kube-state-metrics, but is expected in a following release. Users will need to build kube-state-metrics from source in the meantime.

• k8s のオブジェクトの labels をメトリクスに出力する際に snake_case に変換するようにします #1165

  • k8s のオブジェクトの labels をメトリクスとして出力する際に、 camelCase で記述されていた場合にそのまま出力されていましたが snake_case に変換するように変更されました。変換のイメージは以下になります。

    # camelCase
    - metadata_DevicePath 
    
    # snake_case
    + metadata_device_path 
    

• mutatingWebhookConfiguration が v1beta1 から v1 に変更されました #1144

• storage class の labels が snake_case に変更されました #1107

  • 変更後の labels のイメージは以下になります

    # camelCase
    - reclaimPolicy 
    - volumeBindingMode
    
    # snake_case
    + reclaim_policy
    + volume_binding_mode
    

• CLI の flag 名が --namespace から --namespaces に変更されました #1098

• メトリクス名が kube_pod_deleted から kube_pod_deletion_timestamp に変更されました #1079

• CLI の flag 名が --collectors から --resources に変更されました #1006

• [CHANGE] Pod のメトリクスから non-identifying な labels の削除されました #1009

  • 以下のメトリクスから node の label が削除されました
    • kube_pod_container_resource_requests
    • kube_pod_container_resource_limits
    • kube_pod_init_container_resource_limits

• deprecated なメトリクスが削除されました #1004
  詳細については #1168 を参照ください　　

  • 以下のメトリクスが削除されます

    ```diff
    - kube_pod_container_resource_requests_cpu_cores
    - kube_pod_container_resource_requests_memory_bytes
    - kube_pod_container_resource_limits_cpu_cores
    - kube_pod_container_resource_limits_memory_bytes
    - kube_node_status_capacity_pods
    - kube_node_status_capacity_cpu_cores
    - kube_node_status_capacity_memory_bytes
    - kube_node_status_allocatable_pods
    - kube_node_status_allocatable_cpu_cores
    - kube_node_status_allocatable_memory_bytes
    ```
    

  • 今後、同じメトリクスを使用する場合は以下のメトリクスに対して resource labels を指定して使用してください。

    ```diff
    + kube_pod_container_resource_requests
    + kube_pod_container_resource_limits
    + kube_node_status_capacity
    + kube_node_status_allocatable 
    ```
    

  • 代替して使用する際のイメージは以下になります。

    ```diff
    ### requests
    - kube_pod_container_resource_requests_cpu_cores 
    + kube_pod_container_resource_requests{resource="cpu"}
    - kube_pod_container_resource_requests_memory_bytes
    + kube_pod_container_resource_requests{resource="memory"}
    
    ### limits
    - kube_pod_container_resource_limits_cpu_cores 
    + kube_pod_container_resource_limits{resource="cpu"}
    - kube_pod_container_resource_limits_memory_bytes
    + kube_pod_container_resource_limits{resource="memory"}
    
    ### capacity
    - kube_node_status_capacity_pods 
    + kube_node_status_capacity{resource="pods"}
    - kube_node_status_capacity_cpu_cores
    + kube_node_status_capacity{resource="cpu"}
    - kube_node_status_capacity_memory_bytes 
    + kube_node_status_capacity{resource="memory"}
    
    ### allocatable
    - kube_node_status_allocatable_pods
    + kube_node_status_allocatable{resource="pods"}
    - kube_node_status_allocatable_cpu_cores 
    + kube_node_status_allocatable{resource="cpu"}
    - kube_node_status_allocatable_memory_bytes
    + kube_node_status_allocatable{resource="memory"}
    ```
    

• black-/whitelist が allow/deny-list に名前が変更されました #1045
  New flags are --metric-allowlist and --metric-denylist

  • CLI flag の変更内容は以下になります
    • --metric-whitelist -> --metric-allowlist
    • --metric-blacklist -> --metric-denylist

• metrics port が 8080 に, telemetry port が 8081 に変更されました #1005 #1049

  • CLI flag の default の port が変更されました
    • metrics port: 80 -> 8080
    • telemetry port: 81 -> 8081

• horizontalpodautoscaler のメトリクスの prefix が変更されました #1003

  • horizontalpodautoscaler に関するメトリクスは以下のようになります

    - kube_hpa_*
    + kube_horizontalpodautoscaler_*
    

FEATURE（機能追加）

• kube-state-metrics に http_request_duration_seconds のメトリクスが追加されました #1218

  • メトリクスのイメージは以下になります

    # TYPE http_request_duration_seconds histogram
    + http_request_duration_seconds_bucket{handler="metrics",method="get",le="0.005"} 30
    + http_request_duration_seconds_bucket{handler="metrics",method="get",le="0.01"} 30
    + http_request_duration_seconds_bucket{handler="metrics",method="get",le="0.025"} 30
    + http_request_duration_seconds_bucket{handler="metrics",method="get",le="0.05"} 30
    + http_request_duration_seconds_bucket{handler="metrics",method="get",le="0.1"} 30
    + http_request_duration_seconds_bucket{handler="metrics",method="get",le="0.25"} 30
    + http_request_duration_seconds_bucket{handler="metrics",method="get",le="0.5"} 30
    + http_request_duration_seconds_bucket{handler="metrics",method="get",le="1"} 30
    + 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
    

• persistentvolume_info のメトリクスに　fc/iscsi/nfs の識別用の labels が追加されました #1208

  • labels で追加される情報は以下になります

    + fc_wwids
    + fc_lun
    + fc_target_wwns
    + iscsi_target_portal
    + iscsi_iqn
    + iscsi_lun
    + nfs_server
    + nfs_path
    

• pod のメトリクスに kube_pod_container_state_started が追加されました #1183

  • メトリクスのイメージは以下になります

    # HELP kube_pod_container_state_started Start time in unix timestamp for a pod container.
    # TYPE kube_pod_container_state_started gauge
    + kube_pod_container_state_started{container="container7",namespace="ns6",pod="pod6"} 1.501777018e+09
    

• DaemonSets のメトリクスに kube_daemonset_status_observed_generation が追加されました #1178

  • メトリクスのイメージは以下になります

    # HELP kube_daemonset_status_observed_generation The most recent generation observed by the daemon set controller.
    # TYPE kube_daemonset_status_observed_generation gauge
    + kube_daemonset_status_observed_generation{daemonset="ds1",namespace="ns1"} 2
    

  • このメトリクスが存在する以前は DaemonSet の rollout 完了確認を以下のように行う必要がありましたが、このメトリクスの追加により改善されました

    observedGeneration == generation &&
    currentNumberScheduled == desiredNumberScheduled &&
    numberMisscheduled == 0 && 
    updatedNumberScheduled == desiredNumberScheduled &&
    numberAvailable == desiredNumberScheduled
    

• node_info のメトリクスに internal_ip の情報が追加されました#1172

  • メトリクスのイメージは以下になります

    # HELP kube_node_info Information about a cluster node.
    # TYPE kube_node_info gauge
    - kube_node_info{container_runtime_version="rkt",kernel_version="kernel",kubelet_version="kubelet",kubeproxy_version="kubeproxy",node="127.0.0.1",os_image="osimage",pod_cidr="172.24.10.0/24",provider_id="provider://i-randomidentifier"} 1
    + kube_node_info{container_runtime_version="rkt",kernel_version="kernel",kubelet_version="kubelet",kubeproxy_version="kubeproxy",node="127.0.0.1",os_image="osimage",pod_cidr="172.24.10.0/24",provider_id="provider://i-randomidentifier",internal_ip="1.2.3.4"} 1
    

• [FEATURE] Kubernetes 上の labels をメトリクスを出力 した際に、Prometheus の labels として取り込まれるときに衝突するのを避けるように変更されました #1156

  • k8s 上の labels は Prometheus 上での labels と比べて制約が少ないので、 サポートされていない - 等の文字列を _ に変換するようになっています。したがって以下のようなケースでは labels 名が衝突することになります

    • foo-bar -> label_foo_bar
    • foo_bar -> label_foo_bar

  • そのため、labels 名の衝突を検知した場合には Suffix *_conflict<N> が付与されます。変更後のイメージは以下になります

    ### 機能追加前の変換イメージ
    - foo-bar -> label_foo_bar
    - foo_bar -> label_foo_bar
    
    ### 機能追加後の変換イメージ
    + foo-bar -> label_foo_bar_conflict1
    + foo_bar -> label_foo_bar_conflict2
    

• kube_persistentvolume_info のメトリクスに aws/gce volume id が追加されました #1146

  • ebs_volume_id gce_persistent_disk_name の labels が追加される形で実現されています。メトリクスのイメージは以下になります

    ### GCE
    + kube_persistentvolume_info{ebs_volume_id="",gce_persistent_disk_name="name",persistentvolume="test-pv-available",storageclass=""} 1
    
    ### AWS
    + kube_persistentvolume_info{ebs_volume_id="aws://eu-west-1c/vol-012d34d567890123b",gce_persistent_disk_name="",persistentvolume="test-pv-available",storageclass=""} 1
    

• kube_pod_status_reason のメトリクスの reason の labels に UnexpectedAdmissionError が追加されました #1145

  • メトリクスのイメージは以下になります

    # TYPE kube_pod_status_reason gauge
    kube_pod_status_reason{namespace="default",pod="pod0",reason="Evicted"} 0
    kube_pod_status_reason{namespace="default",pod="pod0",reason="NodeLost"} 0
    + kube_pod_status_reason{namespace="default",pod="pod0",reason="UnexpectedAdmissionError"} 0
    

  • "UnexpectedAdmissionError" について確認したい方はこちらをご参照ください

  • こちらの変更は後述する#1013での変更の中で、まだ未定義のステータスがあったため、追加されました。

• init container の requests に関するメトリクスが追加されました #1123

  • メトリクスのイメージは以下になります

    # HELP kube_pod_init_container_resource_requests The number of requested resources by the init container.
    # TYPE kube_pod_init_container_resource_requests gauge
    + kube_pod_init_container_resource_requests{container="pod1_initcon1",namespace="ns1",pod="pod1",resource="cpu",unit="core"} 0.2
    + kube_pod_init_container_resource_requests{container="pod1_initcon1",namespace="ns1",pod="pod1",resource="ephemeral_storage",unit="byte"} 3e+08
    + kube_pod_init_container_resource_requests{container="pod1_initcon1",namespace="ns1",pod="pod1",resource="memory",unit="byte"} 1e+08
    + kube_pod_init_container_resource_requests{container="pod1_initcon1",namespace="ns1",pod="pod1",resource="nvidia_com_gpu",unit="integer"} 1
    + kube_pod_init_container_resource_requests{container="pod1_initcon1",namespace="ns1",pod="pod1",resource="storage",unit="byte"} 4e+08
    

  • kube_pod_container_resource_requests だけでは、 scheduler が init container 考慮したスケジュールができないことから、今回のメトリクスを追加されました

• kube_pod_info のメトリクスに host_network の情報が追加されました #1100

  • メトリクスのイメージは以下になります

    # TYPE kube_pod_info gauge
    - kube_pod_info{namespace="default",pod="pod0",host_ip="1.1.1.1",pod_ip="1.2.3.4",uid="abc-0",node="node1",created_by_kind="<none>",created_by_name="<none>",priority_class=""} 1
    + kube_pod_info{namespace="default",pod="pod0",host_ip="1.1.1.1",pod_ip="1.2.3.4",uid="abc-0",node="node1",created_by_kind="<none>",created_by_name="<none>",priority_class="",host_network="false"} 1
    

  • この変更により、 kube_pod_info{host_network="true"} で host_network を使用している Pod を簡単に特定できるようになります

• kube_replicationcontroller_owner のメトリクスが追加されました #1100

  • メトリクスのイメージは以下になります

    # HELP kube_replicationcontroller_owner Information about the ReplicationController's owner.
    # TYPE kube_replicationcontroller_owner gauge
    + kube_replicationcontroller_owner{namespace="ns1",owner_is_controller="true",owner_kind="DeploymentConfig",owner_name="dc-name",replicationcontroller="rc1"} 1
    

• kube_pod_overhead のメトリクスが追加されました #1053

  • メトリクスのイメージは以下になります

    # HELP kube_pod_overhead_cpu_cores The pod overhead in regards to cpu cores associated with running a pod.
    # TYPE kube_pod_overhead_cpu_cores gauge
    + kube_pod_overhead_cpu_cores{namespace="kube-system",pod="test-pod"} 0.25
    # HELP kube_pod_overhead_memory_bytes The pod overhead in regards to memory associated with running a pod.
    # TYPE kube_pod_overhead_memory_bytes gauge
    + kube_pod_overhead_memory_bytes{namespace="kube-system",pod="test-pod"} 1.2582912e+08
    

  • 正確にはこの変更の際には、kube_pod_overhead でしたが #1168 メトリクスが修正され *_cpu_cores と *_memory_bytes が追加されましたので、実際に使う際には上記のイメージ例を参考にしていただけたらと思います。

  • 再掲にはなりますが、Pod Overhead は Kubernetes v1.18 で beta になった機能になります。詳しく知りたい方は公式サイトのこちらをご参照ください

• kube_pod_status_phase のメトリクスに "Terminating" に関する状態が追加されました #1013

  • メトリクスのイメージは以下になります

    # TYPE kube_pod_status_reason gauge
    + kube_pod_status_reason{namespace="default",pod="pod0",reason="Evicted"} 0
    + kube_pod_status_reason{namespace="default",pod="pod0",reason="NodeLost"} 0
     kube_pod_status_reason{namespace="default",pod="pod0",reason="UnexpectedAdmissionError"} 0
    

  • 前述の #1145 で追加された "UnexpectedAdmissionError" と変更箇所は同じになります。

• lease collector が追加され、 lease に関するメトリクスが出力されるようになりました #1038

  • メトリクスのイメージは以下になります

    # HELP kube_lease_owner Information about the Lease's owner.
    # TYPE kube_lease_owner gauge
    + kube_lease_owner{lease="kind-control-plane",owner_kind="Node",owner_name="kind-control-plane"} 1
    + kube_lease_owner{lease="kind-worker",owner_kind="Node",owner_name="kind-worker"} 1
    
    # HELP kube_lease_renew_time Kube lease renew time.
    # TYPE kube_lease_renew_time gauge
    + kube_lease_renew_time{lease="kind-control-plane"} 1.606403924e+09
    + kube_lease_renew_time{lease="kind-worker"} 1.60640392e+09
    

  • 新しい collector が追加されたので、対応する権限を ClusterRole に追加する必要があります

    - apiGroups:
      - coordination.k8s.io
      resources:
      - leases
      verbs:
      - list
      - watch
    

  • lease に関して詳しく知りたい方は公式サイトのこちらを参照ください

ENHANCEMENT（機能改善）

• DeprecatedVersion が struct FamilyGenerator と func NewFamilyGenerator に追加されました #1160

  • この変更の結果、DEPRECATED なメトリクスについては #HELP の箇所に Deprecated since x.x が表示されるようになります。

  • 主な変更箇所は以下になります

    • struct FamilyGenerator

      type FamilyGenerator struct {
          Name              string
          Help              string
          Type              metric.Type
          DeprecatedVersion string
          GenerateFunc      func(obj interface{}) *metric.Family
      }
      

    • func NewFamilyGenerator

      // NewFamilyGenerator creates new FamilyGenerator instances.
      func NewFamilyGenerator(name string, help string, metricType metric.Type, deprecatedVersion string, generateFunc func(obj interface{}) *metric.Family) *FamilyGenerator {
          f := &FamilyGenerator{
              Name:              name,
              Type:              metricType,
              Help:              help,
              DeprecatedVersion: deprecatedVersion,
              GenerateFunc:      generateFunc,
          }
          if deprecatedVersion != "" {
              f.Help = fmt.Sprintf("(Deprecated since %s) %s", deprecatedVersion, help)
          }
          return f
      

      詳細について確認したい方は、こちら をご確認ください

  • これ以前は、メトリクスが DEPRECATED か確認するためには公式の docs を見るしかありませんでしたが、#HELP に表示されるようになるので便利になります。

  • 今回マージされた PR の中では、自分はこの変更が一番好きです。 v2.0.0 にする際に DEPRECATED なメトリクスが一新されたため実際に利用する機会はまだ先になりますが今後利用するのが楽しみですね。

• deployment と statefulset に security context が追加されました #1034

  • examples で提供されている manifest に security context が追加されました

    apiVersion: apps/v1
    kind: Deployment
        :
    +        securityContext:
    +          runAsUser: 65534
        :
    

BUGFIX(バグ修正)

• VolumeAttachment API version が v1 で watch するのが正しいところ、 v1betaとなっていたため修正されました #1136

  • 以下が修正箇所の一部抜粋になります

    package store
    
    import (
    -	storagev1beta1 "k8s.io/api/storage/v1beta1"
    +	storagev1 "k8s.io/api/storage/v1"
    

• kube_volumeattachment_info メトリクスの label の nodeName が node に変更になりました #1117

  • メトリクスのイメージは以下になります

    # HELP kube_volumeattachment_info Information about volumeattachment.
    # TYPE kube_volumeattachment_info gauge	        
    - kube_volumeattachment_info{attacher="cinder.csi.openstack.org",nodeName="node1",volumeattachment="csi-5ff16a1ad085261021e21c6cb3a6defb979a8794f25a4f90f6285664cff37224"} 1
    + kube_volumeattachment_info{attacher="cinder.csi.openstack.org",node="node1",volumeattachment="csi-5ff16a1ad085261021e21c6cb3a6defb979a8794f25a4f90f6285664cff37224"} 1
    

v2.0.0-alpha.1 / 2020-10-06

Changes（変更）

• go module の path が k8s.io/kube-state-metrics/v2 に変更されました #1238

  • 以下が変更内容の一部抜粋になります

    - module k8s.io/kube-state-metrics
    + module k8s.io/kube-state-metrics/v2
    

• klog が v2 に、 client-go が 1.19 に更新されました #1250

  • 以下が変更内容の一部抜粋になります

    -	k8s.io/client-go v0.18.6
    -	k8s.io/klog v1.0.0
    +	k8s.io/client-go v0.19.2
    +	k8s.io/klog/v2 v2.2.0
    

FEATURE（機能追加）

• persistentvolume_info のメトリクスに initiator の label が追加されました #1235

  • メトリクスのイメージは以下になります

    # HELP kube_persistentvolume_info Information about persistentvolume.
    # TYPE kube_persistentvolume_info gauge	        
    - kube_persistentvolume_info{ebs_volume_id="",fc_lun="",fc_target_wwns="",fc_wwids="",gce_persistent_disk_name="",iscsi_iqn="iqn.my.test.server.target00",iscsi_lun="123",iscsi_target_portal="1.2.3.4:3260",nfs_path="",nfs_server="",persistentvolume="test-pv-available",storageclass=""} 1
    + kube_persistentvolume_info{ebs_volume_id="",fc_lun="",fc_target_wwns="",fc_wwids="",gce_persistent_disk_name="",iscsi_initiator_name="",iscsi_iqn="iqn.my.test.server.target00",iscsi_lun="123",iscsi_target_portal="1.2.3.4:3260",nfs_path="",nfs_server="",persistentvolume="test-pv-available",storageclass=""} 1
    

BUGFIX(バグ修正)

• Jsonnet に Namespace が追加されました #1233

  • 以下が変更内容になります

          roleBinding.mixin.roleRef.withName(ksm.name) +
    +      roleBinding.mixin.roleRef.withNamespace(ksm.namespace) +
          roleBinding.mixin.roleRef.mixinInstance({ kind: 'Role' }) +
    

• family generator を参照するように変更されました
  #1240

  • 以下が変更内容の一部抜粋になります

    for _, m := range metricFamily.Metrics {
    -	m.LabelKeys, m.LabelValues = allowLabels.Allowed(f.Name, m.LabelKeys, m.LabelValues)
    +	m.LabelKeys, m.LabelValues = allowLabels.Allowed(familyGenerator.Name, m.LabelKeys, m.LabelValues)
    }
    

  • この変更は v2.0.0-alpha で kube_*_created のメトリクスで label が表示されなくなる bug に対する修正になります

v2.0.0-alpha.2 / 2020-10-27

Changes（変更）

• ingress と certificates APIs の version が stable なものに変更されました #1260

• #1168 での変更内容が一部 Revert されました #1278

  • 以下のメトリクスに関する変更が元に戻されました
    • kube_pod_container_resource_requests
    • kube_pod_container_resource_limits

FEATURE（機能追加）

• kube_job_status_failed のメトリクスに failure reason が追加されました #1214

  • メトリクスのイメージは以下になります

    - # HELP kube_job_status_failed The number of pods which reached Phase Failed.
    + # HELP kube_job_status_failed The number of pods which reached Phase Failed and the reason for failure.
    # TYPE kube_job_status_failed gauge
    - kube_job_status_failed{job_name="FailedJob1",namespace="ns1"} 1
    + kube_job_status_failed{job_name="FailedJob1",namespace="ns1",reason="BackoffLimitExceeded"} 1
    + kube_job_status_failed{job_name="FailedJob1",namespace="ns1",reason="DeadLineExceeded"} 0
    + kube_job_status_failed{job_name="FailedJob1",namespace="ns1",reason="Evicted"} 0
    

• kube_persistentvolume_claim_ref のメトリクスが追加されました #1244

  • メトリクスのイメージは以下になります

    # HELP kube_persistentvolume_claim_ref Information about the Persitant Volume Claim Reference.
    # TYPE kube_persistentvolume_claim_ref gauge
    + kube_persistentvolume_claim_ref{claim_namespace="default",name="pv-claim",persistentvolume="test-claimed-pv"} 1
    

• kube_pod_runtimeclass_name_info のメトリクスが追加されました #1276

  • メトリクスのイメージは以下になります

    # HELP kube_pod_runtimeclass_name_info The runtimeclass associated with the pod.
    # TYPE kube_pod_runtimeclass_name_info gauge
    + kube_pod_runtimeclass_name_info{namespace="kube-system",pod="test-pod",runtimeclass_name="kata-fc"} 1
    

v2.0.0-alpha.3 / 2020-11-19

BUGFIX(バグ修正)

• kube_pod_container_resource_limits から node の label が抜け落ちていたのが修正されました #1293

  • メトリクスのイメージは以下になります

    # HELP kube_pod_container_resource_limits The number of requested limit resource by a container.
    # TYPE kube_pod_container_resource_limits gauge
    - kube_pod_container_resource_limits{namespace="default",pod="pod0",container="pod1_con1",resource="nvidia_com_gpu",unit="integer"} 1
    + kube_pod_container_resource_limits{namespace="default",pod="pod0",container="pod1_con1",node="node1",resource="nvidia_com_gpu",unit="integer"} 1
    

• --labels-metric-allow-list CLI flag を用いて、kubernetes の labels をメトリクスとして出力する機能について、調整とリファクタリングが行われました #1301

  • この調整で CLI flag 名が変更になりました

    - --labels-allow-list
    + --labels-metric-allow-list
    

  • この調整の前は、CLI flag に何も指定しない場合は、 kube_*_labels は空でしたが、 namespace と name の値については出力されるように変更になりました。

    # HELP kube_deployment_labels Kubernetes labels converted to Prometheus labels.
    # TYPE kube_deployment_labels gauge
    + kube_deployment_labels{namespace="kube-system",deployment="coredns"} 1
    + kube_deployment_labels{namespace="local-path-storage",deployment="local-path-provisioner"} 1
    + kube_deployment_labels{namespace="kube-system",deployment="kube-state-metrics"} 1
    

  • PR 中に以下と書かれている通り、この PR は変更途中のものになるので、リリース後の cli-arguments のドキュメントを確認する必要があります

    Note this is a breaking change, if you were using --labels-allow-list, look at the PR details for more information.

v2.0.0-beta / 2020-12-04

v2.0.0-alpha.3 がリリースされて2週間、新規の bug の報告がなかったのでついに beta になりました

メトリクスの変更のまとめ

メトリクスの変更については、変更内容の要点を以下にまとめました。影響調査を行う際にご活用ください。

kube_<オブジェクト名>_labels のメトリクスについて

メトリクス名が kube_<オブジェクト名>_labels については、namespace と name 以外については、CLI falg の --labels-metric-allow-list で指定した label 情報しか出力されないようになりました。以下に、pod と node の例を記載します。

# pod
- kube_pod_labels{namespace="kube-system",pod="kube-apiserver-kind-control-plane",label_component="kube-apiserver",label_tier="control-plane"} 1
+ kube_pod_labels{namespace="kube-system",pod="kube-apiserver-kind-control-plane"} 1

# node
- kube_node_labels{node="kind-control-plane",label_beta_kubernetes_io_arch="amd64",label_beta_kubernetes_io_os="linux",label_ingress_ready="true",label_kubernetes_io_arch="amd64",label_kubernetes_io_hostname="kind-control-plane",label_kubernetes_io_os="linux",label_node_role_kubernetes_io_master=""} 1
+ kube_node_labels{node="kind-control-plane"} 1

その他のメトリクスの変更内容を以下に記載します。

DaemonSet Metrics

# メトリクス名の変更
- kube_daemonset_updated_number_scheduled
+ kube_daemonset_status_updated_number_scheduled

# 新規追加
+ kube_daemonset_status_observed_generation

Horizontal Pod Autoscaler Metrics

# メトリクス名の変更
- kube_hpa_*
+ kube_horizontalpodautoscaler_*

Job Metrics

# 新規ラベル `failure reason` の追加
+ kube_job_status_failed

# 新規ラベル `condition` の追加 
+ kube_job_complete

# 新規ラベル `condition` の追加
+ kube_job_failed 

Lease Metrics

# 新規追加
+ kube_lease_owner
+ kube_lease_renew_time

Node Metrics

# 新規ラベル `internal_ip` の追加
+ kube_node_info

# 廃止
- kube_node_status_phase

# 廃止
- kube_node_status_capacity_cpu_cores
- kube_node_status_capacity_memory_bytes
- kube_node_status_capacity_pods
- kube_node_status_allocatable_cpu_cores
- kube_node_status_allocatable_memory_bytes
- kube_node_status_allocatable_pods
# 上記の機能については、以下のメトリクスの `resource` ラベルを使用
+ kube_node_status_capacity
+ kube_node_status_allocatable 

PersistentVolume Metrics

# 新規追加
+ kube_persistentvolume_claim_ref

# 新規ラベル `ebs_volume_id` `gce_persistent_disk_name` の追加
+ kube_persistentvolume_info

Pod Metrics

# 新規ラベル `host_network` の追加
+ kube_pod_info

# 新規追加
+ kube_pod_container_state_started

# 廃止
- kube_pod_container_resource_requests_cpu_cores
- kube_pod_container_resource_requests_memory_bytes
- kube_pod_container_resource_limits_cpu_cores
- kube_pod_container_resource_limits_memory_bytes
# 上記の機能については、以下のメトリクスの `resource` ラベルを使用
+ kube_pod_container_resource_requests
+ kube_pod_container_resource_limits

# 新規追加
+ kube_pod_overhead_cpu_cores
+ kube_pod_overhead_memory_bytes

# 新規追加
+ kube_pod_runtimeclass_name_info

# メトリクス名の変更
- kube_pod_deleted
+ kube_pod_deletion_timestamp

# 新規追加
+ kube_pod_init_container_resource_limits
+ kube_pod_init_container_resource_limits_cpu_cores
+ kube_pod_init_container_resource_limits_memory_bytes
+ kube_pod_init_container_resource_limits_storage_bytes
+ kube_pod_init_container_resource_limits_ephemeral_storage_bytes
+ kube_pod_init_container_resource_requests
+ kube_pod_init_container_resource_requests_cpu_cores
+ kube_pod_init_container_resource_requests_memory_bytes
+ kube_pod_init_container_resource_requests_storage_bytes
+ kube_pod_init_container_resource_requests_ephemeral_storage_bytes

# 新規追加
+ kube_pod_status_reason

ReplicationController metrics

# 新規追加
+ kube_replicationcontroller_owner

VolumeAttachment Metrics

# ラベル名が `nodeName` から `node` に変更
- kube_volumeattachment_info