netbox-assurance

NetBox Assurance

NetBox Assurance に関する情報は古くなっている可能性があります。 差分の種類、データソースの設定、API の動作はリリースごとに変わります。事前学習済みの知識よりも、情報を取得して確認してください。

情報取得元

情報源	URL／方法	用途
Assurance のドキュメント	https://netboxlabs.com/docs/assurance/	概要、利用開始、UI のワークフロー
NetBox Platform MCP	設定されている場合 — 差分、データソースを照会	ライブのドリフト状況

NetBox Assurance は、意図したネットワーク状態（NetBox が存在すべきと示しているもの）と実際のネットワーク状態（実際に存在するもの）の間のドリフトを検出します。違いを差分として提示し、NetBox UI から確認して解決できます。

このスキルを使用する場面

• Assurance の差分ワークフローの設定やトラブルシューティング
• ドリフトの種類と解決方法の理解
• 実際のネットワーク状態を取り込むデータソースの設定
• Assurance と Discovery および Diode の統合
• 差分のトリアージを中心とした運用ワークフローの構築

クイックリファレンス

差分の状態

状態	意味
Queued	取り込まれ、分析待ちのデータ
Open	ドリフトが検出され、確認可能な状態
Applied	変更が承認され、NetBox に反映された状態
Ignored	オペレーターによって却下された状態
Failed	反映が試みられたものの、エラーになった状態
No Changes	分析で差異が見つからなかった状態
Errored	分析中に処理エラーが発生した状態

アクション

アクション	内容	実行可能な状態
Apply	差分を承認し、実際の状態に合わせて NetBox を更新します	Open, Failed
Ignore	差分を恒久的に却下します	Open
Rediff	現在の NetBox の状態と照らし合わせて再分析します	Open, Applied, Failed
Reopen	無視された差分を再び表示します	Ignored

すべてのアクションで、複数の差分に対する一括操作が可能です。

ドリフトの種類

種類	説明	例
属性ドリフト	オブジェクトが両方に存在しますが、プロパティが異なります	デバイスのシリアル番号が変更された
インベントリドリフト（追加）	ネットワーク上で検出されたものの、NetBox に存在しないオブジェクト	デバイスで新しいインターフェイスが見つかった
インベントリドリフト（古い情報）	NetBox に存在するものの、ネットワーク上で最近確認されていないオブジェクト	廃止済みのデバイスが NetBox に残っている

トポロジードリフト（デバイス→誤ったサイトのような関係の不一致）と構成ドリフト（実行中の設定と意図した設定の不一致）は、今後対応する予定の機能です。

アーキテクチャ

Assurance は、次の 3 段階のパイプラインに従います。

1. INGESTION          2. ANALYSIS              3. RESOLUTION
   ─────────            ────────                 ──────────
   Actual state    →    Compare actual     →     Review deviations
   collected from       vs intended              and take action
   network              (NetBox) state           (apply/ignore)

データソースは、実際のネットワーク状態をシステムに取り込みます。

• Discovery エージェント — SNMP／API ベースの自動ネットワークスキャン
• コントローラー統合 — VMware vCenter、Cisco Catalyst Center、HPE Mist など
• Diode SDK — あらゆるデータソースに対応する、Python／Go によるカスタム統合

分析エンジンは、取り込まれたデータを NetBox と比較し、フィールド単位の変更詳細（各属性の変更前／変更後の値）を含む差分を生成します。

データソース

Assurance には、実際のネットワーク状態を提供するデータソースが少なくとも 1 つ必要です。詳しい設定については、references/data-sources.md を参照してください。

Discovery エージェント（推奨される開始方法）

NetBox Discovery の Orb Agent はネットワークを能動的にスキャンし、結果を Assurance に直接送信します。利用を始める際に最も一般的な方法です。

エージェントの設定については、netbox-discovery スキルを参照してください。

コントローラー統合

インフラストラクチャコントローラー（VMware vCenter、Cisco Catalyst Center、HPE Mist など）との組み込み統合により、管理プラットフォームから状態を取得します。

Diode SDK（カスタム統合）

組み込みでサポートされていないデータソースには、Diode SDK（Python または Go）を使用して、エンティティデータをプログラムで送信します。

SDK の使用パターンについては、netbox-diode スキルを参照してください。

偏差のライフサイクル

完全な状態遷移図については、references/deviation-lifecycle.mdを参照してください。

一般的なワークフロー

1. データの取り込み — データソースからネットワークデータが到着し、偏差がQueuedになります
2. 分析の実行 — システムがNetBoxと比較し、偏差がOpen（またはNo Changes）になります
3. オペレーターによる確認 — UIでフィールド単位の変更を確認します
4. 操作の実行：
   • Apply → NetBoxが更新され、偏差がAppliedになります
   • Ignore → 偏差が破棄され、Ignoredになります
   • Rediff → 現在のNetBoxの状態と照らし合わせて再分析します（NetBoxを手動で編集した後に便利です）

解決パターン

シナリオ	推奨される操作
正当な変更が検出された（例：新しいインターフェースの追加）	Apply — NetBoxを更新します
追跡する必要のない既知の不一致	Ignore — 破棄します
すでにNetBoxを手動で更新した	Rediff — 再分析して確認します
以前に無視したが、状況が変わった	Reopen → 次にApplyまたはRediffを実行します
一時的なエラーでApplyに失敗した	問題を修正してから、Rediffを実行するか、Applyを再試行します

UIワークフロー

ナビゲーション

Assuranceにより、NetBoxのナビゲーションにAssuranceセクションが追加され、次のビューが利用できます。

ビュー	目的
Deviation Types	偏差のカテゴリと件数を確認します
Active Deviations	対応が必要な未解決の偏差を表示します
All Deviations	解決済みを含むすべての偏差を表示します
Archived Deviations	解決済み偏差の履歴を表示します

偏差の確認

1. Assurance → Active Deviationsに移動します
2. 偏差をクリックして詳細ビューを開きます
3. Overviewタブ — ソース、オブジェクトタイプ、状態、タイムスタンプを確認します
4. Changesタブ — フィールド単位で変更前と変更後を比較します
5. 操作を実行します：Apply、Ignore、またはRediff

一括操作

任意のリストビューで複数の偏差を選択し、一括操作を実行できます。

• Bulk Rediff — 選択したすべての偏差を現在のNetBoxの状態と照らし合わせて再分析します
• Bulk Ignore — 選択したすべての偏差を破棄します
• Bulk Apply — 選択したすべての変更をNetBoxに適用します

フィルタリング

偏差リストでは、次の条件でフィルタリングできます。

• State — Open、Applied、Failed、Ignoredなど
• Object type — 例：デバイス、インターフェース、IPアドレス
• Deviation type — ドリフトの分類
• Data source — 偏差を生成したインテグレーション
• Time range — データが取り込まれた時期

偏差タイプ

偏差は、必要な操作とオブジェクトタイプを組み合わせたタイプに分類されます。

• Createタイプ — オブジェクトをNetBoxに追加する必要があります（インベントリドリフト）
• Updateタイプ — オブジェクトは存在しますが、属性が異なります（属性ドリフト）

各偏差タイプには該当する偏差の件数が集計されるため、Deviation Typesビューを使ってドリフトのパターンを一目で把握できます。

比較対象

取り込みパイプラインを通るあらゆるエンティティタイプを比較できます。一般的なタイプは次のとおりです。

• デバイス（dcim.device）
• インターフェース（dcim.interface）
• サイト（dcim.site）
• デバイスタイプ（dcim.devicetype）
• IPアドレス（ipam.ipaddress）
• プレフィックス（ipam.prefix）

このシステムは拡張可能で、データソースから提供されるあらゆるエンティティタイプを比較します。

インテグレーションパターン

詳細なインテグレーションガイダンスについては、references/integration-patterns.mdを参照してください。

NetBox Discoveryとの連携

Discoveryエージェントは、比較における「実際の状態」を提供します。

Network Devices → Orb Agent (Discovery) → Assurance → Deviations → NetBox

DiscoveryとAssuranceは密接に連携しています。Discoveryが収集し、Assuranceが比較と修正を行います。

Diode SDKとの連携

Diode SDKは、カスタムインテグレーション向けのプログラムによる取り込み経路です。

Custom Script → Diode SDK (Python/Go) → Assurance → Deviations → NetBox

NetBox Branchingとの連携

偏差をNetBoxのブランチに関連付けることで、次のことが可能になります。

• 特定のブランチの状態と照らし合わせてドリフトを確認する
• メインデータベースではなく、ブランチに変更を適用する
• 偏差を解決する際のステージング領域としてブランチを使用する

Day 1 / Day 1.5 / Day 2 のパターン

パターン	ユースケース
Day 1 — 初期データ投入	新しいネットワークに対して Discovery を実行し、差分を一括適用して NetBox にデータを登録します
Day 1.5 — 照合	既存の NetBox データを実際のネットワークと比較し、不一致を修正します
Day 2 — 継続的な保証	継続的にドリフトを監視し、差分が発生したらトリアージします

権限

Assurance には、次の 2 つの権限レベルがあります。

権限	付与される権限
View Assurance	差分ビューへの読み取り専用アクセス
Add Assurance	操作（適用、無視、再差分、再オープン）を実行する権限

これらは、NetBox の標準的なユーザー／グループ権限システムを通じて割り当てます。

前提条件

• Assurance が有効になっている NetBox Cloud または NetBox Enterprise。ドキュメントでは、要件を Assurance エンタイトルメント付きの NetBox Enterprise 1.10+（Assurance サービスがインストールされるかどうかはライセンスファイルによって決まります）、または Starter、Professional、Premium プラン向けの NetBox Cloud アドオンとしています。Assurance プラグインの系列は v1.6.x（v1.6.0、2026-09-03）で、NetBox 4.4.10–4.7.x を指定しています。実際に利用する NetBox のバージョンは、Cloud／Enterprise プラットフォームのリリースに同梱されているものです。
• 少なくとも 1 つのデータソースが設定済みであること
• データソースと Assurance サービス間のネットワーク接続

Assurance は NetBox Cloud および NetBox Enterprise 向けのオプションのライセンス制アドオンであり、オープンソース版の NetBox Community には含まれていません。

トラブルシューティング

差分が表示されない

1. データソースが有効で、データを送信していることを確認します
2. Discovery エージェントが実行され、データを収集していることを確認します（netbox-discovery を参照）
3. データ取り込みが機能していることを確認します（データが分析まで流れている必要があります）
4. 時間をおいてください。分析は非同期で行われ、数分かかることがあります

誤検知が多すぎる

• ノイズの原因となっているオブジェクトタイプとフィールドを確認します
• 許容できる既知の不一致には Ignore を使用します
• データソース設定の調整が必要かどうかを検討します（例：SNMP コミュニティ文字列、API 認証情報）

失敗した差分

• 差分の詳細ビューでエラーの詳細を確認します
• よくある原因：NetBox への書き込み権限の問題、検証エラー、依存関係の順序
• 根本原因を修正した後、Rediff を使用して再分析します

大規模ネットワークでのパフォーマンス

• フィルタリングを使用して差分ビューを絞り込みます（状態、オブジェクトタイプ、期間など）
• 差分は段階的に処理します。まず 1 つのオブジェクトタイプまたはサイトから始めます
• 一括操作を使うと、大量の項目を効率的に処理できます

アンチパターンと制限事項

1. Assurance はデータソースが提供するデータを比較します — データソースがフィールドを収集しない場合、Assurance はそのフィールドのドリフトを検出できません
2. 適用時には順序が重要です — 一部の差分は他の差分に依存します（例：デバイスをサイトに割り当てる前に、そのサイトを作成する必要があります）。システムは依存関係の順序を処理しますが、複雑な依存関係の連鎖には手動での対応が必要になる場合があります
3. 古いインベントリの検出には制限があります — NetBox から削除すべきオブジェクト（ネットワーク上に存在しなくなったオブジェクト）の検出は、観測タイムスタンプに依存しており、機能は現在も進化中です
4. リアルタイムシステムではありません — ネットワークの変更、ディスカバリー、分析、差分の利用可能化の間には、必然的に遅延が生じます
5. ブランチのスコープ — ブランチを使用する場合は、正しいブランチコンテキストに対する差分を確認していることを確かめてください

バージョンに関する注記

NetBox 4.7 (2026-09-02)

• diode-sdk-python 1.14.x / diode-sdk-go 1.12.0 を基盤とするデータソースは、4.7 のモデル（cooling、ModuleBayType）とフィールド（Interface.channels/channel_id、Service.port_mappings、DeviceType.end_of_life、cooling_method）を出力できるため、プラットフォームのリリースに NetBox 4.7 が含まれると比較可能になります（プラグイン v1.6.0 では 4.7.x のサポートが宣言されています）。詳しくは references/data-sources.md をご覧ください。
• トリアージ中に読み取る REST レスポンスの形式が変更されました（選択式のカスタムフィールドが {"value", "label"} オブジェクトとして返される、サービスの port_mappings、オブジェクトごとの一括処理エラー）。詳しくは references/deviation-lifecycle.md をご覧ください。

NetBox 4.6

• Diode SDK（python 1.12.0 / go 1.9.0）では CableBundle、RackGroup、VirtualMachineType が追加され、スイッチスタックの検出で VirtualChassis とメンバーデバイスが出力されるようになりました。

参考資料

ドキュメント	読むタイミング
references/deviation-lifecycle.md	状態遷移や解決パターンを理解するとき
references/data-sources.md	比較対象の設定を行うとき
references/integration-patterns.md	Assurance と Discovery、Diode、NetBox Labs スタックを接続するとき

関連スキル

• netbox-discovery — ネットワークスキャン用の Orb Agent の設定
• netbox-diode — プログラムによるデータ取り込み用の Diode SDK
• netbox-branching — ブランチ対応のワークフロー