複数拠点のK3sノードを1台落としたのに、中央のGrafanaはまだ「稼働中」のままだった
工場や店舗にK3sクラスタを複数拠点展開し、メトリクスを中央のPrometheus/Grafanaに集約する——このような構成は、K3sが無人・リソース制約のあるリモート環境向けに設計された本番運用可能なKubernetesディストリビューションであることからも分かる通り、エッジ運用の定番パターンになりつつある。
ところが、拠点側のPrometheusをAgent modeで動かしていると、ノードを意図的に落としたりネットワークが切れたりした後も、中央のダッシュボードに「最後に取得した値」がそのまま残り続け、まるで今も稼働しているように見えてしまうことがある。障害対応の初動で「ダッシュボードは緑なのに、現地に電話したら本当に落ちていた」という事態になりかねない。
この記事では、K3s Prometheus Agent modeを拠点側の監視エージェントとして使う際に実際に起きる、ターゲット消失時のメトリクス表示の罠と、その設計上の対処法を解説する。なお、KuboのようなK3sベースのマネージドKubernetesでは、Prometheus + Grafanaの監視スタックが標準搭載されており、ここで紹介する落とし穴の多くがあらかじめ考慮された構成になっている。
Agent modeは「スクレイプしてそのまま転送するだけ」の軽量モードではなかった
K3sのようなリソース制約環境にPrometheusをそのまま置くと、ローカルのTSDB（時系列データベース）やクエリエンジン、アラート評価の分だけメモリとディスクを消費する。これを避けるために用意されているのが Prometheus の Agent mode だ。
Prometheus公式ドキュメントによれば、Agent modeはスクレイピングとリモート書き込みに特化した専用の運用モードで、通常のTSDBクエリ・記録ルール・アラート評価機能を無効化している。カスタマイズされたWAL（Write-Ahead Log）を使い、リモート書き込みが成功した時点でデータを即座に削除する仕組みのため、メモリ上にチャンクを構築したりクエリ用インデックスを持ったりする必要がなく、通常のPrometheusサーバーに比べて大幅にリソース消費を抑えられる。
Prometheus公式ブログの紹介記事でも、エッジクラスタや一時的なKubernetesクラスタのようなリソースが限られた環境で、監視データを中央に集約する必要性の高まりがAgent mode開発の背景にあると説明されている。K3s自体も、単一バイナリかつメモリ消費を抑えた設計でRaspberry Piのような低スペック機器でも動作することを前提に作られており、拠点側の監視エージェントにも同じ省リソース志向が求められる。
ただし注意点もある。公式ドキュメントでは、リモートエンドポイントに到達できない場合のディスクバッファは2時間分に限定されていると明記されている。長時間のネットワーク断が起きる拠点では、この制限がデータ欠損に直結する。
ターゲットが消えた時に送られる「stale marker」という仕組み
ここからが本題だ。K3sのエッジノードは、クラウド上の標準的なクラスタに比べて「消える」頻度が高い。ノードの再起動、Spot的な運用、ネットワーク瞬断——これらが起きるたびに、Prometheusのスクレイプ対象（ターゲット）が一時的、あるいは完全に消失する。
Prometheus Remote Writeのプロトコルには、この状況に対応する仕組みがある。Prometheus公式のRemote Write仕様書では、「時系列にこれ以上データが追加されなくなる場合、送信側は陳腐化マーカー（stale marker）を送信しなければならない」と定義されている。これは特別なNaN値（0x7ff0000000000002）として信号化され、他の目的には使用してはならない予約値だ。マーカーが送られる契機としては、サービスディスカバリでターゲットが消失したことを検知した場合や、連続するスクレイプ間で対象の時系列が公開されなくなった場合などが挙げられている。
つまり、ターゲットが正しく消失したことがstale markerとして中央のリモートストレージ側に伝わっていれば、「このシリーズはもう更新されない」と判断でき、ダッシュボードは適切に「データなし」として扱われる。逆に、ネットワーク瞬断でAgentプロセス自体が応答を返せないまま停止したり、ディスクバッファの2時間制限を超えてしまったりすると、stale markerそのものが届かず、リモート側には「最後に受け取った正常値」が残り続ける。見た目には「緑のまま動いている」グラフとして表示され、実際には何も計測されていない——これが冒頭で紹介した事象の正体だ。
K3sのエッジクラスタ自体も、/metricsエンドポイントでクラスタ管理・ワークキュー・ノードコンポーネントなど多岐にわたるメトリクスを単一のエンドポイントに集約しているため、このエンドポイントへの到達性そのものが、拠点の死活監視における重要なシグナルになる。stale markerの挙動を理解せずにAgent modeを導入すると、肝心の「拠点が落ちたこと」を検知する仕組みが機能しなくなるリスクがある。
複数拠点のK3sエッジでAgent modeを使う際の設計チェックリスト
実際にK3sエッジでPrometheus Agent modeを複数拠点展開する際は、最低限以下の3点を設計段階で確認しておきたい。
1. どの拠点のクラスタか、ラベルで識別できているか
複数拠点から同じリモートストレージへ書き込む構成では、どのメトリクスがどの拠点由来かを区別できなければ、障害時の切り分けができない。Grafanaの公式ドキュメントでは、external_labelsでクラスタ単位のラベルをメトリクスに付与する方法と、X-Scope-OrgIDのようなHTTPヘッダでテナント単位の振り分けを行う方法が紹介されている。拠点数が増える前提のエッジ構成では、拠点ID相当のラベルをexternal_labelsで必ず持たせておくべきだ。
# K3sエッジ側 Prometheus Agent mode 設定例（抜粋）
global:
external_labels:
site_id: "factory-osaka-03"
cluster: "k3s-edge"
remote_write:
- url: "https://central-prometheus.example.com/api/v1/write"
2. stale markerが無効化されていないか
リソース削減のためにstale marker送信を無効化できる設定が存在する実装もあるが、エッジのように拠点が頻繁に入れ替わる環境ではこれを無効化すべきではない。「データが来なくなったこと」自体が重要な障害シグナルであり、これを握りつぶすと、冒頭のような「見た目は稼働中」問題が常態化する。
3. ネットワーク断の最大想定時間に対して、バッファは十分か
前述の通り、Agent modeのディスクバッファは2時間分に制限されている。工場の夜間メンテナンスでネットワークが長時間切れるような拠点では、2時間を超えるとデータが失われる前提で、障害復旧後の再送に頼らない設計（例えば復旧直後のアラート抑制期間を設ける等）を検討する必要がある。
この3点は、拠点数が増えるほど1つずつ手作業で確認するのが難しくなる。Kubo CloudのCaptain UIのように、クラスタごとの設定・ラベル付けの状態を一覧で可視化できる管理画面があれば、どの拠点でラベルが抜けているか、stale marker設定が揃っているかをまとめて把握しやすくなる。
まとめ：Agent modeは「軽量な置き換え」ではなく「挙動の違うコンポーネント」として扱う
Prometheus Agent modeは、K3sのようなリソース制約のあるエッジクラスタで監視コストを抑えるための有効な選択肢だ。2018年にKubernetesに次いでCNCFのGraduatedプロジェクトに昇格したPrometheusのエコシステムの一部として、エッジ向けの軽量な転送モードが用意されていること自体は心強い。
しかし「軽量版だから単純」というわけではない。ターゲット消失時のstale markerの挙動、2時間というディスクバッファの制限、複数拠点を識別するラベル設計——これらを理解せずに導入すると、「監視しているつもりで、実は何も見えていなかった」という状態に陥る。
こうした細かな設計をすべて自前で詰めていく運用コストは、拠点数が増えるほど無視できなくなる。KuboはK3sベースのマネージドKubernetesとして、Prometheus + Grafanaの監視スタックを標準搭載しており、こうした落とし穴を踏まえた構成をあらかじめ組み込める点が強みだ。自前でAgent mode・stale marker・ラベル設計を一つひとつ詰めていく前に、標準でこれらが考慮された構成から始めるという選択肢もある。
製造業DXなどでエッジ拠点を多数抱える場合、Kubo On-Premiseであれば、データを外に出せない制約を抱えたまま、拠点側のK3sクラスタと監視基盤をセットで運用できる。自社の拠点展開計画と照らし合わせて検討したい場合は、お問い合わせから相談できる。