kube 状態メトリクス
v2.14.0
kube-state-metrics (KSM) は、Kubernetes API サーバーをリッスンし、オブジェクトの状態に関するメトリクスを生成する単純なサービスです。 (以下の「メトリクス」セクションの例を参照してください。)これは、個々の Kubernetes コンポーネントの健全性ではなく、デプロイメント、ノード、ポッドなど、内部のさまざまなオブジェクトの健全性に焦点を当てています。
kube-state-metrics は、変更を加えずに Kubernetes API オブジェクトからメトリクスを生成することについてのものです。これにより、kube-state-metrics によって提供される機能が、Kubernetes API オブジェクト自体と同じグレードの安定性を持つことが保証されます。これは、kubectl がわかりやすいメッセージを表示するために特定のヒューリスティックを適用するため、特定の状況では kube-state-metrics が kubectl とまったく同じ値を示さない可能性があることを意味します。 kube-state-metrics は、Kubernetes API から未変更の生データを公開します。これにより、ユーザーは必要なデータをすべて入手し、必要に応じてヒューリスティックを実行できます。
メトリクスは、HTTP エンドポイントでエクスポートされ/metricsがエクスポートされます。これらは平文として提供されます。これらは、Prometheus 自体、または Prometheus クライアント エンドポイントのスクレイピングと互換性のあるスクレイパーによって消費されるように設計されています。ブラウザで/metrics開いて生のメトリクスを確認することもできます。 /metricsエンドポイントで公開されるメトリクスは、Kubernetes クラスターの現在の状態を反映していることに注意してください。 Kubernetes オブジェクトが削除されると、 /metricsエンドポイントには表示されなくなります。
注記
この README はテンプレートから生成されています。そこで変更を加えて、 make generate-templateを実行してください。
バージョン管理
Kubernetesのバージョン
互換性マトリックス
リソースグループのバージョンの互換性
コンテナイメージ
メトリクスのドキュメント
ラベル名の競合解決
Kube-state-metrics セルフメトリクス
リソースの推奨事項
レイテンシ
原価計算に関するメモ
kube-state-metrics と metrics-server
kube-state-metrics のスケーリング
自動シャーディング
リソースの推奨事項
水平シャーディング
ポッドメトリクスの 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-state-metrics | 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 のリソースは進化する可能性があります。つまり、リソースのグループ バージョンがアルファからベータに変更され、最終的にはさまざまな Kubernetes バージョンで GA になる可能性があります。現時点では、kube-state-metrics は、最新リリースで利用可能な最も古い API のみを使用します。
最新のコンテナ イメージは次の場所にあります。
registry.k8s.io/kube-state-metrics/kube-state-metrics:v2.14.0 (アーチ: amd64 、 arm 、 arm64 、 ppc64leおよびs390x )
ここですべてのマルチアーキテクチャ画像を表示します
アルファ版の Kubernetes API に基づくリソースとメトリクスは、安定性の保証から除外されており、特定のリリースで変更される可能性があります。
公開されたメトリクスの詳細については、 docsディレクトリを参照してください。
*_labelsファミリーのメトリクスは、Kubernetes ラベルを Prometheus ラベルとして公開します。 Kubernetes はラベル名に使用できる文字に関して Prometheus よりも寛容であるため、サポートされていない文字は自動的にアンダースコアに変換されます。たとえば、 app.kubernetes.io/name label_app_kubernetes_io_nameになります。
foo-barやfoo_barなどの複数の Kubernetes ラベルが同じ Prometheus ラベルlabel_foo_barに変換される場合、この変換により競合が発生する可能性があります。
Kube-state-metrics は、この競合を解決するためにサフィックス_conflictNを自動的に追加するため、上記のラベルをlabel_foo_bar_conflict1およびlabel_foo_bar_conflict2に変換します。
この競合の解決方法をより詳細に制御したい場合は、スタックの別のレベルでこの問題に対処することを検討することをお勧めします。たとえば、競合が発生しないようにするアドミッション 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 オブジェクト (ポッド/ノード/デプロイメント/シークレットなど) のサイズによって変化します。クラスター内の 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 ノードからメトリクスを定期的に収集するクラスター レベルのコンポーネントです。メトリクスは集約され、メモリに保存され、メトリクス 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 の間のレイテンシを短縮する 1 つの方法は、 --use-apiserver-cacheフラグを指定して KSM を実行することです。このオプションは、レイテンシーの短縮に加えて、etcd の負荷の軽減にもつながります。
シャーディングは慎重に使用する必要があり、シャーディングが設定され期待どおりに機能していることを確認するために追加の監視を設定する必要があります (たとえば、合計シャードのうち各シャードのインスタンスが設定されている)。
自動シャーディングにより、各シャードは StatefulSet にデプロイされるときにその名目上の位置を検出できるようになり、シャーディングを自動的に構成するのに役立ちます。これは実験的な機能であり、予告なく壊れたり削除されたりする可能性があります。
自動シャーディングを有効にするには、kube-state-metrics がStatefulSetによって実行され、ポッド名と名前空間が--podおよび--pod-namespaceフラグを介して kube-state-metrics プロセスに渡される必要があります。自動シャーディング機能を示すマニフェストの例は/examples/autoshardingにあります。
このシャードのデプロイ方法は、シャードごとに 1 つのDeployment持つのではなく、単一の Kubernetes リソース (この場合は単一のStatefulSet ) を通じて KSM シャードを管理する場合に便利です。この利点は、多数のシャードをデプロイする場合に特に顕著になります。
自動シャーディング設定を使用する場合の欠点は、 StatefulSetによってサポートされるロールアウト戦略に起因します。 StatefulSetによって管理される場合、ポッドは一度に 1 つずつ置き換えられ、各ポッドは最初に終了されてから再作成されます。このようなロールアウトは時間がかかるだけでなく、各シャードのダウンタイムも短くなります。ロールアウト中に Prometheus のスクレイピングが発生すると、kube-state-metrics によってエクスポートされたメトリクスの一部が失われる可能性があります。
ポッド メトリクスの場合は、次のフラグを使用してノードごとにシャード化できます。
--node=$(NODE_NAME)
各 kube-state-metrics ポッドは、FieldSelector (spec.nodeName) を使用して、同じノード上のポッド メトリクスのみを監視/リストします。
daemonset 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
未割り当てのポッドのメトリクスを追跡するには、次の例に示すように、追加のデプロイメントを追加し、 --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 クラスターへの読み取り専用アクセス権を持つサービス アカウント トークンを持つ Kubernetes ポッド内で kube-state-metrics を構築して実行するだけです。
( kube-prometheus ) スタックは、コンポーネントの 1 つとして 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 スクレイプ構成を作成することをお勧めします。注釈ベースの検出は、エンドポイントの 1 つだけを選択できるため、推奨されません。また、kube-state-metrics は基本的にメトリクス エンドポイントを介して利用可能なほとんどの情報への読み取りアクセスを許可するため、ほとんどの場合特別な認証と認可の要件があります。
注: Google Kubernetes Engine (GKE) ユーザー - GKE には厳密なロール権限があり、kube-state-metrics ロールとロール バインディングが作成されなくなります。これを回避するには、次のワンライナーを実行して、GCP ID にクラスター管理者のロールを付与します。
kubectl create clusterrolebinding cluster-admin-binding --clusterrole=cluster-admin --user=$(gcloud info --format='value(config.account)')
GCP ID では大文字と小文字が区別されますが、Google Cloud SDK 221.0.0 のgcloud infoでは大文字と小文字が区別されないことに注意してください。これは、IAM メンバーに大文字が含まれている場合、上記のワンライナーは機能しない可能性があることを意味します。上記のコマンドとkubectl apply -f examples/standard実行した後に 403 禁止された応答が返された場合は、https://console.cloud.google.com/iam-admin/iam?project=PROJECT_ID でアカウントに関連付けられている IAM メンバーを確認してください。 。大文字が含まれている場合は、上記のコマンドの --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 を返します。 liveness プローブにはこれを使用することをお勧めします。
/readyz ( selfで公開): アプリケーションがリクエストを受け入れてメトリクスを公開する準備ができている場合は、ステータス コード 200 を返します。これを Readiness Probe に使用することをお勧めします。
説明データをプロキシする場合、プローブにテレメトリ メトリクス エンドポイントを使用することは推奨されないことに注意してください。
クラスターリーダーの役割を持たない環境で kube-state-metrics を実行する場合は、次のことができます。
サービスアカウントを作成する
apiVersion: v1kind: ServiceAccountmetadata: name: kube-state-metrics 名前空間: kube-state-metrics がデプロイされる名前空間
特定の名前空間に対するview権限を付与します (roleBinding を使用) (注: この roleBinding は、サービス アカウントにアクセスさせたいすべての NS に追加できます)
apiVersion: rbac.authorization.k8s.io/v1kind:RoleBindingmetadata:name:kube-state-metrics 名前空間: project1roleRef: apiGroup: rbac.authorization.k8s.io 種類: ClusterRole 名前: ビュー件名: - 種類: サービスアカウント名: kube-state-metrics 名前空間: kube-state-metrics がデプロイされる名前空間
次に、サービスアカウントがkube-state-metricsデプロイメント構成でアクセスできる名前空間のセット ( --namespacesオプションを使用) と kubernetes オブジェクトのセット ( --resourcesを使用) を指定します。
仕様: テンプレート:仕様: コンテナ:
- 名前: kube-state-metricsargs:
- '--resources=pods' - '--namespaces=project1'使用可能な引数の完全なリストについては、docs/developer/cli-arguments.md のドキュメントを参照してください。
kube-state-metrics chart v2.13.3 (kube-state-metrics image v1.9.8 ) 以降、公式 Helm チャートは prometheus-community/helm-charts で維持されます。 kube-state-metrics chart 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 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 分 (隔週 - 定期会議と交互)。自分のタイムゾーンに変換します。
