インストール

Yagra は、常駐する 2 つのバイナリと、静的な WebUI でできています。

• Yagra-core — 全体の制御、スケジューリング、ノースバウンドの REST API
• Yagra-poller — 状態を持たない ICMP / SNMP / API のワーカー
• Yagra-web — WebUI。nginx が配信し、/api をコアへリバースプロキシします

このページでは、Yagra をインストールするサポート構成をすべて扱います。1 コマンドで立ち上がる 評価用のマシンから、TLS のバス越しに結果を中央へ送り返すリモート拠点のポーラーまでです。

その背後で、最大 6 つのバックエンドサービスが動きます:

バックエンドサービス	役割	必要とするもの
PostgreSQL	メタデータ: ノード・設定・しきい値・ユーザー・アラート履歴	コア（必須）
NATS（JetStream）	コア⇄ポーラーバス: ジョブ・作業セット・結果・イベント	コア + ポーラー（必須）
VictoriaMetrics	時系列ストア — メトリクス本体	コア（必須）
Redis	一時的なポーラー死活/割当ミラー — 再構築可能	コア（任意）
VictoriaLogs	パッシブイベントのログストア — syslog/トラップの全文検索	コア（任意）
ClickHouse	トラフィックフローストア — NetFlow/IPFIX/sFlow レコード	コア（任意）

ポーラーが接続するのは、NATS だけです。デバイスの認証情報、ジョブの指示、結果は、すべて バスの上を流れます。ポーラーがデータベースに触れることはありません。

この形だからこそ、ポーラーは状態を持たずに済み、台数を増やすだけで規模を広げられます。リモート 拠点の NAT の内側にも置けます。

デプロイ構成の選択

選ぶ軸は 2 つです。単一ノードか分散か、そして Docker かネイティブかです。どれを選ぶ場合 でも、まず動作要件でホストのサイジングを確認してください。

	Docker Compose	ネイティブ（Docker なし）
単一ノード	A — ビルド済みイメージ · B — ソースからビルド	C
分散ポーラー	D	E

まずは A から始めてください。公開イメージを取得するだけで、チェックアウトもビルドも要りません。 単一ノードの構成のなかで、WebUI から自分自身をアップグレードできるのは A だけです。

リモート拠点にポーラーが必要になったら D または E へ進みます。ポーラーは中央のバスへ 外向きに接続します。ですから拠点側に受信ポートを 1 つも開けずに、NAT やファイアウォールを 越えられます。

残る 3 つは対象が限られますが、いずれもサポート対象です。B はソースからビルドする構成です。 Yagra を開発する、監査する、独自ビルドを作る、といった目的に使います。C と E は Docker が 使えないホスト向けで、バイナリを直接動かします。

規模を大きくするのに、作り直しは要りません。設定を変えるだけです。単一ノードでも分散でも、動かす イメージは同じです。リモートポーラーを足し、バスがマシンの外へ出る前に NATS の TLS と認証を 有効にしてください。ジョブのメッセージはデバイスの認証情報を運ぶからです。

高可用性は、この表とは別の話です。同じストア群に対して複数のコアを動かす構成なら、リーダー 選出（YAGRA_ENABLE_HA）を有効にして、コアを自動でフェイルオーバーさせられます。リポジトリの docker-compose.ha.yml は、これを試すためのすぐ使える 2 コア構成です:

docker compose -f docker-compose.yml -f docker-compose.ha.yml up --build

/readyz に 200 を返すのは、常にちょうど 1 つのコア（リーダー）だけです。スタンバイは引き継ぐ まで 503 を返します。引き継ぎは、リーダーが止まってから数秒以内に終わります。API と WebUI の トラフィックは、/readyz を基準に振り分けてください。詳細は 高可用性にあります。

イメージとタグ

3 つのイメージが GitHub Container Registry に公開されています:

ghcr.io/horryworks/yagra-core
ghcr.io/horryworks/yagra-poller
ghcr.io/horryworks/yagra-web

公開されるのはリリースだけです。開発ビルドがレジストリに載ることはないので、下の表のタグは すべてそのまま動かせるリリースです。

タグ	意味	用途
:v<version>	特定のリリース（例 :v0.1.18）	本番 — これを固定
:latest	最新の安定リリース。プレリリース（-beta / -rc）がこれを動かすことはありません	評価、最新への追従
:<git-sha>	あるリリースへの不変の参照	再現可能なデプロイ、ロールバック

Compose ファイルは、YAGRA_IMAGE_TAG（既定は latest）でタグを選びます。アップグレードは、 このタグを変えてコンテナを作り直すだけです。手順は アップグレードとバックアップにあります。元に戻すときも、 より古いタグで同じ操作をするだけです。

ノート

:latest が指すのは「最も新しいバージョン番号」ではありません。「最後に公開された安定リリース」 です。大きなリリースの後に hotfix を切ると、:latest はいったん戻ります。

長く使うつもりの環境では、リリースページにある v<version> タグを固定してください。

A — 単一ノード, Docker（ビルド済みイメージ）

これが推奨するデプロイ構成です。 docker-compose.deploy.yml は、次の 4 つを行います。

• GHCR から公開イメージを取得します。ローカルでのビルドはしません。
• 設定を .env から読みます。
• kek-init サービスを 1 回だけ動かし、永続的なマスタ鍵（KEK）を書き込みます。これで保存済みの 監視認証情報が、再デプロイをまたいでも読めるままになります。
• yagra-updater サイドカーを同梱します。Settings ▸ Upgrade が動くのは、このサイドカーがあるからです。

リポジトリのチェックアウトは要りません。この compose ファイルはこれ 1 つで完結しています。 参照する変数はすべて既定値を持ち、バインドマウントも Docker ソケット以外にはありません。

1. デプロイ用のディレクトリを作り、compose ファイルを取得します:

   mkdir yagra && cd yagra
   curl -fsSL -o docker-compose.deploy.yml \
     https://github.com/horryworks/Yagra/releases/latest/download/docker-compose.deploy.yml

   compose ファイルは main からではなくリリースから取ってください。このファイルと、これが取得する イメージは一体の成果物です。compose 側が、まだ公開されていないイメージにしか無いコマンドや 初期化コンテナを要求することがあります。releases/latest/download/ は最新の安定リリースに 解決され、これは :latest イメージタグの意味と同じなので、両者は必ず一致します。

   ファイルはこの名前のまま、ここに置いておいてください。無停止アップグレードは、自分のコンテナ に付いたラベルからこのディレクトリを読み戻します。そこに docker-compose.deploy.yml が無ければ、 実行を拒否します。

2. .env を作成します。実際に決める必要があるのは、データベースのパスワードだけです。ただし、 それは今決めてください。PostgreSQL は初期化のときに、このパスワードをデータボリュームへ 書き込みます。あとから変えるには、ファイルの編集だけでなく ALTER ROLE の実行も必要になります。

   使う文字は、URL に使えるものだけにしてください。このパスワードは接続 URL に埋め込まれます。 そこで percent-encode はできません。/ @ : ? # を含むパスワードは URL をそこで 終わらせてしまい、コアは起動を拒否します。openssl rand -hex 16 はこれらの文字を生成しません。 openssl rand -base64 は高い確率で / を生成するので、ここでは使わないでください。

   POSTGRES_PASSWORD=change-me            # set this before the first start
   # YAGRA_IMAGE_TAG=v0.2.5               # pin a release for production (default: latest)
   # YAGRA_API_PORT=8080                  # host port for the API (plaintext)
   # YAGRA_WEB_PORT=443                   # host port for the WebUI (HTTPS)
   # YAGRA_ADMIN_PASSWORD=choose-a-strong-password   # else a one-time random one is logged

   それ以外はすべて動作する既定値を持ちます。全変数の一覧: 設定リファレンス。

3. 起動します:

   docker compose -f docker-compose.deploy.yml up -d

   これだけでイメージの取得も行われます。イメージに pull_policy: always が付いているので、 別途 pull する必要も、ビルドもありません。

4. 一度限りの admin パスワードを取得します（YAGRA_ADMIN_PASSWORD を設定した場合は不要です）:

   docker compose -f docker-compose.deploy.yml logs core | grep -i password

   https://localhost で WebUI を開き、admin でサインインして、パスワードを変更してください。 自己署名証明書についてブラウザが警告します。差し替え方は WebUI の TLS に あります。

何が動くか。 コア、ポーラー 1 台、WebUI に加えて、次のものが動きます。

• PostgreSQL、Redis、NATS、VictoriaMetrics
• VictoriaLogs（パッシブイベントの検索用）
• ClickHouse（トラフィックフロー用）
• ipasn-updater サイドカー。オフラインの IP→ASN データセットを最新に保ちます。インターネット へ外向きの通信をするのは、このコンテナだけです。

マイグレーション（データベースの形の変更）は、コアの起動時に自動で走ります。永続データは名前付き ボリュームにあるので、down して up しても残ります。

用途	ホスト既定	変更方法
WebUI（HTTPS）	443	YAGRA_WEB_PORT
REST API + /metrics（平文）	8080	YAGRA_API_PORT
syslog 受信（UDP）	514	YAGRA_SYSLOG_PORT
SNMP トラップ受信（UDP）	162	YAGRA_TRAP_PORT
NetFlow v5/v9 / IPFIX 受信（UDP）	2055	YAGRA_FLOW_PORT
sFlow 受信（UDP。YAGRA_SFLOW_BIND を設定するまでリスナーは無効）	6343	YAGRA_SFLOW_PORT

ストア群は、内部の Docker ネットワークから外に出ません。任意で使う機能は、.env で対応する変数を 空にするとオフになります。たとえば YAGRA_CLICKHOUSE_URL= はフロー監視を、YAGRA_SYSLOG_BIND= は syslog の受信を止めます。全体の一覧は ポートと設定にあります。

デバイスの送信先を設定する。 syslog はホストの :514/udp へ、SNMP トラップ（v1/v2c と inform） は :162/udp へ、NetFlow/IPFIX のエクスポートは :2055/udp へ送ってください。

パッシブイベントは、データグラムの送信元 IP でノードに対応付けられます。お使いのホストで Docker の ブリッジネットワークが送信元アドレスを書き換えてしまう場合は、poller サービスを network_mode: host に切り替えてください。実アドレスがそのまま届くようになります。

確認。 すべてのコンテナが起動していて、コアが応答することを確かめます:

docker compose -f docker-compose.deploy.yml ps
curl -fsS http://localhost:8080/healthz

続いて WebUI の設定 ▸ Yagra ヘルスを開いてください。各ストアに届いているか、そしてサーバー 自身の総合判定が表示されます。

認証情報を残すための鍵（KEK）。 保存される監視認証情報（SNMP コミュニティ、SNMPv3 認証情報、 API トークン）は、マスタ鍵（KEK）で二重に暗号化されます。

kek-init サービスは、32 バイトの KEK を kekdata ボリュームへ一度だけ生成します。以後は決して 上書きしません。コアはそれを読み取り専用でマウントします。

永続的な KEK が無いと、コアは一時鍵に切り替えます。一時鍵は再起動のたびに作り直されます。 つまり再デプロイしたあと、保存済みの認証情報がすべて読めなくなります。

KEK をバックアップする

kekdata ボリュームは決して削除しないでください。そして鍵のコピーを、ホストの外に保管して ください:

docker run --rm -v yagra_kekdata:/kek busybox cat /kek/key > kek-backup.key

KEK を失うと、保存済みの認証情報はすべて永久に読めなくなります。データベースのバックアップから 復元することもできません。

B — 単一ノード, Docker（ソースからビルド）

Yagra のライセンスは AGPL-3.0 です。きれいなチェックアウトからビルドできます。この構成は Yagra を開発する、監査する、独自ビルドを作るためのものです。docker-compose.yml は イメージをローカルでビルドして :dev タグを付け、一式を 1 ホストで動かします:

git clone https://github.com/horryworks/Yagra.git
cd Yagra
docker compose up --build

その後、https://localhost:8443 で WebUI を開きます。コアのログに出力される一度限りの admin パスワードでサインインしてください。

443 ではなく 8443 を使うのには理由があります。ノート PC では 443 が埋まっていることが多く、 さらに rootless Docker は 1024 未満のポートをそもそも公開できません。初回起動時の証明書は自己署名 なので、ブラウザが警告します。詳しくは WebUI の TLS を見てください。

業務で頼るシステムに、この構成を選ぶべきではありません

理由は 2 つあります。どちらも見落としではなく、意図してそうしています。

• 自分自身をアップグレードできません。 この構成には yagra-updater サイドカーがありません。 しかも、ここでビルドする :dev タグは公開もされません。つまり、アップデータが移行できる リリースがそもそも存在しません。Settings ▸ Upgrade は、押しても失敗するボタンを並べず、 使えないことを表示します。
• マスタ鍵（KEK）が残りません。 再起動のたびに作り直されるので、保存した監視認証情報は 再起動をまたげません。取り込んだ TLS 証明書も同じく読めなくなります。その場合 core は、 それをはっきり伝えたうえで、最後の証明書を配り続けます（勝手に差し替えることはしません）。

実運用には A を使ってください。公開イメージ、消えない KEK、そして WebUI からの無停止 アップグレードが揃います。

WebUI の TLS

WebUI は最初から HTTPS です。 うっかり公開してしまう平文のリスナーはありません。

初回起動時、コアは自己署名の証明書を生成します。対象はループバックとコンテナのホスト名です。 ですからブラウザは警告を出しますし、名前が合わないとも言ってきます。コンテナの中からは、実際に 使われるアドレスを知りようがないためです。

対処は、その警告の先にある設定 ▸ TLS 証明書から行います。できることは 2 つです。PEM 形式の 証明書チェーンと秘密鍵を取り込む（貼り付けでもファイル選択でも可）か、実際に使うホスト名や IP アドレスを指定して、自己署名証明書を作り直します。

取り込んだ証明書は、何も再起動せずに数秒で有効になります。使えない証明書は、その場で理由付きで 拒否されます。鍵と証明書が対になっていない、期限が切れている、サブジェクト代替名が無い、といった 場合です。次のハンドシェイクで初めて失敗する、ということはありません。

手前に置いた外部のリバースプロキシやロードバランサが、すでに HTTPS を終端している場合は、.env で YAGRA_WEB_TLS=off を設定してください。

core の API ポートは今も平文

8080 は UI と同じものを運びます。ログインパスワード、Bearer トークン、そして暗号化前のデバイス 認証情報です。そして今も LAN に公開されています。

これは意図した順序です。まず Prometheus の scrape、webhook の送信元、API スクリプトを、信頼できる 証明書のある https://<host>/api/v1/… へ移してください。そのあとで YAGRA_API_BIND=127.0.0.1 を設定し、ポートをネットワークから外します。

同時にやってはいけません。すべての機械クライアントが一斉に失敗し、原因が 2 つ重なって切り分け できなくなります。詳しくはセキュリティを見てください。

C — 単一ノード, ネイティブ

Docker を使わず、バイナリを直接動かす構成です。ストアは自分で用意します。そのあとワークスペースを ビルドし、yagra-core と yagra-poller を（たとえば systemd の）サービスとして動かします。

1. バックエンドストアの用意

次のものをインストールして起動します。いずれも、コアを動かすホストから届く場所に置いてください:

• PostgreSQL 17 — データベースとロールを作ります。コアはマイグレーションを自分で実行します。 ただし、データベース自体を作ることはしません:

  CREATE ROLE yagra LOGIN PASSWORD 'yagra';
  CREATE DATABASE yagra OWNER yagra;

• NATS 2.x（JetStream 有効） — nats-server -js

• VictoriaMetrics — victoria-metrics-prod --retentionPeriod=12（メトリクスを 12 か月保持）

• Redis 7（任意）— ポーラーの死活と割当のミラーを有効にします。無くても起動はできます。 一部の機能が使えなくなるだけです

• VictoriaLogs（任意）— パッシブイベントの全文検索に使います。無い場合、イベントはすべて PostgreSQL に留まります

• ClickHouse 24.x（任意）— トラフィックフローの保管先です。無い場合、フロー監視はオフになり、 フロー API は 503 を返します

2. ワークスペースのビルド

Rust 1.90 と、WebUI 用に Node 22 が必要です。ビルドはリポジトリのルートから行ってください。 ワークスペースが持つ依存パッチ（vendor 済み）を効かせるためです:

git clone https://github.com/horryworks/Yagra.git
cd Yagra
cargo build --release --workspace           # → target/release/yagra-core, target/release/yagra-poller
cd web && npm ci && npm run build           # → web/dist/  (static SPA bundle)

3. KEK の用意（コアの初回起動前に）

二重暗号化に使うマスタ鍵です。中身は 32 バイトのファイルで、消さずに残します。これが無いと、 コアは一時的な dev 鍵で起動します。その場合、保存した認証情報は再起動をまたげません:

sudo install -d -m 0700 /etc/yagra
head -c 32 /dev/urandom | sudo tee /etc/yagra/kek > /dev/null
sudo chmod 0400 /etc/yagra/kek

このファイルをバックアップしてください。失うと、保存済みの認証情報はすべて永久に読めなくなります。

4. コアの起動

export YAGRA_DATABASE_URL="postgres://yagra:yagra@localhost:5432/yagra"
export YAGRA_BUS_URL="nats://localhost:4222"
export YAGRA_TSDB_URL="http://localhost:8428"
export YAGRA_REDIS_URL="redis://localhost:6379"      # optional
export YAGRA_LOGS_URL="http://localhost:9428"        # optional: passive-event log store
export YAGRA_CLICKHOUSE_URL="http://localhost:8123"  # optional: traffic-flow store
export YAGRA_KEK_FILE="/etc/yagra/kek"
export YAGRA_API_ADDR="0.0.0.0:8080"                 # default
# export YAGRA_ADMIN_PASSWORD="choose-a-strong-password"   # else a one-time random one is logged
export RUST_LOG=info

./target/release/yagra-core

起動すると、コアは次の 4 つを行います。ストアへ接続し、マイグレーションを自動実行し、組み込みの プロファイルとカタログを書き込み、YAGRA_API_ADDR 上で /api/v1 と Prometheus の /metrics を 提供します。curl -fsS http://localhost:8080/healthz で確認してください。

YAGRA_ADMIN_PASSWORD を設定していない場合は、一度限りの admin パスワードをログから拾って ください。

必須の URL は 3 つあります。YAGRA_DATABASE_URL、YAGRA_BUS_URL、YAGRA_TSDB_URL です。 1 つでも未設定だと、コアはメモリ上だけで動くスケルトンモードになります。実際のデータは扱いません。

恒久的に動かすときは、同じ環境変数を与えたサービスユニット（systemd など）で包んでください。 コアはいつ再起動しても安全です。全変数の一覧は 設定リファレンスにあります。

5. WebUI の配信

web/dist/ は静的バンドルです。好きな Web サーバーで配信し、/api をコアへリバースプロキシして ください。同梱の nginx 設定（web/nginx.conf）に倣うのが確実です。要点は 2 つあります。SSE （サーバーから随時送られてくる更新）には proxy_buffering off と長い proxy_read_timeout が 要ります。そして SPA には try_files のフォールバックが要ります:

server {
    listen 80;
    root /var/www/yagra;                    # the contents of web/dist/
    index index.html;

    location /api/ {
        proxy_pass http://localhost:8080;   # → core's YAGRA_API_ADDR
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_http_version 1.1;
        proxy_buffering off;                # stream SSE immediately
        proxy_read_timeout 1h;              # keep SSE connections open
    }

    location / {
        try_files $uri $uri/ /index.html;   # SPA client-side routing fallback
    }
}

SPA を別オリジンから配信する場合

本番では、同じオリジンから配信するのが定石です。ブラウザは Web サーバー上の /api/v1/… を呼び、 nginx がそれをコアへプロキシします。この形ならビルド時の設定は要りません。

SPA と API を別々のオリジンから配信する場合は、VITE_API_BASE に API のオリジンを設定して バンドルをビルドしてください。例: VITE_API_BASE=https://core.example.net npm run build。

設定するのはオリジンであって、パスではありません。/api/v1 を付け足さないでください。すべての リクエストパスがすでにそれを含んでいますし、ライブ更新のストリームも同じベースを使います。

6. ポーラーの起動

ポーラーは ICMP を送るために raw ソケットを使います。バイナリに権限を付けて非 root で動かすか、 root で実行してください:

sudo setcap cap_net_raw+ep ./target/release/yagra-poller

export YAGRA_BUS_URL="nats://localhost:4222"
export YAGRA_POLLER_ID="poller-1"          # unique per poller; defaults to hostname
export YAGRA_POLLER_POOL="default"
# Optional intake listeners, each off until bound (binding :514/:162 directly
# would additionally need root or CAP_NET_BIND_SERVICE — these high ports don't):
# export YAGRA_SYSLOG_BIND="0.0.0.0:1514"
# export YAGRA_TRAP_BIND="0.0.0.0:1162"
# export YAGRA_FLOW_BIND="0.0.0.0:2055"
export RUST_LOG=info

./target/release/yagra-poller

ポーラーは自身の Prometheus /metrics を 0.0.0.0:9100 で公開します。

任意: PDF レポート

レポートの PDF エクスポートは wkhtmltopdf（パッチ済みの Qt ビルド）を呼び出します。 インストールしていない場合、PDF エクスポートは HTTP 503（pdf_unavailable）を返します。 HTML と CSV のエクスポートは、そのまま使えます。

D — 分散ポーラー, Docker

中央では A と同じように一式を動かし、リモート拠点にポーラーを足す構成です。

各リモートポーラーは、拠点のデバイスをその場でポーリングし、結果をバス経由で中央へ送り返します。 ノードは pool 属性を持ちます。コアは各プールのノードを、コンシステントハッシュで生きている ポーラーへ割り当てます。ポーラーが落ちれば自動でフェイルオーバーします。しくみと挙動は 分散ポーリングで詳しく説明しています。

バスがマシンを出る前に TLS + 認証を

ジョブのメッセージは、デバイスの認証情報を平文で運びます。1 ホストの中だけなら問題ありません。 バスは内部の Docker ネットワークから出ないからです。

しかしバスがリモート拠点へ出た瞬間から、TLS による暗号化と認証が必須になります。しかも順番が 大事で、出す前に設定してください。NATS の :4222 を平文で公開しては絶対にいけません。

ステップ 1 — 中央スタックで NATS の TLS + 認証を有効化

これは WebUI のスイッチ 1 つで終わります。以前は手作業が 5 つ必要でした。openssl で証明書を作り、 docker-compose.deploy.yml を 2 か所書き換え、全拠点に同じパスワードを配る、という手順です。

1. 設定 ▸ ポーラーを開き、リモートポーラーのパネルを見ます。バスを一度も公開していなければ 内部のみと表示されています。

2. 「リモートポーラーを受け入れる」を押し、リモートポーラーが接続する宛先を入力します。 ホスト名か IP アドレスを、カンマ区切りで書きます。拠点が実際に接続する宛先が載っていないと その拠点は接続できません。使う宛先はすべて挙げてください。

3. 停止を確認します。 バス・このサーバー・ここで動いているポーラーが再起動するため、監視が 1 分ほど止まります。先にデプロイ全体のメンテナンス期間が開くので、通知は出ません。この画面も その間は切断されます。

スイッチ 1 つが、すべてを実施します。入力した宛先でバス証明書を再発行し、TLS とバスのパスワードを 有効化し、バスのポートを公開し、同じ変更で同居するコアとポーラーを tls:// に移します。サーバー 全体を TLS にすると平文のポートが残らないので、最後の部分は省略できません。

その後パネルは暗号化済みになり、証明書の内容が出ます。対応する宛先・有効期限・フィンガー プリントです。拠点の宛先が変わったときは**証明書を再発行…**で作り直します。再接続の前に、新しい ファイルを全拠点へ渡す必要があります。

証明書は Yagra が生成し、PostgreSQL が正本になります。WebUI 自身の証明書と同じ扱いです。秘密鍵は 封筒暗号で、証明書自体は公開物なので平文です。取り込み（インポート）はありません。バス証明書を 信頼する必要があるのは、Yagra 自身が設定するポーラーだけだからです。

NATS の設定は、core ユーザーに全権を与え、poller ユーザーは最小権限にします。結果・イベント・ ハートビートの publish はでき、subscribe できるのはジョブとワーキングセットの割り当てだけです。この 設定ファイルは core イメージに同梱され、バス用ボリュームへ自動で置かれます。

既定では poller アカウントは 1 つを共用します。ステップ 2 でポーラーごとに専用トークンを発行 すると、1 拠点の漏洩が全拠点の鍵であることをやめます。さらに絞るなら — 侵害された拠点が他プールの 割り当てすら読めないように — 同じ Compose ブロックに書いてある Auth Callout を有効にしてください。 詳細はセキュリティにあります。

シェルから設定する場合

WebUI を使えないデプロイでは、同じことを手で設定できます。docker-compose.deploy.yml の nats サービスの上に、必要な変数が書いてあります。YAGRA_NATS_ARGS、YAGRA_NATS_BIND、 YAGRA_NATS_CORE_PASSWORD、YAGRA_NATS_POLLER_PASSWORD、YAGRA_CORE_BUS_URL、 YAGRA_POLLER_BUS_URL、YAGRA_BUS_CA_FILE です。

これらは .env に置きます。.env は無停止アップグレードでも保持されます。以前のリリースでは compose ファイル自体を編集する方式でしたが、設定 ▸ アップグレードはそのファイルを対象イメージの もので入れ直します。つまり編集はアップグレードのたびに消えていて、しかも気づくのはリモート拠点だけ でした。v0.3.11 からは、どうしても Compose で書くしかない変更には残る置き場があります —— docker-compose.local.yml です。アップグレードとバックアップを 参照してください。

NATS の設定では、core ユーザーにすべての権限を与えます。poller ユーザーには最小限だけです。 publish できるのは結果・イベント・ハートビートのみ、subscribe できるのはジョブと作業セットの 割当のみです。

ただし、この poller アカウントは 1 つを全ポーラーで共有します。認証を通ったポーラーなら、 どのプールの割当でも読めてしまいます。ですからテナントの境界にはなりません。

バスの認証情報をポーラーごとに絞りたい場合は、同じ Compose ブロックに書いてある Auth Callout の 手順を有効にしてください。これを使うと、侵害された拠点は自分のプールのデバイス認証情報しか 読めなくなります。詳細はセキュリティにあります。

ステップ 2 — WebUI でポーラーを登録

**設定 ▸ ポーラー ▸「ポーラーを登録」を開きます。変わらない id を付け、担当させたいプールを 割り当てて、「トークンを発行してキットをダウンロード」**を押してください。拠点はまだ存在して いなくてかまいません —— この操作が登録も兼ねます。拠点のマシンに必要なものが、1 つのアーカイブで 落ちてきます:

中身	何が入っているか
.env	このポーラーの id・プール・バス URL・トークン。パーミッションは 0600 です。
certs/server-cert.pem	固定するバス証明書。公開証明書だけで、鍵は入りません。
docker-compose.poller.yml	この core のイメージから取り出したもの。動かしているバージョンと一致します。
README.txt	拠点側の手順と、アーカイブを失くしたときの対処。

トークンは SHA-256 のダイジェストしか保存されません。ですから表示は 1 回きりで、実体はこのアーカイブ の中だけにあり、復元できません。失くしたら新しく発行してください。そのとき古いトークンは無効に なります。

既に接続している拠点なら、同じアーカイブは一覧のその行からも取れます。トークン列を見ると どのポーラーがまだデプロイ全体の共通シークレットを使っているか分かり、トークンを発行して ダウンロードでそのポーラーに専用トークンを渡せます。

ステップ 3 — リモートポーラーの起動

リモート拠点のマシンで、アーカイブを展開して起動します。編集するものはありません:

tar xzf yagra-poller-edge-tokyo-1.tar.gz
docker compose -f docker-compose.poller.yml up -d

Compose が要求するものは、アーカイブの .env がすべて満たします:

YAGRA_BUS_URL=tls://poller:<this poller's token>@core.example.com:4222
YAGRA_POLLER_ID=edge-tokyo-1        # stable, unique per poller
YAGRA_POLLER_POOL=tokyo             # the pool this poller serves
YAGRA_BUS_CA_FILE=/etc/yagra/certs/server-cert.pem

ここでも YAGRA_IMAGE_TAG でイメージを固定してください。場面に応じた追加の設定 — 受信のレート 上限、フローの収集、store-and-forward のバッファ — は、すべて 設定リファレンスにあります。

docker-compose.poller.yml はホストネットワークを使い、付与する権限は NET_RAW だけです。 ホストネットワークを使う理由は 2 つあります。syslog とトラップのノード対応付けは、データグラムの 送信元 IP を手がかりにします（ブリッジの NAT はそれを書き換えてしまいます）。そして raw ソケットの ICMP は、ホストのインターフェースを直接使う必要があります。

ポーラーは起動から数秒以内に設定 ▸ ポーラーに現れます。そこからコアが、そのプールのノードを 割り当て始めます。

1024 未満のポートは使えません

リモートポーラーは非 root で動きます（raw ICMP 用のファイル権限だけを持ちます）。ですから :514 や :162 のような 1024 未満のポートは開けません。

対処は 2 つあります。既定の高いポート（1514 / 1162）を使い、ホストのファイアウォールで 転送する方法です。たとえば iptables -t nat -A PREROUTING -p udp --dport 514 -j REDIRECT --to-ports 1514 と書きます。 もう 1 つは、デバイスの送信先を最初から高いポートに向ける方法です。

知っておくと役に立つ性質:

• プールを増強するには、同じ YAGRA_POLLER_POOL を持つポーラーを足します（YAGRA_POLLER_ID は別々にします）。コアがプールをそれらへ配り直し、1 台失っても他へ引き継ぎます。
• 生きたポーラーが 0 台のプールは、ジョブを 1 件ずつ配る昔のやり方に切り替わります。 入れ替えの最中も、監視が止まるノードはありません。
• WAN が切れても履歴に穴は空きません。 ポーラーはその場でポーリングを続け、結果をためます （まずメモリに保持し、あふれたら pollerbuf ボリュームへ退避します）。つながり直したら 送り直します。メトリクスは元の時刻のまま埋め戻されます。アラートは意図的に埋め戻さず、 「現在」から再開します。
• 拠点でフローを受けるとき: ホストネットワークでは、ポーラーが :2055 を直接開きます。 ですから拠点の NetFlow/IPFIX エクスポーターは、ポーラーへ向けてください。フローは拠点側で 集約され、同じ TLS のバス経由でコアへ送られます。

拠点の回線のサイジング

ポーラーは、受信した元のバイト列をそのままコアへ運びます。転送機能が、デバイスの送信内容を そのまま中継できるようにするためです。

具体的には、パッシブイベントには raw データグラムのコピーが付きます。フローのデータグラムは、 集約した結果に加えて、原本もそのまま中継されます。

リモート拠点にとって、これは実際の WAN トラフィックです。量は拠点の syslog とトラップの多さ、 そしてフローのレートに比例します。目安は 1,000 flows/s あたり 1 メガビット/秒です。

回線はこれを見込んで選んでください。一時的な急増は、送信元ごと・全体それぞれの受信レート制限で 抑えられます。設定値は設定リファレンスにあります。

E — 分散ポーラー, ネイティブ

D と同じ構成ですが、リモートポーラーをコンテナではなくネイティブのバイナリで動かします。 中央のバスの TLS と認証の設定（D のステップ 1）は、そのままです。

リモートホストで yagra-poller のバイナリをビルドするか、コピーして持ち込みます。CA 証明書を 読める場所に置いてから実行してください:

sudo setcap cap_net_raw+ep ./yagra-poller

export YAGRA_BUS_URL="tls://poller:a-strong-poller-bus-password@core.example.com:4222"
export YAGRA_POLLER_ID="edge-tokyo-1"       # unique per poller
export YAGRA_POLLER_POOL="tokyo"
export YAGRA_BUS_CA_FILE="/etc/yagra/certs/server-cert.pem"
# Optional intake listeners (see the privileged-port caveat in D):
# export YAGRA_SYSLOG_BIND="0.0.0.0:1514"
# export YAGRA_TRAP_BIND="0.0.0.0:1162"
# export YAGRA_FLOW_BIND="0.0.0.0:2055"
export RUST_LOG=info

./yagra-poller

ホストネットワークの上で動かしてください。専用のネットワークネームスペースに入れてはいけません。 パッシブイベントの送信元 IP による対応付けと、raw ICMP が、拠点の実インターフェースに対して 働く必要があるからです。

それ以外の挙動 — プール、登録、フェイルオーバー、バッファ — は D とまったく同じです。

アップグレードとバックアップ

アップグレードは、手間をかけずに終わり、データを失わず壊さないよう設計されています。これは すべてのマイグレーションとメッセージ形式が守るべき設計目標であって、「どの版でも証明済み」 という約束ではありません。

ですから、まず移行先リリースのノートを読んでください。運用担当や API を使う人が気付く挙動の変更が 載っているからだけではありません。版によっては、その版について保証を取り下げ、「新規インストール してください」と言うことがあるからです。そのときはノートの破壊的変更の節にそう書いてあり、 新規インストールで何を失うかも書いてあります。変更履歴から各版のノートへ 辿れます。

v0.3.5 はその場でのアップグレードを保証しません — 新規インストールを

この 1 つの版に限り、アップグレードの仕組み自体は残っていて動きますが、保証を取り下げます。 その場で上げると、v0.3.5 が自力で直せない状態に残ることがあります。1 つは既に分かっています —— 拠点は上げても拠点 updater が入れ替わらないので、新しい「この拠点はアップグレードの安全を表明して いません」の警告が、上げただけでは消えません。

中央デプロイを新規インストールしても、遠隔拠点は入れ替わりません。 拠点は別のデプロイです。 設定 ▸ ポーラー ですべての拠点のキットを再発行し、拠点で展開して起動してください。これを飛ばすと、 各拠点は古い構成のまま残ります。

新規インストールで失うもの。 ストアは空から始まるので、収集済みのメトリクス・アラート履歴・ 監査ログは引き継がれません。設定の大半は運べます —— 設定 ▸ 設定バンドル でエクスポートし、新しい デプロイでインポートしてください。バンドルが意図的に運ばないものは作り直しが必要です —— ユーザーアカウントと API トークン、監視用の資格情報、通知チャネルとそれを指すルーティングルール、 LDAP / OIDC / LLM の設定、ダッシュボードのレイアウト。

これは 1 つの版についての判断であって、方針の変更ではありません。公開リリースに対してアップグレード 経路を通しで走らせられたら、保証は戻す想定です。

v0.2.3 / v0.2.4 / v0.2.5 をお使いの方は v0.2.6 へ

この 3 つのリリースには、1 台の機器につきチェックを 1 本しかポーリングしないという不具合が あります。

SNMP のノードでは、システムスカラー（機器全体の状態を表す数個の値）だけが届き続けます。 インターフェースの walk、ベンダーの機器状態表、トポロジの walk、さらには ICMP まで、毎周期 捨てられます。つまり、SNMP の収集が黙って止まります。

しかも、何も知らせません。生き残るチェックがそのまま死活監視のチェックだからです。ノードは ok のままで、欠測も記録されず、アラートも上がりません。

症状は規模が小さいほど重く出ます。初めて導入した環境がいちばん強く踏み、大規模なフリートは影響を 受けません。設定を変える必要はありません。修正はポーラー側にあるので、アップグレードすればそれで 直ります。

WebUI から（v0.2.2 以降、構成 A）

これが通常のアップグレード手段です。Settings ▸ Upgrade を開くと、この環境が移行できる リリースが並びます。

Upgrade を押しても、まだ何も始まりません。この環境を構成しているもの —— core、同居ポーラー、 各遠隔拠点 —— の一覧が開きます。各行に、いま動いている版・移行先の版・チェックボックスが並び、 チェックは最初からすべて入っています。もう一度 Upgrade を押すと、チェックを残した行だけが 動きます。

動かす行それぞれについて、この画面は次の 6 つをまとめて実行します。

1. 何かを書き込む前に、空き容量を確かめる
2. バックアップを取る
3. イメージを取得する（pull）
4. 対象イメージの中に入っている構成を導入する
5. コンテナを作り直す
6. 正しく上がったか検証する

手順 1 は、満杯のホストをさらに悪くしないためのものです。バックアップは PostgreSQL のフルダンプと VictoriaMetrics のスナップショットで、どのイメージを取得するより前に、このホストへ書き込まれます。 ∴ この確認が無いと、既に満杯のホストにまず数百 MB を書き足してから pull に失敗していました。今は 必要量と現在値の両方を文言に入れて停止し、デプロイには一切手を付けません。下限は YAGRA_UPGRADE_MIN_FREE_BYTES（既定 3 GiB）です。

新しい版が健全に上がった後、サイドカーは後片付けをします。直前のリリースは残すので 1 ホップの 切り戻しに再ダウンロードは要りません。それより古いものと、古いバックアップは削除されます。触れるのは Yagra 自身の 3 イメージだけで、バックアップは必ず 1 つ残ります。残す本数は YAGRA_UPGRADE_KEEP_RELEASES で変えられます。

実行するのは yagra-updater サイドカー（アップグレードを代行する小さなコンテナ）です。 Docker ソケットを持つのはこのコンテナだけで、コアは持ちません。アップグレードを要求するには manage-the-deployment（デプロイの管理）の権限が必要で、これを持つのは Admin だけです。実行は 監査ログに記録されます。MCP には意図的に出していません。

この機構は、同じ画面のスイッチで止められます。設定は PostgreSQL に保存されるので、その機構が 管理するアップグレードをまたいでも残ります。compose ファイルからサービスを消す方法とは違う点 です。各バージョンが自分の構成を導入するため、消したサービスは次のアップグレードで戻ってきます。

手順 4 は同じ理由で docker-compose.deploy.yml も入れ直します。つまりそのファイルへの編集も アップグレードを越えません。その箱だけに必要な変更は、同じディレクトリに置く docker-compose.local.yml に書いてください。 アップグレードはこのファイルを置き換えません。 v0.3.11 からは、このファイルがあれば Compose へ 2 枚目の -f として渡します。Compose は後の -f を先の -f に重ねるので、上書き側には変えるところだけ書けば済みます。

# docker-compose.local.yml —— アップグレードはこのファイルを置き換えません
services:
  poller:
    networks: [default, lab-devices]
networks:
  lab-devices:
    external: true

起動もアップグレードと同じ形で行います。

docker compose -p yagra -f docker-compose.deploy.yml -f docker-compose.local.yml up -d

このファイルが無いデプロイへの影響はありません（ファイルが無ければ引数も足しません）。 アップグレードは どちらだったかを言います —— with this deployment's docker-compose.local.yml か no docker-compose.local.yml here か。これにより、自分の変更が運ばれなかったデプロイと、 そもそも運ぶものが無いデプロイを読み分けられます。**設定 ▸ ポーラー ▸「リモートポーラーを 受け入れる」**もこの上書きを渡します。この切り替えはポーラーを名指しで作り直すからです。

network_mode: host にはもう 1 行要ります

ポーラーを network_mode: host にする場合、上書き側に ports: !reset [] も必要です。Compose は ホストネットワークのサービスに公開ポートを重ねられないためです。!reset は Compose v2.24 以降を要求します。足すだけの上書きなら 2.x なら何でも動きます。

なお、この機構を持つのは構成 A だけです。それ以外のインストール方法 — ソースからのビルド、 ネイティブ実行、yagra-updater サイドカーを置いていない構成 — にはありません。その場合、画面は 押しても失敗すると分かっているボタンを並べず、使えないことをはっきり表示します。

遠隔拠点のポーラーも一緒に上がります。v0.3.3 からは既定で上がります。

監視対象の拠点で動いているポーラーは、自分だけの compose プロジェクトとして動いています。 中央のデプロイとは別のプロジェクトなので、そのままでは中央から再起動できません。

拠点キット —— Settings ▸ Pollers ▸「Issue token & download」 —— が生成する .env に、 COMPOSE_PROFILES=self-upgrade が書かれます。そうするチェック欄は最初から入っています。 このプロファイルが拠点で yagra-poller-updater サイドカーを起動し、その拠点は「自分でリリースを 導入できます」と申告するようになります。すると core は、自分がいま入れたリリースをその拠点へ 渡します。渡し方には決まりがあります。

• プールごとに 1 台ずつ渡します。ポーラーが 2 台以上あるプールは、監視を止めずに済みます。
• イメージの取得は、何かを止める前に行います。ポーラーが 1 台しかない拠点でも、止まるのは コンテナを作り直す間だけです。ダウンロードの間は止まりません。
• ポーラー自身は Docker ソケットに触りません。コマンドの中身を確かめてから共有ボリュームへ 書き、それを自分のサイドカーが読んで実行します。中央のコアと同じ形です。

拠点を対象から外すには、キットを発行する前にチェックを外すか、あとからその拠点の .env で COMPOSE_PROFILES の値を空にします。切り替えは compose ではなく .env で行ってください。 アップグレードは compose を導入するリリースのものに入れ替えますが、.env には触れません。 v0.3.3 より前にキットを渡した拠点は、キットを再発行して渡すまで今までどおりの動作のままです。

展開する前に、これが何を許すかを読んでください。サイドカーは root で動き、その拠点ホストの Docker ソケットを持ちます。中央のサイドカーと同じ取り引きで、境界も同じです。 アップグレード用サイドカー を参照してください。

v0.3.4 より前に立てた拠点は、先に拠点で 1 度だけコマンドが要ります

次に中央をアップグレードする前に、その拠点のデプロイディレクトリで 1 度だけ実行してください。

docker compose -p yagra-poller -f docker-compose.poller.yml up -d

拠点のアップデーターは名前付きサービスなので、apply が作り直すのは poller だけで、アップデーター 自身は作り直されません —— コンテナは作られたときの定義を持ち続けます。v0.3.4 より前に作られたものは docker compose を自分のコンテナの中から実行するため、相対パス ./certs を既定とする証明書の マウントが、そのコンテナの中にしか無いパスとして解決されます。Docker は存在しないホスト ディレクトリを失敗させず空で作るので、入れ替わったポーラーはバスを信頼する材料を持たずに起動し、 二度と接続できません —— それでいて拠点は apply … succeeded、この画面は「揃っている」と表示します。 他に生きたポーラーが居るプールはノードが移るので監視は続きますが、1 台だけのプールは手で直すまで 暗いままです。

v0.3.4 以降のアップデーターは、このマウントをホスト側のディレクトリに対して解決し、証明書 ディレクトリが空のポーラーは作り直しを拒否します。必要なのはこの 1 回だけで、v0.3.4 以降に発行された キットから立てた拠点は最初から影響を受けません。

先にその拠点の .env の YAGRA_IMAGE_TAG を確認してください。アップデーターはタグを自分の コマンドラインで渡すため、.env がレジストリに無いタグを指したままでも誰も気づきません。一方この コマンドを手で打つと .env が読まれます。

取り残された拠点は、core を上げ直さずに追いつかせられます。 以前は命令が core 自身の アップグレードの尻尾でしか出なかったため、あとから立てた拠点・失敗して直した拠点・今日 アップデーターを有効にした拠点は、次のリリースまで取り残されたままでした。v0.3.4 からは、 一覧で core のチェックを外して Upgrade を押すだけです。このデプロイのコンテナは何も再起動せず、 プールごとに 1 台ずつ渡す点も変わりません。core より新しいポーラーは core の版まで戻します。 バスが保証しないのはそちら向きの版差だからです。

Upgrade を押す前に、一覧が付いてこないポーラーとその理由、そしてポーラーが 1 台しかない プール（そのプールはコンテナを作り直す間だけ監視が止まります）を名前で挙げます。この警告は チェックの状態に追随するので、行のチェックを外せば内容も変わります。また、ポーラーを 2 版 遅れにしてしまうリリースは、理由を添えてチェックボックスなしで表示されます。バスが許容する版の ずれは、1 リリースまでだからです。

アップグレードのポーラー側にも、独立した進捗が出ます。 core 側の手順は「検証」で終わりますが、 その後 —— 各拠点が自分の回線でイメージを取得し、プールごとに 1 台ずつコンテナを作り直す —— に さらに 30 分ほどかかることがあります。各拠点の現在地が表示され、実行後もその記録が画面に残るので、 戻ってこなかった拠点が名指しで分かります。 以前は生存ポーラー一覧から静かに消えるだけでした。

戻す操作も、決められた範囲内でならできます。マイグレーション（データベースの形の変更）は 互換下限を宣言できます。互換下限とは、それを適用したあと、それより古い版では動かなくなる 境目のことです。現在の下限を下回るリリースは、隠さずに、理由を添えて選べない状態で表示します。

戻しても 1 行も失われません。新しい版が追加した列はそのまま残ります。読まれなくなるだけで、 もう一度上げれば また見えるようになります。

到達できるレジストリがひとつも無い環境向けの経路もあります。イメージに手が届く場所で リリースの 3 イメージを docker save し、同じ画面からアーカイブをアップロードしてください。

この経路を使うには、ホスト側でもう 1 段の許可（YAGRA_UPGRADE_ALLOW_BUNDLE=1）が要ります。 docker load はアーカイブに入っているものを何でも導入してしまうからです。有効にする前に 設定リファレンスを読んでください。

コマンドラインから

コマンドラインからのアップグレードも、引き続き使えます。サイドカーを止めている場合や、 そもそも置いていない構成の場合は、こちらを使ってください。

やることは「使うイメージのタグを新しい版に変えて、コンテナを作り直す」だけです。

1. バックアップを取ります。

   大きなアップグレードの前には必ず取ってください。取るのは 2 つです。

   # PostgreSQL — ノード・設定・ユーザー・アラート履歴が入っています
   docker compose -f docker-compose.deploy.yml exec postgres \
     pg_dump -U yagra yagra > yagra-backup.sql
   
   # KEK（マスタ鍵）— 小さく、そして代わりが作れません
   docker run --rm -v yagra_kekdata:/kek busybox cat /kek/key > kek-backup.key

   メトリクスは vmdata ボリュームにあります。普段お使いのボリュームのツール、または VictoriaMetrics 自身のスナップショット API でスナップショットを取ってください。 Redis は取らなくてかまいません。 中身はいつでも作り直せるので、失っても問題ありません。

2. 移行先の版を決めます。

   変更履歴にざっと目を通してください。挙動が変わる点は、必ずそこに 載っています。

3. 新しいタグでイメージを取得します。

   # .env に書いておく場合: YAGRA_IMAGE_TAG=v0.2.2
   # 下のように 1 行ずつ指定してもかまいません
   YAGRA_IMAGE_TAG=v0.2.2 docker compose -f docker-compose.deploy.yml pull

4. そのイメージでコンテナを作り直します。

   YAGRA_IMAGE_TAG=v0.2.2 docker compose -f docker-compose.deploy.yml up -d

   データベースの形の変更は、コアが起動したときに自動で走ります。手で流すものはありません。

なぜこの手順でデータが壊れないのか

• データベースの形の変更は、先に足して、あとから削る 2 段構えで行われます。 途中で止まっても データは消えません。1 つ上の版へは必ず上げられます。何が行われるのか先に知りたいときは、 対象のイメージの中で yagra-core migrations を実行してください。そのバイナリに入っている 変更の一覧を JSON で出力します。データベースにも設定にもつながないので、まだ何も触っていない 状態で計画を立てられます。
• コアとポーラーは、1 版までなら版がずれていても通信できます。 新しいコアは古いポーラーと そのまま動きます。ですからコアを先に、ポーラーを後で上げてください。リモート拠点も含めて、 1 台ずつ、順番は自由です。
• ポーラーは状態を持ちません。 いつ入れ替えてもかまいません。プールの中のポーラーが一時的に 0 台になっても、コアはジョブを 1 件ずつ配る昔のやり方に切り替えます。入れ替えの最中も、 監視が止まるノードはありません。
• 保存されたデータはそのまま残ります。 pgdata（PostgreSQL）、vmdata（VictoriaMetrics）、 kekdata（KEK）の 3 つのボリューム — ネイティブ構成ならそれに当たる場所 — は、イメージを 入れ替えても手を付けられません。

元に戻したいときは、1 つ前のタグで同じ手順をやり直すだけです。 中身が変わらない :<git-sha> タグは、まさにこのために用意してあります。

KEK を決して失わないこと

データベースはバックアップから復元できます。しかし KEK は作り直せません。

kekdata ボリュームや KEK ファイルを失うと、保存してある監視の認証情報は、すべて永久に 読めなくなります。データベースと一緒にバックアップし、そのコピーはホストの障害が及ばない場所に 置いてください。

アンインストール

Yagra はホストに何もインストールしません — パッケージも、システムサービスも、デプロイ用ディレクトリと Docker 自身の保存領域の外にあるファイルも作りません。アンインストールは、インストールを逆にたどるだけです。

以下はすべて docker-compose.deploy.yml を置いたディレクトリで実行します。

`-p yagra` は省略できません

Compose は、指定が無ければプロジェクト名をディレクトリ名から作ります。-p yagra を落とすと down は 別の空のプロジェクトに対して動き、何も消さないまま「成功」と表示します。本物のスタックはそのまま 動き続けます。

止めるだけ（データは残す）。 コンテナとネットワークは消え、名前付きボリュームはすべて残ります。 up -d すれば、設定・アラート履歴・メトリクスをそのまま持った同じデプロイが戻ります。

docker compose -p yagra -f docker-compose.deploy.yml down

完全に消す。 -v は名前付きボリューム 11 個を破棄します — pgdata（ノード・ユーザ・閾値・ アラート履歴・すべての設定）、vmdata（メトリクスの全履歴）、vldata（受動イベントの全件）、 chdata（フローの全レコード）、kekdata（鍵暗号化鍵）、および証明書・ログ・バッファ・受け渡し用の 各ボリュームです。

docker compose -p yagra -f docker-compose.deploy.yml down -v --remove-orphans

イメージとディレクトリも消す場合:

docker compose -p yagra -f docker-compose.deploy.yml down -v --rmi all --remove-orphans
cd .. && rm -rf yagra          # compose ファイルと、POSTGRES_PASSWORD が入った .env

--rmi all はバックエンドのストアのイメージ（postgres / redis / nats / victoria-metrics / victoria-logs / clickhouse）も消します。他のプロジェクトがまだ使っているものは Docker が飛ばします。

KEK の無いバックアップは復元しても空です

保存済みの監視資格情報 — SNMP コミュニティ、SNMPv3 認証情報、API トークン、バスの秘密鍵 — はすべて kekdata にある鍵で封筒暗号化されています。-v はこの鍵を破棄し、鍵は再生成できません。KEK なしで 取ったデータベースのダンプは、完璧に復元できるのに何もポーリングできません。

戻ってくる可能性が少しでもあるなら、先に KEK を取り出してください。

docker run --rm -v yagra_kekdata:/kek busybox cat /kek/key > yagra-kek.bin

設定バンドルは代わりになりません。バンドルは資格情報を一切運ばず id だけを運ぶので、新しい KEK で 作り直したデプロイにその id は存在しません。

リモートポーラーは別のスタックです。 リモート拠点のポーラー（構成 D）は、そのホスト上の独立した Compose プロジェクトです。上の操作では一切消えず、中央スタックが無くなったあともバスへの再接続を 試み続けます。各ホストで個別に docker compose -f docker-compose.poller.yml down -v してください。

消し残りの確認。 Compose は作ったものすべてにラベルを付けるので、compose ファイルが無くても引けます。

docker ps -a      --filter label=com.docker.compose.project=yagra
docker volume ls  --filter label=com.docker.compose.project=yagra
docker network ls --filter label=com.docker.compose.project=yagra

WebUI にアンインストール操作はありません。設定 ▸ アップグレードはリリース間の移動だけを行います。 アンインストールは意図的にホスト側の作業にしてあります。

次のステップ

• すべての環境変数・既定値・クランプ — 設定リファレンス
• どのポートが何を運び、何をファイアウォールで守るか — ポート一覧
• プール・作業セット・フェイルオーバーの実際の挙動 — 分散ポーリング
• 複数のコアを動かす — 高可用性
• あらゆる場所での TLS、KEK、ポーラー単位のバス認証情報 — セキュリティ
• 構造化ログ、Prometheus メトリクス、分散トレーシング — 可観測性