netbox-data-modeling

NetBoxのデータモデリング

NetBoxのデータモデルに関する知識は古くなっている可能性があります。 利用可能なモデルタイプ、フィールドオプション、リレーションシップのパターンは、リリースごとに変化します。事前学習済みの知識より、情報の取得を優先してください。

情報の取得元

取得元	URL／方法	用途
データモデルのドキュメント	https://netboxlabs.com/docs/netbox/models/	すべてのモデルタイプとフィールド
カスタムフィールドのドキュメント	https://netboxlabs.com/docs/netbox/customization/custom-fields/	フィールドタイプ、検証、フィルタリング
NetBoxリポジトリ	https://github.com/netbox-community/netbox	モデルのソースコード、マイグレーション
NetBox MCP サーバー	設定されている場合 — 既存のデータモデルを確認し、オブジェクトスキーマを調査	現在の構造の把握

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

次の作業が必要な場合は、このスキルを読み込んでください。

• NetBoxのデータモデルをゼロから設計する、または既存のモデルを拡張する
• カスタムフィールド、タグ、コンフィグコンテキストから選択する
• 一括データインポートを計画する（依存関係の順序付け）
• オブジェクト間のリレーションシップや階層パターンを理解する
• サイト、IPAM、デバイス、テナントをモデル化する

APIの仕組み（認証、ページネーション、エラー処理）については、 netbox-api-integrationを参照してください。

NetBoxモデルのアーキテクチャ

基底モデルクラス

すべてのNetBoxオブジェクトは、次の3つの基底クラスのいずれかを継承します。

基底クラス	用途	例	主な特徴
PrimaryModel	実際のインフラストラクチャオブジェクト	Device、Site、Prefix、Rack	説明、コメント、所有者を持つ
OrganizationalModel	分類／タクソノミー	RIR、IPAM Role、ClusterType	一意の名前とスラッグ
Nested group model	再帰的な階層	Region、Location、DeviceRole	自身を参照するparent FK。4.7以降はNestedLtreeGroupModel（PostgreSQL ltree）、4.5～4.6はNestedGroupModel（MPTT）

これら3つはすべて、カスタムフィールド、タグ、エクスポートテンプレート、カスタムリンク、ブックマーク、ジャーナリング、変更ログ、通知、イベントルールを提供するNetBoxModelを継承します。操作するすべてのモデルで、これらの機能を利用できます。

NetBox 4.7以降：階層（Region、SiteGroup、Location、DeviceRole、Platform、TenantGroup、ContactGroup、WirelessLANGroup、およびModuleBay、InventoryItem、InventoryItemTemplate）は、django-mpttではなくPostgreSQLのltreeによって実装されています。lft／rght／tree_id／level列はなくなりました。levelはPythonのプロパティのみであり、フィルターやorder_byには使用できません。名前の変更や親の変更は、子孫へ自動的に連鎖します。parent FK、RESTのparent_id／ancestor_idフィルター、?region_id=のような子孫を含むフィルターに変更はないため、以下のモデリングに関するアドバイスはすべてのバージョンに適用できます。プラグイン／スクリプトのコードでは、get_ancestors()、get_descendants()、get_children()、add_related_count()は引き続き使用できますが、get_root()、get_family()、is_leaf_node()、move_to()、insert_at()は廃止されました。（NestedGroupModelはプラグイン向けに引き続き存在しますが、非推奨です。）

NetBox 4.5：DeviceRoleとPlatformは、OrganizationalModelからネストされたグループモデルに変更されました。4.5～4.7では親子階層をサポートします。

アプリの構成

アプリ	範囲	主なモデル
dcim	物理インフラ	Region、Site、Location、Rack、RackType、Device、DeviceType、Manufacturer、DeviceRole、Platform、Interface、MACAddress、PowerPanel/PowerFeed、CoolingSource/CoolingFeed (4.7)、ModuleBayType (4.7)
ipam	IP アドレス指定	RIR、Aggregate、Prefix、IPAddress、IPRange、VRF、VLAN、VLANGroup、ASN
circuits	接続	Provider、Circuit、CircuitGroup、VirtualCircuit
tenancy	所有権	TenantGroup、Tenant、Contact、ContactAssignment
virtualization	VM	ClusterType、Cluster、VirtualMachine、VMInterface、VirtualDisk
vpn	トンネル／VPN	Tunnel、TunnelGroup、L2VPN、IKE/IPSec ポリシー
wireless	ワイヤレス	WirelessLAN、WirelessLANGroup、WirelessLink

完全な関係マップについては、references/model-map.md を参照してください。

コア設計パターン

1. Site と Location の階層

Region (geographic, recursive)    SiteGroup (functional, recursive)
         \                              /
          └──────── Site ──────────────┘
                      │
                  Location (recursive, within site)
                      │
                    Rack → Device

• Regions = 地理的な区分：大陸 → 国 → 都市圏
• SiteGroups = 機能別の区分：本番、ステージング、ラボ、エッジ
• Site = 物理施設。必要に応じて、Region と SiteGroup の一方または両方に割り当てます
• Locations = サイト内の区画：建物 → 階 → 部屋 → 列
• 地理的なフィルタリングやレポートが必要な場合は、Regions を使用します
• 地域をまたいだ機能別のグループ化が必要な場合は、SiteGroups を使用します
• どちらも任意です。まずはシンプルに始め、フィルタリングの必要性に応じて階層を追加してください

完全な関係マップと階層設計のガイダンスについては、references/model-map.md を参照してください。

2. IPAM の構成

RIR → Aggregate (top-level allocation, e.g., 10.0.0.0/8)
         └── Prefix (auto-nests by CIDR containment)
               ├── child Prefixes
               ├── IPRange
               └── IPAddress

VRF ──── scopes Prefixes, IPAddresses, IPRanges
VLAN ←── linked to Prefix (optional)

主なルール：

• 集約・概要用のプレフィックスには status=container、割り当て済みのプレフィックスには status=active を使用します
• VRF=null はグローバルルーティングテーブルを意味します。アドレス空間が重複する場合は VRF を使用します
• プレフィックスの重複を防ぐには、VRF で enforce_unique=True を設定します
• プレフィックスは自動的にネストされます。既存の 10.0.0.0/16 内に 10.0.1.0/24 を作成すると、ツリーが自動的に構築されます
• サービス（Device または VM 上）：4.7 以降では port_mappings（["tcp/53", "udp/53"]）を使用します。1 つのサービスで複数のプロトコルに対応できます。protocol + ports は非推奨で（5.0 で削除）、複数プロトコルのサービスでは読み戻すと null になります。4.5～4.6 では protocol + ports を使用し、プロトコルごとにサービスを作成します。

スコープパターン（4.x）： Prefix と VLANGroups は CachedScopeMixin を使用します。これは、site の直接 FK ではなく、汎用 FK（scope_type + scope_id）を使用するものです。VLANGroup のスコープには Region、SiteGroup、Site、Location、Rack、ClusterGroup、Cluster（この全セットに対応したのは 4.5 以降）が指定できます。また、4.6 以降は RackGroup も指定できます。

# Setting scope via API
{"prefix": "10.0.1.0/24", "scope_type": "dcim.site", "scope_id": 42}

3. デバイスモデリング

Manufacturer → DeviceType (template with component templates)
                              ↓ (instantiation)
DeviceRole + Site + DeviceType → Device (with auto-created components)

• DeviceType はハードウェアのテンプレートを定義します。インターフェーステンプレート、電源ポート、モジュールベイが含まれます
• デバイスを作成すると、その DeviceType のテンプレートからコンポーネントが自動作成されます
• Modules はデバイスを拡張します。モジュールタイプは、モジュールベイに挿入する追加のコンポーネントテンプレートを定義します
• DeviceRole（4.5：階層型）— 設定コンテキストの照合と分類に使用します
• Platform（4.5：階層型）— OS／ファームウェアのファミリーです。必要に応じて Manufacturer に関連付けられます
• Racks：RackType（Manufacturer → RackType → Rack）を割り当て、物理寸法は RackType に設定します。4.7 では、ラックごとの form_factor、width、outer_width/height/depth/unit フィールドは非推奨です。5.0 では削除され、rack_type が必須になります。u_height、starting_unit、desc_units、mounting_depth は Rack に残ります。

MACAddress は NetBox 4.2 以降、独立したモデルです（1 つのインターフェースにつき複数のアドレスを設定でき、そのうち 1 つがプライマリです）。4.5～4.7 では、Interface の単なるフィールドではありません。4.7 以降：Interface／VMInterface の mac_address は書き込み可能です。書き込むと、1 回の呼び出しでプライマリ MACAddress が作成または更新されます。MACAddress.is_primary は読み取り専用です。

NetBox 4.7 以降のデバイスモデリングの追加機能（すべて任意。4.5～4.6 では無視してください）：

• ModuleBayType — 各ベイに適合するモジュールの許可リストです。ModuleBay、ModuleBayTemplate、ModuleType の M2M フィールド module_bay_types で指定します。ベイとモジュールタイプの両方でタイプが指定され、共通するタイプがない場合にのみ、取り付けが拒否されます。テンプレートのタイプは、インスタンス化されたベイに引き継がれます。Module.is_bay_compatible／ModuleBay.is_module_compatible は読み取り専用です。
• Module relocation — Module の module_bay に PATCH を適用すると、モジュールを移動できます（デバイスはベイから導出されます）。モジュールのサブツリーも一緒に移動します。デバイスをまたいで移動するには、移動対象のコンポーネントにケーブル、IP、VLAN、その他のトポロジーがないことが必要です。
• チャネル化インターフェース — 物理親インターフェースに channels（例：4）を設定し、チャネルごとに parent と channel_id（1 から始まる番号）を設定したサブインターフェースを作成します。タイプには channel（または実際のトランシーバータイプ）を指定します。ケーブルは親インターフェースに接続し、NetBox はチャネルごとに経路をトレースします。InterfaceTemplate にも同じフィールドがあります。ブレークアウトを、その場限りの仮想インターフェースとしてモデル化しないでください。
• DeviceType／ModuleType の end_of_life 日付 — カスタムフィールドではなく、ライフサイクル計画に使用します。
• 冷却 — Device／DeviceType／ModuleType の cooling_method（air／liquid／hybrid／immersion）。デバイス作成時には、タイプから引き継がれます。Rack／RackType の cooling_capability（air-only／hybrid／liquid-only）と cooling_capacity（kW）。ラックはタイプから引き継ぎます。冷却トポロジーの詳細は §3a を参照してください。

3a. 電源と冷却（冷却は 4.7 以降）

PowerPanel (site, location?) → PowerFeed (→ rack?) → PowerPort ⇄ PowerOutlet (device components)
CoolingSource (site, location?) → CoolingFeed (→ rack?) → CoolingIntake ← CoolingOutflow (device components)

• CoolingSource = 施設の冷却設備（チラー、冷却塔、ドライクーラー、CRAC／CRAH）。site は必須、location は任意です。type、status、fluid_type、cooling_capacity（kW）を指定します
• CoolingFeed = 冷却源から rack（任意）までの冷却液ループ 1 系統（供給＋戻り）。status、cooling_capacity、max_flow／max_flow_unit、tenant を指定します
• CoolingIntake／CoolingOutflow = デバイスのコンポーネント（DeviceType／ModuleType のテンプレートを使用）。インテークの cooling_outflow は上流のアウトフロー（通常は別のデバイスである CDU 上のもの）を参照します。アウトフローの cooling_intake は同じデバイス上のインテークを参照します
• CDU、マニホールド、リアドア熱交換器は、インテーク／アウトフローのコンポーネントを備えた通常のデバイス（ゼロ U）としてモデル化します。CDU モデルはありません。ホースは参照であり、ケーブルではありません。デバイスに対応するフィードは、そのラックから導出されます
• エンドポイント：dcim/cooling-sources/、dcim/cooling-feeds/、dcim/cooling-intakes/、dcim/cooling-outflows/、および -templates/

4. テナントの割り当て

テナントは、Site、Device、Rack、Prefix、VLAN、VRF、Circuit、VM、Cluster、IPAddress など、ほぼすべての PrimaryModel において任意の外部キーです。

パターン： TenantGroup（階層）→ Tenant → オブジェクトに割り当て

ユースケース：

• MSP の顧客の分離
• 社内部門の所有権
• コストセンターの追跡

アンチパターン： Tenant に 2 つの次元（例：「顧客」と「部門」の両方）を担わせないでください。主要な所有権の次元には Tenant を使用し、二次的な次元にはカスタムフィールドまたはタグを使用してください。

5. 連絡先の割り当て

連絡先には汎用リレーションパターンを使用します。ContactAssignment は、任意のオブジェクトを ContactRole を持つ Contact に関連付けます。

Contact + ContactRole + any object → ContactAssignment

ContactGroups は連絡先を階層的に整理します。異なる役割を持つ複数の連絡先を、同じオブジェクトに割り当てることができます。

データモデルの拡張

判断：カスタムフィールド、タグ、Config Context のどれを使うか

質問	→ カスタムフィールド	→ タグ	→ Config Context
yes/no を超える値がありますか？	✅	❌	✅
多くのオブジェクトタイプに適用されますか？	❌（スコープ指定）	✅	❌（デバイス／VM のみ）
これでフィルタリング／検索する必要がありますか？	✅	✅	❌（直接は不可）
自動化／設定レンダリングで使用しますか？	❌	❌	✅
階層から継承／計算されますか？	❌	❌	✅
オブジェクトごとに固有の値ですか？	✅	❌	❌（条件に基づいて一致）

例：

• 保証期限 → カスタムフィールド（デバイスごと、型指定あり、フィルタリング可能）
• PCI 準拠 → タグ（ブール値のような用途、複数オブジェクトで使用）
• サイトのデバイス向け NTP サーバー → config context（継承され、設定レンダリングで使用）

すべてのフィールドタイプと判断の指針については、references/custom-field-types.md を参照してください。

カスタムフィールド — 主なポイント

• タイプ： text、longtext、integer、decimal、boolean、date、datetime、URL、JSON、selection、multi-selection、object、multi-object（13 タイプ — 4.7 まで変更なし。独立した「color」タイプはありません）
• 4.7 以降の読み取り形式： selection／multi-selection の値は {"value": "prod", "label": "Production"} オブジェクトとして返されます（REST および GraphQL）。書き込み時は引き続き生の値を使用します。4.5～4.6 では生の値が返されます
• 4.7 以降： URL フィールドは ALLOWED_URL_SCHEMES に照らして検証されます（スキームのない値には https://… が付与されます）。nulls_first は空の値を並べ替える位置を制御します。読み取り専用の status（active／provisioning／deleting）があり、デフォルト値付きの作成と削除は、対象オブジェクト数が BULK_UPDATE_CHUNK_SIZE を超える場合にバックグラウンドジョブとして実行され、フィールドは active になるまで有効になりません
• JSON フィールドでは、値に JSON Schema を適用するための任意の validation_schema（4.6 以降）を指定できます
• selection／multi-selection の選択肢セットでは、選択肢ごとの色（choice_colors、4.6 以降）をサポートします。リリースノートで「color custom field」と呼ばれているのはこれであり、新しいフィールドタイプではありません
• object／multi-object フィールドは他の NetBox オブジェクトとのリレーションを作成します。テキストフィールドに名前を保存するより、こちらを優先してください
• 作成時に特定のオブジェクトタイプにスコープを設定します
• UI で整理するには、group_name を使ってフィールドをグループ化します
• 表示設定： always／if-set／hidden
• API でのフィルタリング：?cf_<field_name>=<value>

タグ — 主なポイント

• プロパティ：name、slug、color、description
• object_types を関連するモデルに制限します（すべてのタグをどこでも表示できるようにしないでください）
• API でのフィルタリング：?tag=<slug>
• 値はなく、付与／未付与のみです。値が必要な場合は、カスタムフィールドを使用してください

Config Contexts — 主なポイント

• regions、site_groups、sites、locations、device_types、roles、platforms、cluster_types、cluster_groups、clusters、tenant_groups、tenants、tagsを介して、デバイス／VMに対応付けられるJSONデータです
• 重みベースのマージ： 重みの小さいものから先にマージされ、重みの大きいものが競合する値を上書きします
• dictにはディープマージ、リストには置換を適用します
• ローカルコンテキストデータ（デバイス／VMに直接設定されたもの）が常に優先されます
• ConfigContextProfileはJSON Schemaによる検証を適用します
• レンダリング済みの出力： 4.7以降では、config_contextは事前にレンダリングされ、オブジェクトにキャッシュされます。すべての4.7.xで?exclude=config_contextは無視されます。4.7.0～4.7.2では常に読み込まれます。4.7.3以降では、?omit=config_context（または?fields=／?brief=True）を指定すると、DBアノテーションが再び省略されます。4.5～4.6では、デバイス／VMの一覧取得時に?omit=config_context（4.5.2以降）または?exclude=config_contextを指定して除外してください。netbox-api-integrationを参照してください

依存関係の順序

データを一括インポートする場合は、依存関係の順序に従ってオブジェクトを作成します。依存するオブジェクトを作成する前に、必須のFKが存在している必要があります。

大まかな順序：

1. 組織モデル（RIR、Manufacturer、ClusterType、DeviceRole、Platform、IPAM Role、RackRole、ModuleBayType (4.7)）
2. 分類階層（Region、SiteGroup、TenantGroup、Tenant）— 親を子より先に作成します
3. Sites → Locations → RackTypes（Manufacturerが必要）→ Racks → PowerPanels／CoolingSources (4.7) → PowerFeeds／CoolingFeeds (4.7)
4. DeviceTypes／ModuleTypes（Manufacturerが必要です。4.7では、ModuleTypeより先にModuleBayTypeが必要です）
5. Devices（DeviceType、DeviceRole、Siteが必要です）→ Modules → チャネルサブインターフェース (4.7)
6. IPAM：VRFs → Aggregates → Prefixes → IP Addresses
7. VLANGroups → VLANs
8. Clusters → VMs
9. Circuits（Provider、CircuitTypeが必要です）
10. カスタムフィールド、タグ、config contexts（いつでも作成できますが、早めの作成が最適です）

順序の完全な一覧は、references/dependency-order.mdを参照してください。

アンチパターン

1. フラットなサイト構造 — 50以上のサイトがあるのに、Regions／SiteGroupsを使用しないことです。フィルタリングやレポート作成が困難になります。
2. 関係性をテキストのカスタムフィールドで表現する — 名前をテキストとして保存するのではなく、オブジェクト／複数オブジェクト型のカスタムフィールドを使用します。
3. 同じ分類軸の重複 — cf_environment=productionとタグproductionの両方を設定することです。どちらか一方を選びます。
4. 依存関係の順序を無視する — サイトやデバイスタイプより先にデバイスを作成することです。FKが不足してスクリプトが失敗します。
5. すべてをグローバルVRFに配置する — VRFを使って、重複するアドレス空間を適切にモデル化します。
6. tenantの過剰利用 — tenantを2つの目的に使用することです。分類軸は1つに限定し、残りにはカスタムフィールドを使用します。
7. 巨大なconfig contexts — 設定全体ではなく、変数を保存します。レンダリングにはconfig templatesを使用します。
8. 未使用のロール — DeviceRoleはconfig contextの照合に使用されます。ロールを慎重に設計し、4.5の階層構造を使用します。
9. ステータス未設定のPrefix — 必ずcontainer／active／reservedを設定します。containerは組織的な用途、activeは割り当て済みを表します。
10. PKのハードコード — 検索にはname／slugを使用します。PKは環境によって異なります。
11. RackTypeなしのラック — ラックごとの寸法は4.7で非推奨となり、5.0で削除されます。物理モデルごとにRackTypeを定義して割り当てます。
12. 冷却／ライフサイクルデータをカスタムフィールドに保存する (4.7+) — cf_cooling／cf_eolではなく、cooling_method、cooling_capability／cooling_capacity、end_of_lifeと冷却モデルを使用します。

バージョンに関する注意事項

NetBox 4.7（2026-09-02）— 4.7 以降のみ対応。≥ 4.7.3 を推奨（4.7.0/4.7.1 ではトークンの平文がジョブ結果に漏れていました。4.7.3 ではブランチに安全なバックグラウンド書き込みと、config context の omit 最適化が追加されています）

変更	影響
ltree による階層構造	level はフィルタリング／並べ替えができません。名前の変更は連鎖して反映されます。プラグインでは NestedGroupModel を NestedLtreeGroupModel に置き換えてください。4.7.0 の pg_dump から復元すると連鎖トリガーが失われます — rebuild_ltree_paths --check を実行してください（4.7.1 で修正済み）
冷却モデル	CoolingSource → CoolingFeed → CoolingIntake/CoolingOutflow（およびテンプレート）。Device/DeviceType/ModuleType に cooling_method、Rack/RackType に cooling_capability/cooling_capacity を追加
ModuleBayType	ModuleBay/ModuleBayTemplate/ModuleType に多対多の module_bay_types を追加。両側でタイプが宣言されている場合は互換性を検証します。エンドポイントは dcim/module-bay-types/
チャネル化インターフェイス	親に channels、サブインターフェイスに channel_id と parent、インターフェイスタイプに channel を追加。ケーブルは親に 1 本、パスはチャネルごとに 1 つです
モジュールの移動	PATCH で module_bay を指定するとモジュールを移動できます（アクティブなトポロジーがなければ、デバイス間の移動も可能です）
サービスの port_mappings	protocol と ports を置き換えます（非推奨で、5.0 で削除）。複数プロトコルのサービスに対応します
Rack フィールドの非推奨化	Rack の form_factor、width、outer_* は RackType に移行してください。5.0 では rack_type が必須です
end_of_life	DeviceType/ModuleType の日付
インターフェイスの mac_address を書き込み可能に	プライマリの MACAddress を作成／更新します。MACAddress.is_primary
カスタムフィールドの選択値	{value, label} として返されます。書き込み時は生の値を使用します。URL フィールドは ALLOWED_URL_SCHEMES に対して検証されます。nulls_first。バックグラウンドプロビジョニングを伴う読み取り専用の status
設定コンテキストのキャッシュ	事前にレンダリングされます。4.7.x では ?exclude=config_context は常に無視されます。4.7.3 以降では ?omit=config_context により、再び DB 処理をスキップできます

NetBox 4.5

変更	影響
DeviceRole → NestedGroupModel	ロール階層を設計できます（例：network → network/router、network/switch）
Platform → NestedGroupModel	プラットフォーム階層を設計できます（例：cisco-ios → cisco-ios/xe、cisco-ios/xr）
MACAddress の独立モデル化（4.2 以降）	MAC アドレスは単なるインターフェイスのフィールドではなく、第一級のオブジェクトです — サポートされるすべてのバージョンに適用されます
VirtualDeviceContext	マルチテナントデバイス上の VDC をモデル化します
Prefix/VLANGroup の CachedScopeMixin	site の直接 FK ではなく、scope_type/scope_id を使用します
v2 API トークン	Bearer nbt_<key>.<secret> 形式を使用します
ConfigContextProfile	JSON Schema に照らして設定コンテキストのデータを検証します
VirtualCircuit、CircuitGroup	新しい回線モデリングのオプション
VirtualDisk	VM 向けのディスクモデリング

NetBox 4.6（すべて4.6以降のみ。4.5.xのインスタンスでは使用できると想定しないでください）

変更	影響
VirtualMachineType	再利用可能なVM分類（DeviceTypeと同様）で、デフォルトのプラットフォーム／vCPU／メモリを指定できます。エンドポイントは virtualization/virtual-machine-types/ です。VMにオプションの virtual_machine_type FKが追加されます
VMの cluster がオプションに	VMは、サイト、クラスター、デバイスの少なくともいずれか1つに関連付ける必要があります。Deviceに直接接続するクラスターなしのVMが、正式にサポートされるようになります
CableBundle	ケーブルを論理的にグループ化します（コンジット／トランク／ハーネス）。Cable.bundle FKは任意で、トレースには影響しません。エンドポイントは dcim/cable-bundles/ です
RackGroup（フラット）	Locationとは別に、ラックを階層化せずに分類します（列／通路／ケージ）。Rack.group FKを使用します。エンドポイントは dcim/rack-groups/ です。VLANGroupのスコープに指定できます
VLANGroupのスコープにrackgroupを追加	VLANGroupのスコープ種別に rackgroup が追加されます（全種別：region/sitegroup/site/location/rackgroup/rack/clustergroup/cluster）
ASNの role	ASNにipam Roleを設定できるようになります（Roleはプレフィックス、VLAN、およびASNを分類します）
JSON CFの validation_schema	JSONカスタムフィールドでJSON Schemaによる検証を適用できます
選択肢の色	選択肢／複数選択の選択肢セットに、選択肢ごとの色を設定できます（choice_colors）。新しいフィールド種別ではありません
v1 APIトークン	4.6で非推奨となり、5.0で削除されます。v2の nbt_ トークンは、作成時に一度だけ平文で返されます（4.6.1）