[{"data":1,"prerenderedAt":412},["ShallowReactive",2],{"blog-ja-k3s-prometheus-agent-mode-stale-marker-edge-monitoring":3,"blog-related-ja-k3s-prometheus-agent-mode-stale-marker-edge-monitoring":364,"blog-ja-k3s-prometheus-agent-mode-stale-marker-edge-monitoring-alt":353},{"id":4,"title":5,"author":6,"body":7,"date":347,"description":348,"extension":349,"image":350,"locale":351,"meta":352,"navigation":353,"path":354,"seo":355,"stem":356,"tags":357,"__hash__":363},"blog\u002Fblog\u002Fja\u002Fk3s-prometheus-agent-mode-stale-marker-edge-monitoring.md","K3sエッジのPrometheusをAgent modeにしたら、ターゲットが消えた瞬間にメトリクスも消えていた","Kubo Team",{"type":8,"value":9,"toc":336},"minimark",[10,15,27,35,48,55,59,65,73,87,94,98,101,115,118,130,136,140,143,148,168,266,270,273,277,280,288,294,298,307,310,317,332],[11,12,14],"h2",{"id":13},"複数拠点のk3sノードを1台落としたのに中央のgrafanaはまだ稼働中のままだった","複数拠点のK3sノードを1台落としたのに、中央のGrafanaはまだ「稼働中」のままだった",[16,17,18,19,26],"p",{},"工場や店舗にK3sクラスタを複数拠点展開し、メトリクスを中央のPrometheus\u002FGrafanaに集約する——このような構成は、",[20,21,25],"a",{"href":22,"rel":23},"https:\u002F\u002Fk3s.io\u002F",[24],"nofollow","K3sが無人・リソース制約のあるリモート環境向けに設計された本番運用可能なKubernetesディストリビューションである","ことからも分かる通り、エッジ運用の定番パターンになりつつある。",[16,28,29,30,34],{},"ところが、拠点側のPrometheusを",[31,32,33],"strong",{},"Agent mode","で動かしていると、ノードを意図的に落としたりネットワークが切れたりした後も、中央のダッシュボードに「最後に取得した値」がそのまま残り続け、まるで今も稼働しているように見えてしまうことがある。障害対応の初動で「ダッシュボードは緑なのに、現地に電話したら本当に落ちていた」という事態になりかねない。",[16,36,37,38,41,42,47],{},"この記事では、",[31,39,40],{},"K3s Prometheus Agent mode","を拠点側の監視エージェントとして使う際に実際に起きる、ターゲット消失時のメトリクス表示の罠と、その設計上の対処法を解説する。なお、",[20,43,46],{"href":44,"rel":45},"https:\u002F\u002Fkubo.hexabase.io\u002F",[24],"Kubo","のようなK3sベースのマネージドKubernetesでは、Prometheus + Grafanaの監視スタックが標準搭載されており、ここで紹介する落とし穴の多くがあらかじめ考慮された構成になっている。",[16,49,50],{},[51,52],"img",{"alt":53,"src":54},"section01","https:\u002F\u002Fcdn.kubo.hexabase.io\u002Fimages\u002Fblog\u002Fja\u002Fk3s-prometheus-agent-mode-stale-marker-edge-monitoring\u002Fsection01.webp",[11,56,58],{"id":57},"agent-modeはスクレイプしてそのまま転送するだけの軽量モードではなかった","Agent modeは「スクレイプしてそのまま転送するだけ」の軽量モードではなかった",[16,60,61,62,64],{},"K3sのようなリソース制約環境にPrometheusをそのまま置くと、ローカルのTSDB（時系列データベース）やクエリエンジン、アラート評価の分だけメモリとディスクを消費する。これを避けるために用意されているのが Prometheus の ",[31,63,33],{}," だ。",[16,66,67,72],{},[20,68,71],{"href":69,"rel":70},"https:\u002F\u002Fprometheus.io\u002Fdocs\u002Fprometheus\u002F3.9\u002Fprometheus_agent\u002F",[24],"Prometheus公式ドキュメント","によれば、Agent modeはスクレイピングとリモート書き込みに特化した専用の運用モードで、通常のTSDBクエリ・記録ルール・アラート評価機能を無効化している。カスタマイズされたWAL（Write-Ahead Log）を使い、リモート書き込みが成功した時点でデータを即座に削除する仕組みのため、メモリ上にチャンクを構築したりクエリ用インデックスを持ったりする必要がなく、通常のPrometheusサーバーに比べて大幅にリソース消費を抑えられる。",[16,74,75,80,81,86],{},[20,76,79],{"href":77,"rel":78},"https:\u002F\u002Fprometheus.io\u002Fblog\u002F2021\u002F11\u002F16\u002Fagent\u002F",[24],"Prometheus公式ブログの紹介記事","でも、エッジクラスタや一時的なKubernetesクラスタのようなリソースが限られた環境で、監視データを中央に集約する必要性の高まりがAgent mode開発の背景にあると説明されている。K3s自体も、",[20,82,85],{"href":83,"rel":84},"https:\u002F\u002Fmattermost.com\u002Fblog\u002Fintro-to-k3s-lightweight-kubernetes\u002F",[24],"単一バイナリかつメモリ消費を抑えた設計でRaspberry Piのような低スペック機器でも動作する","ことを前提に作られており、拠点側の監視エージェントにも同じ省リソース志向が求められる。",[16,88,89,90,93],{},"ただし注意点もある。公式ドキュメントでは、リモートエンドポイントに到達できない場合のディスクバッファは",[31,91,92],{},"2時間分に限定","されていると明記されている。長時間のネットワーク断が起きる拠点では、この制限がデータ欠損に直結する。",[11,95,97],{"id":96},"ターゲットが消えた時に送られるstale-markerという仕組み","ターゲットが消えた時に送られる「stale marker」という仕組み",[16,99,100],{},"ここからが本題だ。K3sのエッジノードは、クラウド上の標準的なクラスタに比べて「消える」頻度が高い。ノードの再起動、Spot的な運用、ネットワーク瞬断——これらが起きるたびに、Prometheusのスクレイプ対象（ターゲット）が一時的、あるいは完全に消失する。",[16,102,103,104,109,110,114],{},"Prometheus Remote Writeのプロトコルには、この状況に対応する仕組みがある。",[20,105,108],{"href":106,"rel":107},"https:\u002F\u002Fprometheus.io\u002Fdocs\u002Fspecs\u002Fremote_write_spec\u002F",[24],"Prometheus公式のRemote Write仕様書","では、「時系列にこれ以上データが追加されなくなる場合、送信側は陳腐化マーカー（stale marker）を送信しなければならない」と定義されている。これは特別なNaN値（",[111,112,113],"code",{},"0x7ff0000000000002","）として信号化され、他の目的には使用してはならない予約値だ。マーカーが送られる契機としては、サービスディスカバリでターゲットが消失したことを検知した場合や、連続するスクレイプ間で対象の時系列が公開されなくなった場合などが挙げられている。",[16,116,117],{},"つまり、ターゲットが正しく消失したことがstale markerとして中央のリモートストレージ側に伝わっていれば、「このシリーズはもう更新されない」と判断でき、ダッシュボードは適切に「データなし」として扱われる。逆に、ネットワーク瞬断でAgentプロセス自体が応答を返せないまま停止したり、ディスクバッファの2時間制限を超えてしまったりすると、stale markerそのものが届かず、リモート側には「最後に受け取った正常値」が残り続ける。見た目には「緑のまま動いている」グラフとして表示され、実際には何も計測されていない——これが冒頭で紹介した事象の正体だ。",[16,119,120,121,129],{},"K3sのエッジクラスタ自体も、",[20,122,125,128],{"href":123,"rel":124},"https:\u002F\u002Fdocumentation.suse.com\u002Fen-us\u002Fcloudnative\u002Fk3s\u002Flatest\u002Fes\u002Freference\u002Fmetrics.html",[24],[111,126,127],{},"\u002Fmetrics","エンドポイントでクラスタ管理・ワークキュー・ノードコンポーネントなど多岐にわたるメトリクスを単一のエンドポイントに集約している","ため、このエンドポイントへの到達性そのものが、拠点の死活監視における重要なシグナルになる。stale markerの挙動を理解せずにAgent modeを導入すると、肝心の「拠点が落ちたこと」を検知する仕組みが機能しなくなるリスクがある。",[16,131,132],{},[51,133],{"alt":134,"src":135},"section02","https:\u002F\u002Fcdn.kubo.hexabase.io\u002Fimages\u002Fblog\u002Fja\u002Fk3s-prometheus-agent-mode-stale-marker-edge-monitoring\u002Fsection02.webp",[11,137,139],{"id":138},"複数拠点のk3sエッジでagent-modeを使う際の設計チェックリスト","複数拠点のK3sエッジでAgent modeを使う際の設計チェックリスト",[16,141,142],{},"実際にK3sエッジでPrometheus Agent modeを複数拠点展開する際は、最低限以下の3点を設計段階で確認しておきたい。",[144,145,147],"h3",{"id":146},"_1-どの拠点のクラスタかラベルで識別できているか","1. どの拠点のクラスタか、ラベルで識別できているか",[16,149,150,151,156,157,160,161,164,165,167],{},"複数拠点から同じリモートストレージへ書き込む構成では、どのメトリクスがどの拠点由来かを区別できなければ、障害時の切り分けができない。",[20,152,155],{"href":153,"rel":154},"https:\u002F\u002Fgrafana.com\u002Fdocs\u002Fgrafana-cloud\u002Fsend-data\u002Falloy\u002Freference\u002Fcomponents\u002Fprometheus\u002Fprometheus.remote_write\u002F",[24],"Grafanaの公式ドキュメント","では、",[111,158,159],{},"external_labels","でクラスタ単位のラベルをメトリクスに付与する方法と、",[111,162,163],{},"X-Scope-OrgID","のようなHTTPヘッダでテナント単位の振り分けを行う方法が紹介されている。拠点数が増える前提のエッジ構成では、拠点ID相当のラベルを",[111,166,159],{},"で必ず持たせておくべきだ。",[169,170,175],"pre",{"className":171,"code":172,"language":173,"meta":174,"style":174},"language-yaml shiki shiki-themes tokyo-night","# K3sエッジ側 Prometheus Agent mode 設定例（抜粋）\nglobal:\n  external_labels:\n    site_id: \"factory-osaka-03\"\n    cluster: \"k3s-edge\"\nremote_write:\n  - url: \"https:\u002F\u002Fcentral-prometheus.example.com\u002Fapi\u002Fv1\u002Fwrite\"\n","yaml","",[111,176,177,186,197,205,224,239,247],{"__ignoreMap":174},[178,179,182],"span",{"class":180,"line":181},"line",1,[178,183,185],{"class":184},"sbD-w","# K3sエッジ側 Prometheus Agent mode 設定例（抜粋）\n",[178,187,189,193],{"class":180,"line":188},2,[178,190,192],{"class":191},"s0U2E","global",[178,194,196],{"class":195},"sAklC",":\n",[178,198,200,203],{"class":180,"line":199},3,[178,201,202],{"class":191},"  external_labels",[178,204,196],{"class":195},[178,206,208,211,214,217,221],{"class":180,"line":207},4,[178,209,210],{"class":191},"    site_id",[178,212,213],{"class":195},":",[178,215,216],{"class":195}," \"",[178,218,220],{"class":219},"sPY7s","factory-osaka-03",[178,222,223],{"class":195},"\"\n",[178,225,227,230,232,234,237],{"class":180,"line":226},5,[178,228,229],{"class":191},"    cluster",[178,231,213],{"class":195},[178,233,216],{"class":195},[178,235,236],{"class":219},"k3s-edge",[178,238,223],{"class":195},[178,240,242,245],{"class":180,"line":241},6,[178,243,244],{"class":191},"remote_write",[178,246,196],{"class":195},[178,248,250,254,257,259,261,264],{"class":180,"line":249},7,[178,251,253],{"class":252},"sgJMe","  -",[178,255,256],{"class":191}," url",[178,258,213],{"class":195},[178,260,216],{"class":195},[178,262,263],{"class":219},"https:\u002F\u002Fcentral-prometheus.example.com\u002Fapi\u002Fv1\u002Fwrite",[178,265,223],{"class":195},[144,267,269],{"id":268},"_2-stale-markerが無効化されていないか","2. stale markerが無効化されていないか",[16,271,272],{},"リソース削減のためにstale marker送信を無効化できる設定が存在する実装もあるが、エッジのように拠点が頻繁に入れ替わる環境ではこれを無効化すべきではない。「データが来なくなったこと」自体が重要な障害シグナルであり、これを握りつぶすと、冒頭のような「見た目は稼働中」問題が常態化する。",[144,274,276],{"id":275},"_3-ネットワーク断の最大想定時間に対してバッファは十分か","3. ネットワーク断の最大想定時間に対して、バッファは十分か",[16,278,279],{},"前述の通り、Agent modeのディスクバッファは2時間分に制限されている。工場の夜間メンテナンスでネットワークが長時間切れるような拠点では、2時間を超えるとデータが失われる前提で、障害復旧後の再送に頼らない設計（例えば復旧直後のアラート抑制期間を設ける等）を検討する必要がある。",[16,281,282,283,287],{},"この3点は、拠点数が増えるほど1つずつ手作業で確認するのが難しくなる。",[20,284,286],{"href":44,"rel":285},[24],"Kubo Cloud","のCaptain UIのように、クラスタごとの設定・ラベル付けの状態を一覧で可視化できる管理画面があれば、どの拠点でラベルが抜けているか、stale marker設定が揃っているかをまとめて把握しやすくなる。",[16,289,290],{},[51,291],{"alt":292,"src":293},"section03","https:\u002F\u002Fcdn.kubo.hexabase.io\u002Fimages\u002Fblog\u002Fja\u002Fk3s-prometheus-agent-mode-stale-marker-edge-monitoring\u002Fsection03.webp",[11,295,297],{"id":296},"まとめagent-modeは軽量な置き換えではなく挙動の違うコンポーネントとして扱う","まとめ：Agent modeは「軽量な置き換え」ではなく「挙動の違うコンポーネント」として扱う",[16,299,300,301,306],{},"Prometheus Agent modeは、K3sのようなリソース制約のあるエッジクラスタで監視コストを抑えるための有効な選択肢だ。",[20,302,305],{"href":303,"rel":304},"https:\u002F\u002Fwww.cncf.io\u002Fannouncements\u002F2018\u002F08\u002F09\u002Fprometheus-graduates\u002F",[24],"2018年にKubernetesに次いでCNCFのGraduatedプロジェクトに昇格した","Prometheusのエコシステムの一部として、エッジ向けの軽量な転送モードが用意されていること自体は心強い。",[16,308,309],{},"しかし「軽量版だから単純」というわけではない。ターゲット消失時のstale markerの挙動、2時間というディスクバッファの制限、複数拠点を識別するラベル設計——これらを理解せずに導入すると、「監視しているつもりで、実は何も見えていなかった」という状態に陥る。",[16,311,312,313,316],{},"こうした細かな設計をすべて自前で詰めていく運用コストは、拠点数が増えるほど無視できなくなる。",[20,314,46],{"href":44,"rel":315},[24],"はK3sベースのマネージドKubernetesとして、Prometheus + Grafanaの監視スタックを標準搭載しており、こうした落とし穴を踏まえた構成をあらかじめ組み込める点が強みだ。自前でAgent mode・stale marker・ラベル設計を一つひとつ詰めていく前に、標準でこれらが考慮された構成から始めるという選択肢もある。",[16,318,319,320,325,326,331],{},"製造業DXなどでエッジ拠点を多数抱える場合、",[20,321,324],{"href":322,"rel":323},"https:\u002F\u002Fwww.hexabase.com\u002Fproduct\u002Fkubo\u002Fon-premise",[24],"Kubo On-Premise","であれば、データを外に出せない制約を抱えたまま、拠点側のK3sクラスタと監視基盤をセットで運用できる。自社の拠点展開計画と照らし合わせて検討したい場合は、",[20,327,330],{"href":328,"rel":329},"https:\u002F\u002Fwww.hexabase.com\u002Fcontact-us\u002F",[24],"お問い合わせ","から相談できる。",[333,334,335],"style",{},"html pre.shiki code .sbD-w, html code.shiki .sbD-w{--shiki-default:#51597D;--shiki-default-font-style:italic}html pre.shiki code .s0U2E, html code.shiki .s0U2E{--shiki-default:#F7768E}html pre.shiki code .sAklC, html code.shiki .sAklC{--shiki-default:#89DDFF}html pre.shiki code .sPY7s, html code.shiki .sPY7s{--shiki-default:#9ECE6A}html pre.shiki code .sgJMe, html code.shiki .sgJMe{--shiki-default:#9ABDF5}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"title":174,"searchDepth":188,"depth":188,"links":337},[338,339,340,341,346],{"id":13,"depth":188,"text":14},{"id":57,"depth":188,"text":58},{"id":96,"depth":188,"text":97},{"id":138,"depth":188,"text":139,"children":342},[343,344,345],{"id":146,"depth":199,"text":147},{"id":268,"depth":199,"text":269},{"id":275,"depth":199,"text":276},{"id":296,"depth":188,"text":297},"2026-11-03","K3sエッジクラスタでPrometheus Agent modeを使うと、ターゲット消失時のstale marker処理次第で中央監視に古い値が残り続けることがある。K3s edge環境の監視設計とつまずきポイントを解説する。","md","https:\u002F\u002Fcdn.kubo.hexabase.io\u002Fimages\u002Fblog\u002Fja\u002Fk3s-prometheus-agent-mode-stale-marker-edge-monitoring\u002Ftitle.webp","ja",{},true,"\u002Fblog\u002Fja\u002Fk3s-prometheus-agent-mode-stale-marker-edge-monitoring",{"title":5,"description":348},"blog\u002Fja\u002Fk3s-prometheus-agent-mode-stale-marker-edge-monitoring",[358,359,360,361,362],"k3s","kubernetes","prometheus","edge-computing","observability","E8esq9khQcpoejvgkHCHOT6dCVZ42WNssiqpGdXcUis",[365,373,380,387,395,404],{"path":366,"title":367,"description":368,"date":369,"tags":370},"\u002Fblog\u002Fja\u002Fk3s-servicemonitor-prometheus-not-scraping-connection-points","ServiceMonitorのYAMLは合ってる。K3sでPrometheusにターゲットが出てこない『接続点』の診断手順","K3sでkubernetes service monitorを設定したのにPrometheusのTargetsに何も出てこない。原因の9割はラベルセレクタ・ポート名・RBAC・namespaceSelectorという4つの接続点にある。1段ずつ疑って直す診断手順を解説する。","2026-08-30",[358,359,360,371,372,362],"service-monitor","monitoring",{"path":374,"title":375,"description":376,"date":377,"tags":378},"\u002Fblog\u002Fja\u002Fkubernetes-servicemonitor-silent-metrics-failure","Prometheusは動いている。なのにメトリクスが無い。ServiceMonitorが『静かに』失敗する3つの理由","Kubernetesのkubernetes service monitorが原因不明にスクレイプされない——ラベル不一致・namespaceSelector・RBACという3つの落とし穴を、公式ドキュメントを元に切り分け手順つきで解説する。","2026-08-14",[358,359,360,362,379],"servicemonitor",{"path":381,"title":382,"description":383,"date":384,"tags":385},"\u002Fblog\u002Fja\u002Fedge-k3s-observability-homelab-dashboard","壁に貼っただけで「安心」に変わる。ホームラボの壁掛けダッシュボードが教えてくれた、エッジK3sクラスタの観測性設計","自宅の壁掛けダッシュボード作りで起きた総当たりのトラブルシューティングは、工場や店舗に分散したエッジKubernetesクラスタの運用でも同じ罠になる。K3s・Prometheus・Grafanaの公式ドキュメントを引きながら、観測性を後回しにしないための設計原則を解説する。","2026-07-26",[358,359,361,362,372,386],"managed-kubernetes",{"path":388,"title":389,"description":390,"date":391,"tags":392},"\u002Fblog\u002Fja\u002Fk3s-system-upgrade-controller-plan-stuck-node-drain","Planは消えずに残っていた。K3sのsystem-upgrade-controllerが止まり続けた理由","K3sのsystem-upgrade-controllerで自動アップグレードを組んだら、特定ノードだけPlanが進まなくなった。原因はPodDisruptionBudgetとtaintの盲点。仕組みと復旧手順、Kuboでの解決策を解説する。","2026-10-31",[358,359,393,394,361],"system-upgrade-controller","rolling-upgrade",{"path":396,"title":397,"description":398,"date":399,"tags":400},"\u002Fblog\u002Fja\u002Fk3s-spegel-embedded-registry-mirror-airgap-node-join","K3sの組み込みレジストリミラーが効いているはずなのに、新しいエッジノードだけimage pullに失敗した","K3sの組み込みレジストリミラー（Spegel）はクラスタ全体で有効なはずが、新規追加したエッジノードだけimage pullに失敗した。原因はregistries.yamlの未配布と認証ドリフト、containerd 2.0の既知バグ。エアギャップ運用の正しい配布手順を解説する。","2026-10-30",[358,359,401,402,403,361],"spegel","registry-mirror","airgap",{"path":405,"title":406,"description":407,"date":408,"tags":409},"\u002Fblog\u002Fja\u002Fk3s-microshift-etcd-ostree-edge-comparison","エッジでetcdを固定されるのは罠か前提か。K3sとMicroShift、OSTree自動ロールバックの代償を比較する","K3sとMicroShiftはどちらも「軽量Kubernetes」と語られるが、データストアとOS更新モデルの前提が根本的に違う。etcd固定とOSTree自動ロールバックの実態を比較し、エッジ本番運用でどちらを選ぶべきかを整理する。","2026-10-29",[358,410,359,361,411],"microshift","redhat",1793798694872]