インストール

Yagra は 2 つの常駐バイナリと静的 WebUI で構成されます: Yagra-core（オーケストレーション、 スケジューリング、ノースバウンド REST API）、Yagra-poller（ステートレスな ICMP/SNMP/API ワーカー）、 そして Yagra-web（nginx が配信し、/api をコアへリバースプロキシする WebUI）です。 本ページでは、1 コマンドで立ち上がる評価用マシンから、TLS バス越しに結果を中央へ送り返す リモート拠点ポーラーまで、このスタックをインストールするすべてのサポート構成を扱います。

その背後には最大 6 つのバックエンドサービスが控えます:

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

ポーラーが接続するのは NATS だけです — デバイス認証情報・ジョブ仕様・結果はすべてバス上を 流れ、ポーラーがデータベースに触れることはありません。これがポーラーをステートレスかつ水平 スケール可能にし、リモート拠点の NAT の内側にも配置できるようにしています。

デプロイ構成の選択

軸は 2 つ — 単一ノード vs. 分散ポーリングと、Docker vs. ネイティブプロセスです。

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

Yagra が初めてなら、A（1 コマンド・ローカルでビルド）か B（本番相当・ビルド済み イメージを取得）から始めてください。リモート拠点にポーラーが必要になったら D または E へ — ポーラーは中央のバスへ外向きに接続するため、拠点側に受信ポートを一切開けずに NAT や ファイアウォールを越えられます。

スケールアウトは書き換えではなく設定変更です: 単一ノードでも分散でも同じイメージを動かします。 リモートポーラーを追加し、バスがマシンの外へ出る前に 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.yml はイメージをローカルでビルドし、スタック 全体 — コア・ポーラー・WebUI とすべてのバックエンドストア — を 1 ホストで動かします:

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

その後 https://localhost:8443 で WebUI を開き、コアのログに出力される一度限りの admin パスワードでサインインします。初回起動時の証明書は自己署名なのでブラウザが警告します — WebUI の TLS を参照してください。クイックスタートが、 初回ログインを含むこの手順をステップごとに解説しています。

ヒント

この構成は評価と開発には十分です。大切に扱う環境では B を使ってください — リリースイメージの タグ固定と永続的なマスタ鍵（KEK）により、保存済み認証情報が再起動やアップグレードを越えて維持 されます。

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

本番相当の単一ノードデプロイです。docker-compose.deploy.yml は GHCR からイメージを取得し （ローカルビルドなし）、.env でパラメータ化され、保存済みの監視認証情報が再デプロイを越えて 維持されるよう、永続的なマスタ鍵（KEK）を書き込む one-shot の kek-init サービスを追加します。

1. リポジトリをクローンし、.env を作成します:

   git clone https://github.com/horryworks/Yagra.git
   cd Yagra
   cp .env.example .env

2. .env を編集します。要点:

   YAGRA_IMAGE_TAG=v0.1.22                # pin a stable release (see the releases page)
   POSTGRES_PASSWORD=change-me            # change for any non-throwaway box
   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
   # YAGRA_PUBLIC_DASHBOARD=false         # true = read-only dashboards without login

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

3. 取得して起動します:

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

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（トラフィックフロー）、そしてオフラインの IP→ASN データセットを最新に保つ ipasn-updater サイドカー — インターネットへ外向き通信を行う 唯一のコンテナ — が動きます。マイグレーションはコア起動時に自動実行され、名前付きボリュームが 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 の設定 ▸ システムヘルスが、各バックエンドストアへの到達性と、サーバー 自身の総合判定を表示します。

認証情報の永続化 — 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 を失うと、保存済みの認証情報はすべて永久に復号不能になります — データベースのバックアップ からも復元できません。

WebUI の TLS

WebUI は最初から HTTPS です — うっかり公開してしまう平文のリスナーはありません。初回起動時、 コアはループバックとコンテナのホスト名を対象とする自己署名証明書を生成するため、ブラウザは 警告を出し、名前についても文句を言うのが普通です（利用するアドレスをコンテナ内から知る術は ありません）。

対処は、その警告の先にある設定 ▸ TLS 証明書から行います。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 が必要です。ワークスペースのベンダーリングされた依存 パッチが効くよう、リポジトリのルートからビルドします:

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

起動時にコアはストアへ接続し、マイグレーションを自動実行し、組み込みのプロファイルと カタログをシードして、YAGRA_API_ADDR 上で /api/v1 + Prometheus /metrics を提供します — curl -fsS http://localhost:8080/healthz で確認してください。YAGRA_ADMIN_PASSWORD が未設定 なら、一度限りの admin パスワードをログから拾ってください。必須の 3 つの URL （YAGRA_DATABASE_URL・YAGRA_BUS_URL・YAGRA_TSDB_URL）のいずれかが未設定だと、コアは ライブではなくインメモリのスケルトンモードで動きます。恒久的なインストールでは、同じ環境変数を 与えたサービスユニット（systemd など）でラップしてください。コアはいつ再起動しても安全です。 全変数の一覧: 設定リファレンス。

5. WebUI の配信

web/dist/ は静的バンドルです。任意の Web サーバーで配信し、/api をコアへリバースプロキシ してください。同梱の nginx 設定（web/nginx.conf）に倣います — 要点は、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

フルスタックを中央で（B のように）動かし、リモート拠点にポーラーを追加します。各リモート ポーラーは拠点のデバイスをローカルにポーリングし、結果をバス経由で中央へ送り返します。ノードは pool 属性を持ち、コアが各プールのノードをコンシステントハッシュで生存ポーラーへ割り当て、 自動でフェイルオーバーします。概念と挙動の詳細: 分散ポーリング。

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

ジョブメッセージはデバイス認証情報を平文で運びます。1 ホスト内なら問題ありません — バスは内部の Docker ネットワークに留まります。バスがリモート拠点へ信頼境界を越える瞬間から、先に TLS 暗号化と認証が必須になります。NATS の :4222 を平文で公開しては決していけません。

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

これは docker-compose.deploy.yml の nats サービスに（コメントアウトで）既に用意されている オプトインのブロックです。5 つの手順すべてが必須です:

1. サーバー証明書を生成して ./certs に置きます。SAN には、各ポーラーがダイヤルする正確な ホスト/IP を必ず含めます:

   mkdir -p certs
   openssl req -x509 -newkey rsa:2048 -nodes -days 3650 \
     -keyout certs/server-key.pem -out certs/server-cert.pem \
     -subj "/CN=yagra-nats" \
     -addext "subjectAltName=DNS:nats,DNS:core.example.com,IP:203.0.113.10"

   証明書は自己署名なので、それ自身が CA を兼ねます。手順 5 で配布するのは server-cert.pem — 公開証明書のみで、鍵は決して渡しません。

2. バスのパスワードを設定します。.env に（意図的に既定値はありません）:

   YAGRA_NATS_CORE_PASSWORD=a-strong-core-bus-password
   YAGRA_NATS_POLLER_PASSWORD=a-strong-poller-bus-password
   YAGRA_NATS_PORT=4222        # host port to publish the bus on
   YAGRA_CERT_DIR=./certs

3. 認証/TLS 設定を読み込みます。 docker-compose.deploy.yml の nats サービスで command: ["-js"] をコメントアウトし、その下のブロックをコメント解除します — それが docker/nats/nats-server.conf を読み込み、2 つのパスワードを注入し、./certs を マウントして、バスのポートを公開します。

4. 内部クライアントも TLS へ切り替えます — サーバー全体の TLS では平文ポートが残らないため、 同居するコアとポーラーも tls:// を使う必要があります:

   # on the core service:
   YAGRA_BUS_URL: tls://core:${YAGRA_NATS_CORE_PASSWORD}@nats:4222
   # on the local poller service:
   YAGRA_BUS_URL: tls://poller:${YAGRA_NATS_POLLER_PASSWORD}@nats:4222
   # and on BOTH, the pinned server cert plus its volume mount:
   YAGRA_BUS_CA_FILE: /etc/nats/certs/server-cert.pem

   volumes:
     - ${YAGRA_CERT_DIR:-./certs}:/etc/nats/certs:ro

5. certs/server-cert.pem（公開証明書のみ）を各リモート拠点の運用担当者に渡します — それが相手側の YAGRA_BUS_CA_FILE になります。

中央スタックを起動し直します:

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

NATS の設定は core ユーザーにフルアクセスを、poller ユーザーには最小権限 — publish は 結果・イベント・ハートビートのみ、subscribe はジョブと作業セット割当のみ — を与えます。この poller アカウントは 1 つを共有する点に注意してください: 認証済みのどのポーラーも任意の プールの割当を読めるため、テナント境界にはなりません。バス認証情報をポーラー単位にスコープする — 侵害された拠点が自プールのデバイス認証情報しか読めないようにする — には、同じ Compose ブロックに 記載されているオプションの Auth Callout の手順を有効化してください。詳細: セキュリティ。

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

**設定 ▸ ポーラー ▸「ポーラーを登録」**を開きます。リモートホスト用のすぐ使える .env （id・pool・バス URL）が生成されます。このポーラーに担当させたいプールを割り当ててください。

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

リモート拠点のマシンで、docker-compose.poller.yml（ポーラーのみを動かします）を使います:

# put the generated .env next to docker-compose.poller.yml,
# and the CA cert from step 1 into ./certs
mkdir -p certs && cp /path/to/server-cert.pem certs/

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

必須の変数は 3 つ — いずれかが未設定だと Compose はエラー終了します — で、生成された .env が それらを提供します:

YAGRA_BUS_URL=tls://poller:a-strong-poller-bus-password@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 はホストネットワーキングを使い — パッシブな syslog/トラップの 対応付けはデータグラムの送信元 IP をキーにし（ブリッジ NAT はそれを書き換えてしまいます）、 raw ソケット ICMP はホストのインターフェースを直接必要とします — 付与するのは NET_RAW だけ です。ポーラーは起動から数秒以内に設定 ▸ ポーラーに現れ、コアがそのプールのノードの 割り当てを始めます。

特権ポートの注意

リモートポーラーは非 root（raw ICMP 用のファイルケーパビリティのみ）で動くため、:514/:162 （1024 未満）をバインドできません。既定の高位ポート（1514/1162）を使ってホストの ファイアウォールでリダイレクトする — 例: iptables -t nat -A PREROUTING -p udp --dport 514 -j REDIRECT --to-ports 1514 — か、デバイスを 直接高位ポートへ向けてください。

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

• プールのスケール = 同じ YAGRA_POLLER_POOL（かつ別々の YAGRA_POLLER_ID）でポーラーを 増やします。コアがプールをそれらへ再分散し、喪失時はフェイルオーバーします。
• 生存ポーラーが 0 のプールはレガシーのジョブ単位配信にフォールバックするため、 ロールアウト中もノードが監視から欠けることはありません。
• 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 クライアントが気付きうる挙動の変更は、必ずそこに載っています。

Docker デプロイでは、タグを変えて再作成します:

# in .env: YAGRA_IMAGE_TAG=v0.2.0   (or override inline as below)
YAGRA_IMAGE_TAG=v0.2.0 docker compose -f docker-compose.deploy.yml pull
YAGRA_IMAGE_TAG=v0.2.0 docker compose -f docker-compose.deploy.yml up -d

これを安全にしている仕組み:

• マイグレーションは expand-contract 方式で、コア起動時に自動実行されます。N→N+1 は常に サポートされ、手動のマイグレーション CLI はありません。
• バスはバージョン耐性（N/N-1）を持ちます。 ロールアウト中も新しいコアは古いポーラーと 動作するため、コアを先に、ポーラーを後でアップグレードしてください — リモート拠点も含め、 1 台ずつ、順序は自由です。
• ポーラーはステートレスです — 自由に入れ替えられます。一時的にポーラーのいないプールは ジョブ単位の配信にフォールバックするため、ロールアウトの最中もノードが監視から欠けることは ありません。
• 永続データは保持されます。 pgdata（PostgreSQL）、vmdata（VictoriaMetrics）、 kekdata（KEK）の各ボリューム — またはそのネイティブ相当 — は、イメージのアップグレードの 影響を受けません。

大きなアップグレードの前にはバックアップを取ってください:

# PostgreSQL — nodes, configuration, users, alert history
docker compose -f docker-compose.deploy.yml exec postgres \
  pg_dump -U yagra yagra > yagra-backup.sql

# The KEK — tiny, and irreplaceable
docker run --rm -v yagra_kekdata:/kek busybox cat /kek/key > kek-backup.key

VictoriaMetrics のデータは vmdata ボリュームにあります — 普段お使いのボリュームツール （または VictoriaMetrics 自身のスナップショット API）でスナップショットを取ってください。 Redis は再構築可能です。失っても致命的ではなく、バックアップも不要です。ロールバック = 1 つ前のタグで再実行するだけです。不変の :<git-sha> タグは、まさにこのために存在します。

KEK を決して失わないこと

データベースはバックアップから復元できますが、KEK は再生成できません。kekdata ボリュームや KEK ファイルが失われると、保存済みの監視認証情報はすべて永久に復号不能になります。データベースと 一緒にバックアップし、そのコピーはホストの障害が及ばない場所に保管してください。

次のステップ

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