Skip to main content

ServiceMonitorのYAMLは合ってる。K3sでPrometheusにターゲットが出てこない『接続点』の診断手順

ServiceMonitorのYAMLを書いてapplyしたのに、Prometheusの管理画面を開いてTargetsを見ると「0/0 up」のまま何も出てこない。kubernetes service monitorを検索してKubernetes公式のマニフェスト例を丸写しにしたはずなのに、メトリクスが一向に取れない――。K3s上でPrometheus Operatorを運用しているインフラエンジニアなら、一度はこの壁にぶつかったことがあるはずだ。

この詰まり方には共通点がある。ServiceMonitorという1枚のYAMLは、実は「Prometheus CR → ServiceMonitor → Service → Endpoints → Pod」という4つの接続点をすべて正しく通過して初めて機能する。どこか1箇所でも断絶していれば、エラーメッセージすら出ないまま静かに失敗する。本記事では、この4つの接続点を実際に疑うべき順番で解説し、K3s環境での監視運用を根本から見直す。

1. なぜ「YAMLは合っている」のに動かないのか

section01

ServiceMonitorはKubernetesの標準リソースではなく、Prometheus Operatorが独自に追加するカスタムリソース定義(CRD)だ。そのためkubectl applyが成功したからといって、Prometheus本体がそのServiceMonitorを認識しているとは限らない。

Prometheusは基本的に「pull型」でメトリクスを収集する仕組みを採用しており、ターゲットはサービスディスカバリーまたは静的設定によって発見される(Prometheus公式ドキュメント)。ServiceMonitorはこのターゲット発見の設定を、Kubernetesのラベルを介して宣言的に行うための仕組みにすぎない。つまり「ラベルが正しく伝播しているか」がすべての鍵を握っている。

この構造は、フロントエンドからバックエンド、データベースへとリクエストが渡っていく多層アーキテクチャの障害対応と似ている。個々の設定は正しくても、層をまたぐ「接続点」を1つずつ確認しなければ、どこで処理が止まっているのか特定できない。ServiceMonitorのトラブルシューティングも同様に、以下の4つの接続点を順に疑っていく必要がある。

2. 接続点1: Prometheus CRのserviceMonitorSelector

section02

最初に疑うべきは、Prometheus CRDそのものの設定だ。Prometheusオブジェクトは、どのServiceMonitorを対象にするかをspec.serviceMonitorSelectorフィールドで定義する(Prometheus Operator公式ドキュメント)。

このセレクタが空(すべて選択)になっていない限り、ServiceMonitor側に対応するラベルが付与されていなければ、Prometheus Operatorはそのリソースの存在にすら気づかない。実際、Prometheus Operatorの公式トラブルシューティングガイドでも「ServiceMonitorが実際にPrometheusの設定(prometheus-<name>という名前のSecretに保存される)に含まれているかどうかをまず確認すべき」と明記されている(prometheus-operator.dev トラブルシューティングガイド)。

診断コマンドの例:

bash
kubectl get prometheus -n monitoring -o jsonpath='{.items[0].spec.serviceMonitorSelector}'
kubectl get servicemonitor -A --show-labels

serviceMonitorNamespaceSelectorも併せて確認したい。ServiceMonitorが監視対象と異なるnamespaceに配置されている場合、この設定が範囲を絞り込みすぎていると、ラベルが一致していてもスコープ外として無視される。

3. 接続点2: ServiceMonitorのselectorとServiceのラベル

section03

接続点1をクリアしても、次にServiceMonitor自体が正しいServiceを指し示しているかを確認する必要がある。ServiceMonitorのspec.selectorは、監視対象となるServiceオブジェクトをラベルで選択する仕組みだ。公式ドキュメントでは「app: example-appというラベルを持つすべてのServiceオブジェクトを選択するServiceMonitor」という例が示されている(前掲、getting-startedガイド)。

ここでの典型的な事故は、ServiceMonitorをコピー&ペーストして作った際に、matchLabelsの値だけを書き換え忘れるケースだ。以下のように突き合わせて確認する。

bash
kubectl get svc <service-name> -n <namespace> --show-labels
kubectl get servicemonitor <name> -n <namespace> -o yaml | grep -A5 selector

両者のラベルキー・バリューが完全一致していることを確認したら、次の層に進む。

4. 接続点3: ポート名の不一致という見落としがちな罠

section04

ここが最もハマりやすいポイントだ。Kubernetesの仕様上、Serviceのポートに名前(nameフィールド)を付けるかどうかは任意である。しかしServiceMonitorは、ポート番号ではなくポート名だけを参照する仕様になっている(前掲、prometheus-operator.dev トラブルシューティングガイド)。

Kubernetes公式ドキュメントが示す名前付きポートの仕組みは次の通りだ(Kubernetes公式: Service)。

yaml
# Service側
ports:
  - name: metrics
    port: 9090
    targetPort: metrics
---
# ServiceMonitor側
endpoints:
  - port: metrics   # ポート番号ではなく名前を指定

この仕組みは、将来的にPodが公開するポート番号を変更してもクライアント側の設定を壊さないための柔軟性として設計されている(前掲、Kubernetes公式: Service)。しかし裏を返せば、Service側でポート名を付け忘れている、あるいはServiceMonitor側でポート番号(9090のような数値)をそのまま書いてしまうと、一見正しく見える設定でも静かに失敗する。

5. 接続点4: namespaceSelectorとRBAC、見えない権限の壁

section05

ラベルもポート名も一致しているのに、まだメトリクスが取れない場合に残るのが権限の壁だ。Prometheus ServiceAccountに対象namespaceのservices・endpointsを取得する権限(get, list, watch)が付与されていないと、ラベルセレクタが完全一致していても静かに失敗する。これはPrometheus Operatorの公式トラブルシューティングガイドでも「一般的な問題」として明記されている項目だ(prometheus-operator/prometheus-operator トラブルシューティングガイド)。

Kubernetes公式のRBACドキュメントによれば、ClusterRoleでこれらの権限を付与する基本構造は以下の通りだ(Kubernetes公式: RBAC)。

yaml
apiGroups: [""]
resources: ["services", "endpoints", "pods"]
verbs: ["get", "list", "watch"]

kube-prometheus-stack等のHelmチャートを使っていれば通常この設定は自動生成されるが、複数namespaceにまたがる監視対象を後から追加した場合や、独自にRBACをカスタマイズしている環境では見落としやすい。kubectl get eventsで権限拒否のイベントが出ていないか確認するのも有効だ。

さらにK3s特有の注意点もある。K3sはRKE2やkubeadmベースの構成と異なり、etcdやTraefikのメトリクスをデフォルトでは公開しない構成になっている(Rancher公式ドキュメント: How Monitoring Works)。「ServiceMonitorの設定は正しいのに、そもそもそのコンポーネントがメトリクスエンドポイントを持っていない」というK3s特有の詰まり方も、この段階で切り分けておきたい。

まとめ ― 診断コストを毎回払うか、標準搭載に任せるか

section06

改めて、診断の順番を整理する。

  1. Prometheus CRのserviceMonitorSelector/serviceMonitorNamespaceSelectorがServiceMonitorのラベル・namespaceと一致しているか
  2. ServiceMonitorのspec.selectorがServiceのラベルと一致しているか
  3. spec.endpoints[].portがService側で明示的に付けたポート名を参照しているか(ポート番号ではない)
  4. Prometheus ServiceAccountに対象namespaceのservices/endpoints取得権限があるか、K3s特有の未公開メトリクスでないか

Prometheusは38に上るCNCF卒業プロジェクト(2026年8月時点)の中でも中核を担う、成熟した観測基盤だ(CNCF公式: Prometheus)。仕組み自体は枯れているからこそ、動かない原因は「宣言的な設定の接続点」のどこかに必ず存在する。焦って再作成を繰り返す前に、この4段階を機械的に潰していくことが最短ルートになる。ServiceMonitorが動かない原因の9割は、この4つの接続点のどこかにある。1つずつ機械的に確認していけば、原因不明の詰まりは着実に減らせる。

とはいえ、この診断コストそのものがK3s運用の隠れた負荷であることも事実だ。クラスタを増やすたびに同じチェックリストを繰り返すのは、決して生産的な作業とは言えない。KuboのK3sベースのマネージドクラスタには、Prometheus + Grafanaによる監視スタックが標準搭載されており、ServiceMonitorの配線をゼロから組み上げる必要がない。

EKSやAKSの月額費用の6割以下という価格帯で、この種の「接続点の断絶」に消耗する時間そのものを削減できるのがKubo Cloudの価値提案だ。毎回この診断フローを手作業で回すか、月額48,000円〜で監視基盤ごと標準搭載されたマネージドK3sに任せるか。運用チームの時間をどこに使うかという選択として、一度検討してみる価値はあるはずだ。

自社のセキュリティ要件でオンプレミス運用が必要な場合も、Kubo On-Premiseであれば同様の監視スタックを閉域環境に構築できる。データ主権を保ちながら、この記事で解説した接続点の複雑さをKubo側に任せるという選択肢も含めて、お問い合わせから相談してみてほしい。

Related articles

← Back to all posts