netbox-review-datamodel

NetBox データモデルのレビュー

NetBox のデータモデルに関する知識は古くなっている可能性があります。 利用可能なモデルタイプ、関係、拡張性の仕組みは、リリースごとに変化します。変更を推奨する前に、最新のドキュメントで確認してください。

参照元

参照元	URL / 方法	用途
データモデルのドキュメント	https://netboxlabs.com/docs/netbox/models/	利用可能なすべてのモデルタイプ
カスタムフィールドのドキュメント	https://netboxlabs.com/docs/netbox/customization/custom-fields/	フィールドタイプと動作
カスタムオブジェクトのドキュメント	https://netboxlabs.com/docs/extensions/custom-objects/	コード不要の拡張性
NetBox MCP サーバー	設定されている場合 — 現在のデータモデルの確認、オブジェクト数の集計、不整合の検出	ライブでのモデル監査

レビューワークフロー

NetBox のデータモデルを監査するときは、次のチェックリストに従ってください。

1. 組織を理解する — どのような種類のネットワークですか？（エンタープライズ、DC、ISP、ハイブリッド）
2. 階層を確認する — Region → Site Group → Site → Location → Rack の階層は適切ですか？
3. IPAM を確認する — プレフィックスは適切にネストされていますか？必要な箇所で VRF が使われていますか？アグリゲートは定義されていますか？
4. 命名を確認する — スラッグに一貫性がありますか？名前は人が読みやすく、grep しやすいですか？
5. 拡張性の選択肢を確認する — カスタムフィールド、タグ、コンフィグコンテキスト、カスタムオブジェクトのどれを使うべきですか？
6. テナンシーを確認する — マルチテナンシーは適切に使われていますか？テナントが多すぎたり、少なすぎたりしませんか？
7. モデリング上の問題がないか確認する — フィールドの過剰な用途、構造化データへの description の誤用

重要なルール

階層 (HIER)

ID	ルール	重大度
HIER-1	地理的な区分には Regions、機能上の区分には Site Groups を使い、両者を混同しないでください	高
HIER-2	Locations は再帰的に構成できます。階層を平坦化しないでください（Row だけにするより、Floor > Room > Row のほうが適切です）	中
HIER-3	すべてのデバイスを Site に配置してください（最上位に孤立させないでください）	高
HIER-4	Site に Location が定義されている場合、Rack にも Location を設定してください	中
HIER-5	子が 1 つだけの階層は作成しないでください。価値がないまま複雑さが増します	低
HIER-6	4.6 以降では、RackGroups を使うと、Location ツリーとは独立して、複数の場所にまたがる Rack をフラットにグループ化できます（例：「cage-7」、「cold-aisle-B」）。Rack のグループ化を Site／Location のネスト構造にきれいに対応させられない場合に使い、Locations の代わりとして使わないでください	低
HIER-7	4.7 以降では、階層の保存に ltree が使われます。level（DB カラムではなくなりました）でフィルタリングまたは並べ替えを行うスクリプト／保存済みフィルター／エクスポートに注意してください。代わりに parent_id／ancestor_id または get_ancestors() を使ってください。モデリングに関する助言に変更はありません	中
HIER-8	4.7 以降では、インスタンスを 4.7.0 の pg_dump から復元した場合、名前変更や移動の後に子孫のパスが古いままになっていることがあります。階層レポートを信頼する前に、管理者に manage.py rebuild_ltree_paths --check を実行して修復してもらってください	中

IPAM（IPAM）

ID	ルール	深刻度
IPAM-1	アドレス空間の割り当て境界を追跡するために、RIR 集約を定義します	中
IPAM-2	プレフィックスは正しくネストする必要があります（子は親 CIDR 内に配置）	高
IPAM-3	重複するアドレス空間を分離するには VRF を使用します — グローバルテーブルでプレフィックスを重複させないでください	重大
IPAM-4	IP アドレスにはプレフィックス長が必要です（ループバックは /32、インターフェイスは実際のマスク）	高
IPAM-5	プレフィックスの用途（インフラストラクチャ、顧客、管理）を分類するにはロールを使用します。NetBox 4.6 以降では ASN にもロールを設定できます — ASN の用途の分類に使用します	中
IPAM-6	VLAN は適切な スコープ を持つ VLAN グループに所属させます。スコープには Region／SiteGroup／Site／Location／Rack／ClusterGroup／Cluster（4.6 以降では RackGroup も）が指定できます — site／location だけが選択肢だと決めつけず、VLAN の再利用境界に合った最も範囲の狭いスコープを選んでください	中
IPAM-7	4.7 以降では、複数のプロトコルで同じポートをリッスンするサービス（DNS の tcp/53 + udp/53）は、複数の port_mappings を持つ 1 つの Service です。プロトコルごとに重複したサービス（dns-tcp、dns-udp）があれば指摘して統合し、非推奨の protocol／ports の組み合わせに引き続き書き込むインテグレーションがあれば指摘します（5.0 で削除）。4.5～4.6 ではプロトコルごとに 1 つのサービスを作成する方法のみが利用できます	低

デバイスモデリング（DEV）

ID	ルール	深刻度
DEV-1	すべてのデバイスには Device Type が必要です（名前だけでは不十分です）— これによりポート計画が可能になります	高
DEV-2	機能（ルーター、スイッチ、ファイアウォール）の分類にはロールを使用します — 命名規則だけに頼らないでください	高
DEV-3	Platform はソフトウェアを示します — 構成テンプレートとの互換性を確保するために割り当てます	中
DEV-4	バーチャルシャーシのメンバーには、適切な VC ポジションとマスター割り当てが必要です	中
DEV-5	容量計画のために、インターフェイスのタイプを実際の種類（1000base-t と 10gbase-sr など）に一致させます	中
DEV-6	すべてのラックには、寸法が定義された Rack Type が必要です。4.7 ではラックごとの form_factor、width、outer_* フィールドは非推奨です。5.0 では削除され、rack_type が必須になります — rack_type が null のラック（GET /api/dcim/racks/?brief=1 を走査します — rack_type_id に null フィルターはありません）と、ラックごとの寸法が Rack Type と異なるケースを指摘します	高
DEV-7	4.7 以降では、ブレークアウト／チャネル化されたポートを、親の channels と channel タイプのサブインターフェイスの channel_id でモデル化します。独立した仮想インターフェイスや追加の物理インターフェイスとしてモデル化しないでください — そうしないとケーブル経路とポート数が正しくなくなります	中
DEV-8	4.7 以降では、シャーシのスロットごとに取り付け可能なモジュールが異なる場合（ラインカード、スーパーバイザー、ファンベイなど）、Module Bay Types を使用します。ベイタイプが空の集合の場合は「何でも取り付け可能」を意味するため、シンプルなハードウェアなら未設定でも問題ありませんが、スロットの種類が混在し、ベイタイプが未設定のシャーシは指摘します	低
DEV-9	4.7 以降では、Device Type／Module Type の end_of_life でハードウェアのライフサイクルを記録し、Device／DeviceType の cooling_method、Rack／RackType の cooling_capability／cooling_capacity で冷却を記録します — これらと重複するカスタムフィールド（cf_eol、cf_cooling）があれば指摘します。液冷ホールでは CoolingSource → CoolingFeed → 吸気／排気コンポーネントを使用し、PowerPanel → PowerFeed と同様に構成します	中

拡張性（EXT）

ID	ルール	重要度
EXT-1	1 種類のオブジェクトに紐づく単一値の構造化データには、カスタムフィールドを使用します	—
EXT-2	オブジェクト種別をまたいだ分類や、「このプロパティを持つかどうか」を示すブール値には、タグを使用します	—
EXT-3	スコープに応じてマージされる階層的なキーと値のデータには、構成コンテキストを使用します	—
EXT-4	独自のリレーションシップを持つ新しい第一級エンティティが必要な場合は、カスタムオブジェクトを使用します	—
EXT-5	説明フィールドやコメントフィールドには、構造化データ（JSON、リスト）を保存しないでください	高
EXT-6	組み込みフィールドと重複するカスタムフィールド（例：カスタムの「location」フィールド。4.7 以降では end_of_life、cooling_method、ラックの冷却容量も対象）は作成しないでください	高
EXT-7	データが実際には関連エンティティである場合、数十個のカスタムフィールドを作成するより、カスタムオブジェクトを優先します	中
EXT-8	4.6 以降では、JSON カスタムフィールドに validation_schema（JSON Schema）を指定して構造を強制し、自由形式のままにしないでください。スキーマのない構造化データを保持する JSON フィールドには、警告を出してください	中
EXT-9	4.7 以降では、選択式／複数選択式のカスタムフィールド値は {value, label} オブジェクトとして返されます。custom_fields.x を文字列と直接比較する REST／GraphQL の利用側（統合、API を呼び出すスクリプト）には警告を出してください（ORM 経由の obj.cf[...] は引き続き生の値を返します）。また、URL カスタムフィールドでは ALLOWED_URL_SCHEMES に含まれるスキームを使用する必要があります。検証で失敗する javascript:／カスタムスキームを使用した値には警告を出してください	中

命名（NAME）

ID	ルール	重要度
NAME-1	スラッグは小文字とハイフンを使い、grep しやすい形式にしてください（NYC_DC1 ではなく nyc-dc1）	中
NAME-2	デバイス名には、場所＋機能＋インデックスを含めてください（sw-nyc-dc1-01）	低
NAME-3	一貫性を保ち、命名規則を 1 つ選んで全体に適用してください	高
NAME-4	名前にメタデータを埋め込まないでください（サイト名に VLAN ID を含めないでください）	中

テナント（TEN）

ID	ルール	重要度
TEN-1	論理的な所有権の境界（顧客、部門、プロジェクト）には、テナントを使用します	—
TEN-2	テナントを過剰に設定しないでください。すべてが 1 つのテナントに属する場合、テナント機能はおそらく不要です	中
TEN-3	テナントグループは、テナントを階層的に整理します（例：事業部別）	低
TEN-4	共有インフラストラクチャ（管理ネットワーク、コアルーター）は、テナントに所属させなくてもかまいません	中

フラグを付けるべきアンチパターン

アンチパターン	重要な理由	修正方法
階層がフラットなサイト構成（ロケーションなし）	フロア／部屋／列の配置を追跡できません	ロケーション階層を追加します
重複する IP アドレスをすべてグローバル VRF に登録	IPAM の競合やレポートの不具合が発生します	VRF を分けます
外部キーとしてカスタムフィールドを使用	参照整合性がなく、クエリも困難です	カスタムオブジェクトまたはタグを使用します
説明フィールドに JSON のかたまりを格納	検索、検証、フィルタリングができません	カスタムフィールドまたは設定コンテキストを使用します
種別ごとに巨大な「何でもあり」のカスタムフィールドを 1 つだけ使用	構造化データを使う意味がなくなります	個々のフィールドに分割します
デバイスタイプを設定していないデバイス	ポート／ベイ／スロットのモデリングができなくなります	必ずハードウェアモデルを指定します
ラックタイプを設定していないラック	ラックごとの寸法は非推奨（4.7）となり、5.0 で削除され、rack_type が必須になります	物理モデルごとに RackType を作成してラックに割り当て、ラックごとの寸法を削除します
同じポートに対し、プロトコルごとにサービスを 1 つずつ作成（4.7 以降）	重複が発生し、protocol／ports は非推奨です	port_mappings を使い、1 つの Service に統合します
ブレークアウトポートを物理インターフェイスとして追加	ケーブル経路とポート数が正しくなくなります	親の channels と channel_id を持つサブインターフェイスを使用します
命名規則の混在	スクリプトで処理できず、混乱を招きます	命名規則を統一し、一括で名前を変更します
スペースや特殊文字を含むタグ	API フィルタリングやスクリプトに支障が出ます	スラッグに適したタグ名を使用します
リージョンを過度に深くネスト（3 レベル超）	ナビゲーションが改善されないまま複雑さが増します	最大 2～3 レベルにフラット化します
プレフィックス階層の欠落	親子関係が壊れます	欠落している中間プレフィックスを補います

対象範囲

このスキルでは、データモデルの設計と整理を扱います。以下は扱いません。

• API と連携するコード → netbox-review-integration を使用してください
• ゼロからモデリングする方法 → netbox-data-modeling を使用してください
• Custom Objects プラグインの詳細 → netbox-custom-objects を使用してください

原則

• 状況が重要です。 5 拠点の企業と 500 拠点の ISP では、ニーズが異なります。過剰に設計しないでください。
• 実際のインスタンスを監査します。 MCP を利用できる場合は、ドキュメントだけを確認するのではなく、実際のデータを照会してください。
• 指示するのではなく、提案します。 多くのモデリング方法には妥当性があります。明らかなアンチパターンにはフラグを付けつつ、判断が分かれる点ではトレードオフも示してください。
• データの整合性を優先します。 関係の破損やデータの重複を引き起こす問題は、見た目上の命名の問題より重要です。
• 移行コストを考慮します。 アンチパターンを指摘する際、既存データを使って修正する難易度も説明すると、より役立ちます。