Kubernetes 1.32 SIG Instrumentation の変更内容

• Kubernetes 1.30 SIG Instrumentation の変更内容
• Kubernetes 1.31 SIG Instrumentation の変更内容

はじめに

この記事では Kubernetes v1.32 の Changelog から、メトリクスの変更点と SIG Instrumentation の取り組みについてまとめています。

Kubernetes v1.32 の SIG Instrumentation では 2 つの KEP が Alpha として導入されました。

これらの KEP で導入されているエンドポイントは Google 社でモニタリングやデバッグに有用なエンドポイントとして利用されている z-pages の機能の一部となっています。z-pages の z はアプリケーション側のドメインで必要なエンドポイントと重複しないように /healthz、/statusz、 /varz などのサフィックスとして設けられた文字のようです。確かな情報がないため、知っている方がいればコメントで教えてください。

• Where does the convention of using /healthz for application health checks come from? - Stack Overflow

KEP-4827: Component Statusz

/statusz エンドポイントをコンポーネントに実装することを提案している KEP です。

/statusz エンドポイントを実装することで、外部スクリプトやコンポーネントごとに独自の方法で取得・提供していた情報を統一的なインターフェイスで提供できるようになります。また、このエンドポイントではビルドバージョン、Go のバージョン、互換性の詳細、その他の重要なコンポーネント情報の概要を提供することで、コンポーネントの可観測性が強化され、トラブルシューティングやデバッグに役立てることも目指しています。

個人的にはこれらの情報の多くはすでにメトリクスとして公開されており、インターフェイスに関しても component-base で実装すれば統一されるため、メトリクスとの使い分けが難しいと感じました。KEP のユーザーストーリーでは /statusz エンドポイントの参照権限を管理/監視/開発などを実施する最小限の人員に設定することが推奨されています。これによりセンシティブなデバッグ情報が意図せず公開されることを防ぐことができるため、権限や公開範囲を分離できるという点ではメリットがありそうです。

v1.32.0 ではレスポンス内容は次のような内容となっています。

kube-apiserver statusz
Warning: This endpoint is not meant to be machine parseable, has no formatting compatibility guarantees and is for debugging purposes only.

Started:  Tue Jan  7 03:03:57 UTC 2025
Up:  0 hr 05 min 28 sec
Go version:  go1.23.3
Binary version:  1.32.0
Emulation version:  1.32

KEP では上記の内容に加えて z-pages のエンドポイントのリストを出力することも提案されています。

KEP-4828: Component Flagz

KEP-4827 の Component Statusz と同様に、z-pages のエンドポイントとして /flagz エンドポイントをコンポーネントに実装することを提案している KEP です。

このエンドポイントでは、コンポーネントのコマンドラインフラグや設定オプションのキーと値を表示します。

v1.32.0 の段階ではレスポンス内容は次のような内容となっています。

kind で起動した kube-apiserver の出力内容（一部抜粋）

kube-apiserver flags
Warning: This endpoint is not meant to be machine parseable, has no formatting compatibility guarantees and is for debugging purposes only.

admission-control: []
admission-control-config-file: 
advertise-address: xx.xx.xx.xx
aggregator-reject-forwarding-redirect: true
allow-metric-labels: []
allow-metric-labels-manifest: 
allow-privileged: true
...
v: 0
vmodule: 

メトリクスの変更

メトリクスの変更は、チェンジログだけでなく、ドキュメントの変更履歴からも確認できます。ドキュメントは documentation-list.yaml のファイルから機械的に生成しています。

• 生成プログラム
• Update metrics reference for v1.32 release by mengjiao-liu · Pull Request #48684 · kubernetes/website
• Update metrics docs for v1.32 release(Note this must be committed after the code freeze) by mengjiao-liu · Pull Request #128720 · kubernetes/kubernetes

kube-apiserver

• フィーチャーゲート ExternalServiceAccountTokenSigner に関するメトリクスが追加されました(#128190, @￰HarshalNeelkamal)
  • Gauge: apiserver_externaljwt_fetch_keys_data_timestamp
  • Gauge: apiserver_externaljwt_fetch_keys_success_timestamp
  • Counter: apiserver_externaljwt_fetch_keys_request_total
    • Labels: code
  • Counter: apiserver_externaljwt_sign_request_total
    • Labels: code
  • Histogram: apiserver_externaljwt_request_duration_seconds
    • Labels: code、method
• リソースを特定するために resource ラベルが追加されました(#126512, @￰kmala)
  • Counter: apiserver_storage_transformation_operations_total
    • Labels: resource, status, transformation_type, transformer_prefix
• ValidatingAdmissionPolicy に関するメトリクスが修正され、経過時間が正しく記録されるようになりました(#128463, @￰knrc)
  • Histogram: apiserver_validating_admission_policy_check_duration_seconds
    • Labels: enforcement_action、 error_type、policy、policy_binding
• ヘルプドキュメントが修正されました(#127898, @￰modulitos)
  • Counter: apiserver_admission_webhook_fail_open_count
    • Help: Admission webhook fail open count, identified by name and broken out for each admission type (validating or mutating admit).
  • Counter: apiserver_admission_webhook_request_total
    • Help: Admission webhook request total, identified by name and broken out for each admission type (validating or mutating admit) and operation. Additional labels specify whether the request was rejected or not and an HTTP status code. Codes greater than 600 are truncated to 600, to keep the metrics cardinality bounded.

kubelet

• CPU マネージャーにより管理されている CPU プールに関する情報を記録するメトリクスが追加されました(#127506, @￰ffromani)
  • Gauge: kubelet_cpu_manager_shared_pool_size_millicores
  • Gauge: kubelet_cpu_manager_exclusive_cpu_allocation_count
• コンテナが割り当てられたコンピューティングリソースを記録するメトリクスが追加されました(#127155, @￰ffromani)
  • Counter: kubelet_container_aligned_compute_resources_count
    • Labels: boundary、scope
• DRA のノード操作とDRA の gRPC のレイテンシを記録するメトリクスが追加されました(#127146, @￰bart0sh)
  • Histogram: dra_operations_duration_seconds
    • Labels: is_error、operation_name
  • Histogram: dra_grpc_operations_duration_seconds
    • Labels: driver_name、grpc_status_code、method_name
• アドミッション時に拒否された数を記録するメトリクスが追加されました(#128556, @￰AnishShah)
  • Counter: kubelet_admission_rejections_total
    • Labels: reason
• ヘルプテキストが修正されました(#128189, @￰zylxjtu)
  • Gauge: kubelet_graceful_shutdown_end_time_seconds
    • Help: Last graceful shutdown start end time since unix epoch in seconds

kube-controller-manager

• ResourceClaims の総数と割り当て済みの ResourceClaims の数を記録するメトリクスが追加されました(#127661, @￰pohly)
  • Gauge: resourceclaim_controller_resource_claims
  • Gauge: resourceclaim_controller_allocated_resource_claims
• ClusterTrustBundle に関するメトリクスが追加されました(#127326, @￰stlaz)
  • Histogram: clustertrustbundle_publisher_sync_duration_seconds
    • Labels: code
  • Counter: clustertrustbundle_publisher_sync_total
    • Labels: code
• 同じノードで同じボリュームを異なる SELinux コンテキストで使用すると、片方の Pod がボリュームにアクセスできなくなるため、対象の Pod を記録するメトリクスが追加されました(#128242, , @￰jsafrane)
  • Custom: selinux_warning_controller_selinux_volume_conflict
    • Labels: property、pod1_namespace、pod1_name、pod1_value、pod2_namespace、pod2_name、pod2_value

kube-scheduler

• 現在のスケジューリングのキューでトラッキングされているイベントの数を記録するメトリクスが追加されました(#127052, @￰sanposhiho)
  • Gauge: scheduler_inflight_events
    • Labels: event
• フィーチャーゲート SchedulerAsyncPreemption を有効にした場合、プリエンプションを実行するための goroutine の数と処理時間を記録するメトリクスが追加されました(#128170, @￰sanposhiho)
  • Counter: scheduler_preemption_goroutines_execution_total
    • Labels: result
  • Histogram: scheduler_preemption_goroutines_duration_seconds
    • Labels: result

メトリクス以外の変更点

• [kube-apiserver] 冒頭で述べた KEP-4828: Component Flagz に対応しました(#127581, @￰richabanker)
• [kube-apiserver] 冒頭で述べた KEP-4827: Component Statusz に対応しました(#125577, @￰richabanker)
• [kubelet] カーネルバージョン 5.8 より古いバージョンで cgroup v2 を利用すると、警告ログやイベントを出力するようになりました(#126595, @￰pacoxu)
• [client-go/rest] リクエスト/レスポンスのコンテキストログに呼び出し元のソースコードの正確な位置情報を記録するように更新されました(#126999, @￰pohly)
• [kube-apiserver] --tracing-config-file オプションで指定された設定ファイルが厳密に検証されるようになりました。重複したフィールドや不明なフィールドが含まれているとエラーが発生します(#128073, @￰seans3)
• フィーチャーゲート ComponentSLIs が GA となったため削除されました(#128317、#127787, @￰Jefftree)
• [kube-scheduler] --allow-metric-labels フラグが処理されるまで、メトリクスの初期化を遅延させます。この修正によりフラグの値を利用できることが保証され、ラベル値に unexpected と記録される不具合が修正されました(#126762, @￰richabanker)
• [kube-scheduler] #126762 と同様の対応がされました(#128100, @￰yongruilin)
• [kubelet] セキュアポート 10250 とインセキュアポート 10255 のどちらでアクセスしても /metrics/slis エンドポイントがアクセスできるように修正されました(#128430, @￰richabanker)
• [trace] 一部の子スパンと親スパンが並列に表示されていたので、子スパンと親スパンの間違った階層構造（具体的には SerializeObject と List）が修正されました(#127551, @￰carlory)