Kubernetes 1.29 SIG Instrumentation の変更内容

- [Kubernetes 1.27 SIG Instrumentation の変更内容](https://qiita.com/watawuwu/items/92e849642f4477b10a20)
- [Kubernetes 1.28 SIG Instrumentation の変更内容](https://qiita.com/watawuwu/items/7c14a68db116fed2847f)

## はじめに(What’s New の内容含む)

ここでは、Kubernetes 1.29 の [Changelog](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.29.md) からメトリクスの変更と SIG Instrumentation の取り組みについてまとめています。

Kubernetes v1.29 で SIG Instrumentation が扱う主要なテーマはありませんが、SIG Instrumentation に関連した施策があるため記載します。

## [KEP-3077: Contextual Logging](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/3077-contextual-logging)

- [Contextual logging in Kubernetes 1.29: Better troubleshooting and enhanced logging | Kubernetes](https://kubernetes.io/blog/2023/12/20/contextual-logging-in-kubernetes-1-29/)

Kubernetes v1.29 での構造化ロギングについては上記の公式ブログで紹介されています。

[v1.24](https://qiita.com/watawuwu/items/fe9b8e7f8d3089813020) から開始された構造化ロギングも、v1.29 では多くのコンポーネントが移行を完了しました。
マイルストーンはアルファのままですが、スケジューラコンポーネントで懸念されていたパフォーマンスもプロダクション環境で利用するログレベル(-v3 以下)では影響はないという調査結果となったため、現在 v1.30 でベータに移行する話が進んでいます。

## [KEP-2305: Dynamic Cardinality Enforcement](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/2305-metrics-cardinality-enforcement)

この KEP v1.29 で Beta に移行となり、[こちらの実装が入りました](https://github.com/kubernetes/kubernetes/pull/118299)。この KEP は以下の問題の解決を目指しています。

現在、Kubernetes のコンポーネントで提供されているメトリクスは、導入する際に制約がありません。そのためラベル値のカーディナリティが高いメトリクスが意図せずに追加されてしまうと、Prometheus などの計測するコンポーネントでメモリリークを引き起こす問題があります。この問題を解消するために、メトリクスのラベル値を許可リストにより制限する方法が検討されています。

過去に計測側のコンポーネントでメモリリークが発生した際は、修正・対応するために Kubernetes のバイナリ全体を再リリースする必要があった点も課題でした。そのため、この許可リストを動的に参照させる点もモチベーションになっています。

実装を見ると特にフィーチャーゲートは必要なく `allow-metric-labels-manifest` フラグで設定ファイルを指定できるようになっています。 [v1.21 では](https://qiita.com/watawuwu/items/87108aa1545eb5ff4556#dynamic-cardinality-enforcement)直接パラメータを指定できる `allow-metric-labels` フラグも実装されています。

- `metricName,labelName=labelValue,labelValue,...`

許可リストにないラベル値は、`cardinality_enforcement_unexpected_categorizations_total` メトリクスによってカウントされます。


それでは、メトリクスの変更について説明していきます。
こちらは、私が全ての変更点からメトリクスに関連するものを抜粋した内容となります。

## メトリクスの変更

### component-base

<!-- - The metrics controlled by the `ComponentSLIs` feature-gate and served at `/metrics/slis` are now GA and unconditionally enabled. The feature-gate will be removed in `v1.31`. ([#120574](https://github.com/kubernetes/kubernetes/pull/120574), [@&#xFFF0;logicalhan](https://github.com/logicalhan)) -->
- [MOD] `ComponentSLIs` フィーチャーゲートが GA となり、`healthcheck` と `healthchecks_total` の StabilityLevel も Stable となりました([#120574](https://github.com/kubernetes/kubernetes/pull/120574), [@&#xFFF0;logicalhan](https://github.com/logicalhan))


### kube-apiserver

<!-- - Added `apiextensions_apiserver_update_ratcheting_time` metric for tracking time taken during requests by feature `CRDValidationRatcheting`. ([#121462](https://github.com/kubernetes/kubernetes/pull/121462), [@&#xFFF0;alexzielenski](https://github.com/alexzielenski)) -->
- [ADD] `CRDValidationRatcheting` フィーチャーゲートの機能であるバリデーション時間を計測するメトリクスが追加されました([#121462](https://github.com/kubernetes/kubernetes/pull/121462), [@&#xFFF0;alexzielenski](https://github.com/alexzielenski))
  - Histogram: `apiextensions_apiserver_validation_ratcheting_seconds`
    - Labels: {}
<!-- - Added `apiserver_watch_list_duration_seconds` metrics which will measure response latency distribution in seconds for watchlist requests broken by group, version, resource and scope. ([#120490](https://github.com/kubernetes/kubernetes/pull/120490), [@&#xFFF0;p0lyn0mial](https://github.com/p0lyn0mial)) -->
- [ADD] Watch リクエストのレスポンス待ち時間を計測するメトリクスが追加されました。これは [KEP-3157: allow informers for getting a stream of data instead of chunking](https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/3157-watch-list) に関連したもので処理性能の低下をモニタリングするために追加されました([#120490](https://github.com/kubernetes/kubernetes/pull/120490), [@&#xFFF0;p0lyn0mial](https://github.com/p0lyn0mial))
  - Histogram: `apiserver_watch_list_duration_seconds`
    - Labels: {"group", "version", "resource", "scope"}
<!-- - Introduced new apiserver metric `apiserver_flowcontrol_current_inqueue_seats`. This metric is analogous to `apiserver_flowcontrol_current_inqueue_requests`, but tracks the total number of seats, as each request can take more than one seat. ([#119385](https://github.com/kubernetes/kubernetes/pull/119385), [@&#xFFF0;andrewsykim](https://github.com/andrewsykim)) -->
- [ADD] 次のメトリクスが追加されました([#119385](https://github.com/kubernetes/kubernetes/pull/119385), [@&#xFFF0;andrewsykim](https://github.com/andrewsykim))
  - Gauge: `apiserver_flowcontrol_current_inqueue_seats`
    - Labels: {"priority_level", "flow_schema"}
<!-- - The `kube-apiserver` will now expose four new metrics to inform about errors on the clusterIP and nodePort allocation logic. ([#120843](https://github.com/kubernetes/kubernetes/pull/120843), [@&#xFFF0;aojea](https://github.com/aojea)) -->
- [ADD] clusterIP と nodePort の割当処理時に発生したエラー回数を計測するメトリクスが追加されました([#120843](https://github.com/kubernetes/kubernetes/pull/120843), [@&#xFFF0;aojea](https://github.com/aojea))
  - Counter: `apiserver_clusterip_repair_ip_errors_total`
    - Labels: {"type"}
  - Counter: `apiserver_clusterip_repair_reconcile_errors_total`
    - Labels: {}
  - Counter: `apiserver_nodeport_repair_port_errors_total`
    - Labels: {"type"}
  - Counter: `apiserver_nodeport_repair_reconcile_errors_total`
    - Labels: {}
<!-- - Registered metric `apiserver_request_body_size_bytes` to track the size distribution of requests by `resource` and `verb`. ([#120474](https://github.com/kubernetes/kubernetes/pull/120474), [@&#xFFF0;YaoC](https://github.com/YaoC)) [SIG API Machinery and Instrumentation] -->
- [ADD] リクエストボディサイズを記録するメトリクスが公開されました。今までも実装はされていたようですが登録漏れだったようです([#120474](https://github.com/kubernetes/kubernetes/pull/120474), [@&#xFFF0;YaoC](https://github.com/YaoC))
  - `apiserver_request_body_size_bytes`
    - Labels: {"resource", "verb"}
<!-- - Use of secret-based service account tokens now adds an `authentication.k8s.io/legacy-token-autogenerated-secret` or `authentication.k8s.io/legacy-token-manual-secret` audit annotation containing the name of the secret used. ([#118598](https://github.com/kubernetes/kubernetes/pull/118598), [@&#xFFF0;yuanchen8911](https://github.com/yuanchen8911)) [SIG Auth, Instrumentation and Testing] -->
- [ADD] シークレットベースのサービスアカウントトークンを使用すると、使用されたシークレットの名前を含む `authentication.k8s.io/legacy-token-autogenerated-secret` または `authentication.k8s.io/legacy-token-manual-secret` アノテーションが追加され、メトリクスにも計測されるようになりました([#118598](https://github.com/kubernetes/kubernetes/pull/118598), [@&#xFFF0;yuanchen8911](https://github.com/yuanchen8911))
  - Counter: `serviceaccount_legacy_manual_token_uses_total`
    - Labels: {}
  - Counter: `serviceaccount_legacy_auto_token_uses_total`
    - Labels: {}
<!-- - Added apiserver identity to the following metrics:  `apiserver_envelope_encryption_key_id_hash_total`, `apiserver_envelope_encryption_key_id_hash_last_timestamp_seconds`, `apiserver_envelope_encryption_key_id_hash_status_last_timestamp_seconds`, `apiserver_encryption_config_controller_automatic_reload_failures_total`, `apiserver_encryption_config_controller_automatic_reload_success_total`, `apiserver_encryption_config_controller_automatic_reload_last_timestamp_seconds`. Fixed bug to surface events for the following metrics: `apiserver_encryption_config_controller_automatic_reload_failures_total`, `apiserver_encryption_config_controller_automatic_reload_last_timestamp_seconds`, `apiserver_encryption_config_controller_automatic_reload_success_total`. ([#120438](https://github.com/kubernetes/kubernetes/pull/120438), [@&#xFFF0;ritazh](https://github.com/ritazh)) -->
- [FIX] KMS V2: `apiserver_id_hash` ラベルが追加されバグが修正されました([#120438](https://github.com/kubernetes/kubernetes/pull/120438), [@&#xFFF0;ritazh](https://github.com/ritazh))
  - Counter: `apiserver_encryption_config_controller_automatic_reload_failures_total`
    - Labels: {"apiserver_id_hash"}
  - Histogram: `apiserver_encryption_config_controller_automatic_reload_last_timestamp_seconds`
    - Labels: "status", "apiserver_id_hash"}
  - Counter: `apiserver_encryption_config_controller_automatic_reload_success_total`
    - Labels: {"apiserver_id_hash"}
- [MOD] KMS V2: `apiserver_id_hash` ラベルが追加されました[#120438](https://github.com/kubernetes/kubernetes/pull/120438), [@&#xFFF0;ritazh](https://github.com/ritazh))
  - Counter: `apiserver_envelope_encryption_key_id_hash_total`
    - Labels: {"transformation_type", "provider_name", "key_id_hash", "apiserver_id_hash"}
  - Histogram: `apiserver_envelope_encryption_key_id_hash_last_timestamp_seconds`
    - Labels: {"transformation_type", "provider_name", "key_id_hash", "apiserver_id_hash"}
  - Histogram: `apiserver_envelope_encryption_key_id_hash_status_last_timestamp_seconds`
    - Labels: {"provider_name", "key_id_hash", "apiserver_id_hash"}
  - Counter: `apiserver_encryption_config_controller_automatic_reload_failures_total`
    - Labels: {"apiserver_id_hash"}
  - Counter: `apiserver_encryption_config_controller_automatic_reload_success_total`
    - Labels: {"apiserver_id_hash"}
  - Histogram: `apiserver_encryption_config_controller_automatic_reload_last_timestamp_seconds`
    - Labels: {"status", "apiserver_id_hash"}
<!-- - Renamed `apiserver_request_body_sizes` metric to `apiserver_request_body_size_bytes`. ([#120503](https://github.com/kubernetes/kubernetes/pull/120503), [@&#xFFF0;dgrisonnet](https://github.com/dgrisonnet)) -->
- [MOD] Prometheus のベストプラクティスに合わせてリネームされました([#120503](https://github.com/kubernetes/kubernetes/pull/120503), [@&#xFFF0;dgrisonnet](https://github.com/dgrisonnet))
  - Histogram: `apiserver_request_body_sizes` => `apiserver_request_body_size_bytes`
    - Labels: {"resource", "verb"}

### kubelet

<!-- - `kubelet` now emits a metric for end-to-end pod startup latency, including image pull. ([#121041](https://github.com/kubernetes/kubernetes/pull/121041), [@&#xFFF0;ruiwen-zhao](https://github.com/ruiwen-zhao)) -->
- [ADD] Pod が起動するまでのレイテンシーを記録するメトリクスが追加されました。このレイテンシーはイメージのプルおよび Init コンテナの実行時間が含まれ、Pod の作成タイムスタンプからすべてのコンテナが開始されウォッチによって観測されるまでの時間となります。([#121041](https://github.com/kubernetes/kubernetes/pull/121041), [@&#xFFF0;ruiwen-zhao](https://github.com/ruiwen-zhao))
  - Histogram: `kubelet_pod_start_total_duration_seconds`
    - Labels: {}
<!-- - `kubelet` now exposes latency metrics of different stages of the node startup. ([#118568](https://github.com/kubernetes/kubernetes/pull/118568), [@&#xFFF0;qiutongs](https://github.com/qiutongs)) -->
- [ADD] さまざまなステージのノード起動時間を記録するメトリクスが追加されました([#118568](https://github.com/kubernetes/kubernetes/pull/118568), [@&#xFFF0;qiutongs](https://github.com/qiutongs))
  - Gauge: `kubelet_node_startup_pre_kubelet_duration_seconds`
    - Labels: {}
  - Gauge: `kubelet_node_startup_pre_registration_duration_seconds`
    - Labels: {}
  - Gauge: `kubelet_node_startup_registration_duration_seconds`
    - Labels: {}
  - Gauge: `kubelet_node_startup_post_registration_duration_seconds`
    - Labels: {}
  - Gauge: `kubelet_node_startup_duration_seconds`
    - Labels: {}
<!-- - Fixed bug that kubelet resource metric `container_start_time_seconds` had timestamp equal to container start time. ([#120518](https://github.com/kubernetes/kubernetes/pull/120518), [@&#xFFF0;saschagrunert](https://github.com/saschagrunert)) [SIG Instrumentation, Node and Testing] -->
- [FIX] メトリクスのタイムスタンプにコンテナのスタートタイムを指定していたバグが修正されました([#120518](https://github.com/kubernetes/kubernetes/pull/120518), [@&#xFFF0;saschagrunert](https://github.com/saschagrunert))
  - Gauge: `container_start_time_seconds`
    - Labels: {"container", "namespace", "pod"}
<!-- - Metric buckets for `pod_start_duration_seconds` were changed to `{0.5, 1, 2, 3, 4, 5, 6, 8, 10, 20, 30, 45, 60, 120, 180, 240, 300, 360, 480, 600, 900, 1200, 1800, 2700, 3600}`. ([#120680](https://github.com/kubernetes/kubernetes/pull/120680), [@&#xFFF0;ruiwen-zhao](https://github.com/ruiwen-zhao)) -->
- [MOD] バケット設定を変更しました([#120680](https://github.com/kubernetes/kubernetes/pull/120680), [@&#xFFF0;ruiwen-zhao](https://github.com/ruiwen-zhao))
  - Histogram: `kubelet_pod_start_duration_seconds`
    - Labels: {}
    - Buckets: {0.5, 1, 2, 3, 4, 5, 6, 8, 10, 20, 30, 45, 60, 120, 180, 240, 300, 360, 480, 600, 900, 1200, 1800, 2700, 3600}
<!-- - Graduated the following kubelet resource metrics to **general availability**: -->
<!--   - `container_cpu_usage_seconds_total` -->
<!--   - `container_memory_working_set_bytes` -->
<!--   - `container_start_time_seconds` -->
<!--   - `node_cpu_usage_seconds_total` -->
<!--   - `node_memory_working_set_bytes` -->
<!--   - `pod_cpu_usage_seconds_total` -->
<!--   - `pod_memory_working_set_bytes` -->
<!--   - `resource_scrape_error` -->
<!--   Deprecated (renamed) `scrape_error` in favor of `resource_scrape_error` ([#116897](https://github.com/kubernetes/kubernetes/pull/116897), [@&#xFFF0;Richabanker](https://github.com/Richabanker)) -->
- [MOD] StabilityLevel が Stable となりました([#116897](https://github.com/kubernetes/kubernetes/pull/116897), [@&#xFFF0;Richabanker](https://github.com/Richabanker))
  - `container_cpu_usage_seconds_total`
  - `container_memory_working_set_bytes`
  - `container_start_time_seconds`
  - `node_cpu_usage_seconds_total`
  - `node_memory_working_set_bytes`
  - `pod_cpu_usage_seconds_total`
  - `pod_memory_working_set_bytes`
  - `resource_scrape_error`
- [DEPRECATED] `scrape_error` が非推奨となりました。代わりに `resource_scrape_error` を利用してください。([#116897](https://github.com/kubernetes/kubernetes/pull/116897), [@&#xFFF0;Richabanker](https://github.com/Richabanker))

### kube-controller-manager

<!-- - Decoupled `TaintManager` from `NodeLifeCycleController` (KEP-3902). ([#119208](https://github.com/kubernetes/kubernetes/pull/119208), [@&#xFFF0;atosatto](https://github.com/atosatto)) [sig/scheduling,sig/node,sig/api-machinery,sig/apps,sig/instrumentation,sig/testing] -->
- [ADD] KEP-3902: TaintEvictionController が削除した Pod 数と Taint が付与されてから、TaintEvictionController によって削除されるまでの待ち時間を記録するメトリクスが追加されました([#119208](https://github.com/kubernetes/kubernetes/pull/119208), [@&#xFFF0;atosatto](https://github.com/atosatto))
  - Counter: `taint_eviction_controller_pod_deletions_total`
    - Labels: {}
  - Histogram: `taint_eviction_controller_pod_deletion_duration_seconds`
    - Labels: {}
<!-- - Added `job_pods_creation_total` metrics for tracking Pods created by the Job controller labeled by events which triggered the Pod creation. ([#121481](https://github.com/kubernetes/kubernetes/pull/121481), [@&#xFFF0;dejanzele](https://github.com/dejanzele)) -->
- [ADD] ジョブコントローラーによって作成された Pod 数を記録するメトリクスが追加されました([#121481](https://github.com/kubernetes/kubernetes/pull/121481), [@&#xFFF0;dejanzele](https://github.com/dejanzele))
  - Gauge: `job_controller_job_pods_creation_total`
    - Labels: {"reason", "status"}
<!-- - Introduced the `job_finished_indexes_total` metric for the `BackoffLimitPerIndex` feature. ([#121292](https://github.com/kubernetes/kubernetes/pull/121292), [@&#xFFF0;mimowo](https://github.com/mimowo)) -->
- [ADD] `JobBackoffLimitPerIndex` フィーチャーゲートで利用されるメトリクスが追加されました([#121292](https://github.com/kubernetes/kubernetes/pull/121292), [@&#xFFF0;mimowo](https://github.com/mimowo))
  - Gauge: `job_controller_job_finished_indexes_total`
    - Labels: {"status", "backoffLimit"}
<!-- - Set the resolution for the `job_controller_job_sync_duration_seconds` metric from `4ms` to `1min`. ([#120577](https://github.com/kubernetes/kubernetes/pull/120577), [@&#xFFF0;alculquicondor](https://github.com/alculquicondor)) -->
- [MOD] バケット設定を変更しました([#120577](https://github.com/kubernetes/kubernetes/pull/120577), [@&#xFFF0;alculquicondor](https://github.com/alculquicondor))
  - Histogram: `job_controller_job_sync_duration_seconds`
    - Labels: {"completion_mode", "result", "action"}
    - Buckets: ExponentialBuckets(0.004, 2, 15)

### kube-scheduler

<!-- - Added a new scheduler metric, `pod_scheduling_sli_duration_seconds`, and started the deprecation for `pod_scheduling_duration_seconds`. ([#119049](https://github.com/kubernetes/kubernetes/pull/119049), [@&#xFFF0;helayoty](https://github.com/helayoty)) -->
- [ADD] スケジューリングされる Pod の E2E 待ち時間を記録する SLI 用のメトリクスが追加されました。この値には Pod がスケジューリングのキューに入ってから、複数回のスケジューリング試行が行われる可能性があります。([#119049](https://github.com/kubernetes/kubernetes/pull/119049), [@&#xFFF0;helayoty](https://github.com/helayoty))
  - Histogram: `scheduler_pod_scheduling_sli_duration_seconds`
    - Labels: {"attempts"}
- [DEPRECATD] SLI に関するメトリクスが追加されたため、以下のメトリクスが非推奨となりました。このメトリクスは v1.31 で削除予定です。([#119049](https://github.com/kubernetes/kubernetes/pull/119049), [@&#xFFF0;helayoty](https://github.com/helayoty))
  - Histogram: `scheduler_pod_scheduling_duration_seconds`
    - Labels: {"attempts"}

### kube-proxy

- なし

### その他

<!-- - Added `apiserver_envelope_encryption_dek_cache_filled` to measure number of records in data encryption key (DEK) cache. ([#119878](https://github.com/kubernetes/kubernetes/pull/119878), [@&#xFFF0;ritazh](https://github.com/ritazh)) -->
- [ADD] データ暗号化キー（DEK）のソースキャッシュサイズを記録するメトリクスが追加されました。再起動後の値は KMS プラグインに対して行う復号化 RPC コール回数の概算値となります([#119878](https://github.com/kubernetes/kubernetes/pull/119878), [@&#xFFF0;ritazh](https://github.com/ritazh))
  - Gauge: `apiserver_envelope_encryption_dek_source_cache_size`
    - Labels: {"provider_name"}

## メトリクス以外の変更点

<!-- - List of metric labels can now be configured by supplying a manifest using the `--allow-metric-labels-manifest` flag. ([#118299](https://github.com/kubernetes/kubernetes/pull/118299), [@&#xFFF0;rexagod](https://github.com/rexagod)) -->
- 冒頭で説明した KEP-2305: Dynamic Cardinality Enforcement で利用される `--allow-metric-labels-manifest` フラグが導入されました([#118299](https://github.com/kubernetes/kubernetes/pull/118299), [@&#xFFF0;rexagod](https://github.com/rexagod))
<!-- - Migrated the `nodevolumelimits` scheduler plugin to use [contextual logging](https://k8s.io/docs/concepts/cluster-administration/system-logs/#contextual-logging). ([#116884](https://github.com/kubernetes/kubernetes/pull/116884), [@&#xFFF0;mengjiao-liu](https://github.com/mengjiao-liu)) -->
- `nodevolumelimits` スケジューラープラグインが[構造化ロギング](https://k8s.io/docs/concepts/cluster-administration/system-logs/#contextual-logging)に移行しました([#116884](https://github.com/kubernetes/kubernetes/pull/116884), [@&#xFFF0;mengjiao-liu](https://github.com/mengjiao-liu))
<!-- - Migrated the `volumebinding scheduler plugins` to use [contextual logging](https://k8s.io/docs/concepts/cluster-administration/system-logs/#contextual-logging). ([#116803](https://github.com/kubernetes/kubernetes/pull/116803), [@&#xFFF0;mengjiao-liu](https://github.com/mengjiao-liu)) -->
- `volumebinding` スケジューラープラグインが[構造化ロギング](https://k8s.io/docs/concepts/cluster-administration/system-logs/#contextual-logging)に移行しました([#116803](https://github.com/kubernetes/kubernetes/pull/116803), [@&#xFFF0;mengjiao-liu](https://github.com/mengjiao-liu))
<!-- - Migrated the remainder of the scheduler to use [contextual logging](https://k8s.io/docs/concepts/cluster-administration/system-logs/#contextual-logging). ([#120933](https://github.com/kubernetes/kubernetes/pull/120933), [@&#xFFF0;mengjiao-liu](https://github.com/mengjiao-liu)) [SIG Instrumentation, Scheduling and Testing] -->
- kube-scheduler を[構造化ロギング](https://k8s.io/docs/concepts/cluster-administration/system-logs/#contextual-logging)に移行しました([#120933](https://github.com/kubernetes/kubernetes/pull/120933), [@&#xFFF0;mengjiao-liu](https://github.com/mengjiao-liu))
<!-- - Scheduler: in 1.29 pre-releases, enabling contextual logging slowed down pod scheduling. ([#121715](https://github.com/kubernetes/kubernetes/pull/121715), [@&#xFFF0;pohly](https://github.com/pohly)) [SIG Instrumentation and Scheduling] -->
- kube-scheduler のロギングレベル v3でのパフォーマンス・リグレッションを修正し、構造化ロギングに移行しました([#121715](https://github.com/kubernetes/kubernetes/pull/121715), [@&#xFFF0;pohly](https://github.com/pohly))