netbox-automation-patterns

NetBox 自動化パターン

NetBox 自動化ツールに関する知識は古くなっている可能性があります。 Ansible コレクションのモジュール、Terraform プロバイダーのリソース、イベントルールの動作はリリースごとに変わります。事前学習済みの知識よりも、情報を取得して確認してください。

情報取得元

情報源	URL／方法	用途
NetBox Ansible コレクション	https://github.com/netbox-community/ansible_modules	モジュール一覧、パラメーター、例
Ansible ドキュメント	https://netboxlabs.com/docs/integrations/tool-integrations/netbox-ansible-collection/	統合ガイド
Terraform プロバイダー	https://github.com/e-breuninger/terraform-provider-netbox	リソース、データソース
イベントルールのドキュメント	https://netboxlabs.com/docs/netbox/features/event-rules/	Webhook／スクリプトのトリガー
NetBox MCP サーバー	設定されている場合 — イベントルールとWebhookが存在することを確認	自動化設定の検証

このスキルでは、NetBox を自動化ワークフローに統合する方法を扱います。イベント駆動型トリガー、構成管理、インフラストラクチャ・アズ・コード、CI/CD パイプラインを網羅しています。これは複数の領域にまたがるスキルであり、NetBox を信頼できる情報源として、複数のオープンソースツールを連携させます。

このスキルを読み込むタイミング：

• NetBox の変更をトリガーとするWebhook駆動型自動化を構築するとき
• NetBox を動的インベントリーまたは状態管理ツールとして使うよう Ansible を構成するとき
• Terraform を使って NetBox リソースを管理するとき
• NetBox を組み込んだ GitOps パイプラインを設計するとき

対象外： NetBox のコア管理、プラグイン開発、REST／GraphQL API の基本（netbox-api-integration を参照）。

---

クイックリファレンス：パターンごとに使うツール

目的	ツール	パターン
NetBox の変更に応答する	Event Rules + Webhooks	外部システムへのプッシュ通知
内部で変更に応答する	Event Rules + Custom Scripts	NetBox 内でロジックを実行
NetBox で意図する状態を定義する	Ansible モジュール（netbox.netbox）	宣言型、冪等
NetBox を Ansible インベントリーとして使う	nb_inventory プラグイン	NetBox データを使った動的インベントリー
NetBox とクラウドをまとめて管理する	Terraform（e-breuninger/netbox）	IaC のライフサイクル、状態の追跡
次に利用可能な IP／プレフィックスを割り当てる	Terraform available_* リソース	親からの自動割り当て
NetBox → 構成生成 → デプロイ	GitOps パイプライン	NetBox を信頼できる情報源とする CI/CD

---

イベント駆動型自動化

NetBox のイベントルールシステム（3.7 で導入）は、リアクティブな自動化の基盤です。イベントルールはオブジェクトの変更とアクションを対応付けます。

イベントルールの要点

• トリガーの範囲：オブジェクトの型（複数可）＋イベントの型（作成、更新、削除、ジョブの開始／完了／失敗／エラー）
• 条件：フィルタリングに使う任意の JSON 条件 — たとえば、status.value == "active" の場合にのみ実行します。4.7 以降では、変更そのものも条件で判定できます。{"attr": "status", "op": "changed"} に加えて、snapshots.prechange.<attr>／snapshots.postchange.<attr> のパスと regex 演算子が使えます
• アクションの種類：webhook（外部 HTTP 呼び出し）、script（カスタムスクリプトの実行）、notification（ユーザーへの通知）、さらに 4.7 以降ではプラグインによって登録されたアクションの種類
• 処理：Redis／RQ を介した非同期処理 — ユーザーのリクエストは待機せずに完了します

主なガイドライン

1. 必ず条件で範囲を絞ります — 範囲を絞らないイベントルールは、該当する変更があるたびに実行され、ノイズや負荷の原因になります。条件を使って、対象のステータス、ロール、タグを指定してください。遷移（ステータスが有効になる）時だけ実行するには、4.7 の changed 演算子を使います。4.5／4.6 では、代わりに本文テンプレート内で snapshots.prechange／postchange を比較します。4.7 以降では、存在しない属性を参照する条件はフェイルクローズとなり、ログに記録されます。編集後にルールが「実行されなくなった」場合は、通常、誤字が原因です。

2. イベントは非同期です — すぐに実行されると想定しないでください。イベントは Redis／RQ にキューイングされ、ワーカーによって処理されます。遅延に対応できるレシーバーを設計してください。

3. 適切なアクションタイプを選択します：

   • 外部システム → webhook
   • NetBox 内部のロジック → カスタムスクリプト（netbox-custom-scripts を参照）
   • 人への通知 → 通知グループ

4. 本番環境に移行する前に、組み込みレシーバーでテストします：

   python netbox/manage.py webhook_receiver  # Listens on port 9000
   

5. 集約の動作 — 1 つのリクエスト内で同じオブジェクトに対する変更が複数ある場合、それらは集約されます。イベントをトリガーするのは最終状態のみです。削除イベントでは、後からオブジェクトが存在しなくなるため、データが即時にシリアライズされます。

6. レシーバーの実行時間に上限を設定します（4.7 以降） — webhook ごとに timeout（または WEBHOOK_DEFAULT_TIMEOUT、デフォルトは 60 s）を設定します。これは RQ_DEFAULT_TIMEOUT 未満でなければなりません。レシーバーは速やかに受信を確認し、非同期で処理してください。

ペイロード形式、HMAC 署名、Jinja2 テンプレート、安全性に関する考慮事項については、references/event-rules-and-webhooks.md を参照してください。

---

Ansible との統合

netbox.netbox Ansible コレクション（GPLv3）には、モジュール、動的インベントリー、ルックアッププラグインが用意されています。

主な 3 つのユースケース

1. 状態管理 — モジュール（netbox_device、netbox_ip_address など）を使用して、NetBox オブジェクトが望ましい状態と一致するようにします。すべてのモジュールは state: present/absent による冪等性を備えています。

2. 動的インベントリー — nb_inventory を使用して、NetBox から Ansible インベントリーを生成します。デバイスロール、サイト、リージョン、テナント、タグ、プラットフォームでグループ化できます。

3. データの検索 — nb_lookup を使用して、プレイブック内から NetBox データを検索します。

主なガイドライン

1. 必要がない限り、インベントリーで config_context: False を設定します。4.5／4.6 では、これによりサーバー側でデバイスごとに行われる高負荷なレンダリングを回避できます。4.7 以降ではコンテキストが事前にレンダリングされ、キャッシュされます。また、プラグインは ?exclude=config_context を送信します（すべての 4.7.x で無視されます。4.7.3 の ?omit= 最適化は netbox.netbox 3.23.1 時点では適用されません）。そのため、このオプションの効果は hostvars の削減に限られます。

2. query_filters を使用して、クライアント側でフィルタリングするのではなく、サーバー側でインベントリーの範囲を絞ります。

3. トークンの権限を適切に設定します — インベントリー／ルックアップには読み取り専用トークンを使用し、オブジェクトを作成／変更するモジュールにのみ書き込みトークンを使用します。

4. バージョンの互換性 — コレクションの方針では、NetBox の直近 2 リリースを対象としています。最新リリース（v3.23.1、2026-10）は CI で 4.5 までテストされていますが、4.6／4.7 はまだサポート対象として明記されていません。コレクションのバージョンを固定し、使用する NetBox のマイナーバージョンでテストしてください。

5. device_query_filters でフィルタリングします — たとえば、管理 IP のないデバイスを除外するには has_primary_ip: 'true' を指定します。

モジュールの例、インベントリーの設定、ルックアップのパターンについては、references/ansible-patterns.md を参照してください。

---

Terraform との統合

e-breuninger/netbox Terraform プロバイダーは、NetBox のリソースを Infrastructure as Code として管理します。

主なガイドライン

1. NetBox のバージョンに合わせてプロバイダーのバージョンを固定する — NetBox はマイナーリリースで互換性のない API 変更を行います。プロバイダーの互換性マトリックスを確認してください。v5.6.1 以降は NetBox 4.3～4.6.5 に対応しています。v6.0 のリライト版（2026-09 時点で RC）は 4.6.8～4.6.10 を対象としており、4.7 のサポートを宣言しているリリースはまだありません。

2. available_* リソースのライフサイクルを理解する — netbox_available_ip_address と netbox_available_prefix は作成時に割り当てを行い、「更新」できません。通常のリソースとは異なる固有のライフサイクル動作があります。

3. 状態のドリフトに備える — Terraform の外部で誰かが NetBox を変更すると、次の terraform plan でドリフトが表示されます。ドリフトを修正する方針を決めておいてください。

4. 領域によってカバレッジは異なる — プロバイダーのカバレッジが最も充実しているのは IPAM と仮想化です。その他のモデルでは、リソースのサポートが不完全な場合があります。

5. 読み取り専用の参照にはデータソースを使用する — ほとんどのリソースには対応するデータソースがあり、既存の NetBox オブジェクトを管理せずに参照できます。

プロバイダーの設定、リソースの例、および available_* の割り当てパターンについては、references/terraform-patterns.md を参照してください。

---

GitOps ワークフロー

NetBox は、信頼できる唯一の情報源または状態のミラーとして GitOps パイプラインに統合できます。

一般的なアーキテクチャ

パターン	フロー	最適な用途
Webhook 駆動	NetBox の変更 → webhook → CI/CD → デプロイ	リアルタイムの反応
ポーリング／エクスポート	Cron → NetBox データをエクスポート → Git にコミット → CI/CD	一括設定の生成
Ansible pull	Ansible + nb_inventory → 設定を生成 → プッシュ	Playbook 主導のワークフロー
Terraform による統合管理	Terraform で NetBox とインフラストラクチャをまとめて管理	クラウドと NetBox の同期

主なガイドライン

1. 信頼できる唯一の情報源を決める — NetBox が状態を規定し、Git／自動化でそれを適用するか、Git を情報源として NetBox をミラーにするかを決めてください。二つのマスターを設けないでください。

2. テンプレート用のデータには config context を使用する — Config context は、Jinja2 テンプレートが設定生成時に使用する、デバイス、ロール、またはサイトごとの設定データを提供します。

3. リアルタイムパイプラインには Webhook → CI/CD を使用する — イベントルールと webhook を組み合わせ、NetBox の変更時に GitHub Actions、GitLab CI、または Jenkins をトリガーします。

4. 自動化のヒントとしてタグを使用する — インターフェース、デバイス、またはプレフィックスにタグを付け、自動化の意図を示します（例：インターフェースに「OSPF」タグを付け、OSPF 設定の生成対象に含めます）。

パイプラインのアーキテクチャの詳細と例については、references/gitops-workflows.md を参照してください。

---

横断的な考慮事項

以下は、すべての自動化方式に当てはまります。

• トークン管理：最小限の権限を持つスコープ付きトークンを使用してください。Bearer 認証を使用する v2 トークン（NetBox 4.5 以降）が推奨されます。トークン形式の詳細については、netbox-api-integration を参照してください。

• レート制限：大規模な自動化実行（一括 Ansible play、Terraform の適用）では、NetBox API に過剰な負荷をかけないよう、バックオフを実装してください。4.7 以降では、大規模なカスタム一括書き込みに ?background=true（HTTP 202 + ジョブ URL。結果を取得するにはジョブをポーリング）を使用して、プロキシのタイムアウトを回避できます。netbox-api-integration を参照してください。

• ページネーション：すべてのツール（pynetbox、Terraform プロバイダー、Ansible コレクション）は内部でページネーションを処理しますが、カスタム統合を作成する際は意識してください。NetBox 4.6 では、カーソルベースの start ページネーションが追加されています（深い offset スキャンに代わる効率的な方法です）。netbox-api-integration を参照してください。

• 冪等性：Ansible モジュールは設計上、冪等性を備えています。Terraform は宣言型です。Webhook は送信後の結果を確認しないため、受信側で冪等性を実装してください。

• テスト：CI/CD テスト環境には NetBox 公式 Docker イメージ（netboxcommunity/netbox:v4.7-5.1.1。タグ形式は v<netbox>-<netbox-docker>）を使用してください。統合テスト用に使い捨てのインスタンスを起動します。

---

バージョンに関する注意

NetBox 4.7（2026-09-02）

• スナップショット対応条件：changed／unchanged 演算子、snapshots.prechange.<attr>／snapshots.postchange.<attr> パス、regex 演算子が追加されました。解決できない属性は安全側に倒して失敗し、netbox.event_rules にログを記録します。スナップショットの値は生の値です（status であり、status.value ではありません）。
• Webhook コンテキスト：username と request_id は削除されました。request.user／request.id を使用してください。send_webhook() から username 引数が削除されました。アップグレード前に RQ キューを空にしてください。空にしないと、キューに入った Webhook ジョブが TypeError で失敗します。
• Webhook タイムアウト：Webhook ごとの timeout フィールドと WEBHOOK_DEFAULT_TIMEOUT（デフォルトは 60）が追加されました。RQ_DEFAULT_TIMEOUT より小さくする必要があります。そうでない場合、NetBox は起動または保存を拒否します。
• イベントルール：action_object_type は省略可能になりました。プラグインでアクションタイプ（EventRuleAction）を登録できます。action_is_available は、そのプラグインがなくなったルールを示します。
• 自動化ツールに影響するペイロード／API の変更：選択式のカスタムフィールドは REST で {value,label} オブジェクトになり（Webhook の data にも反映されます）、デバイス／VM の出力にはデフォルトで config_context が含まれます（4.7.3 以降では ?omit=config_context で省略できます。4.7 では ?exclude= は何も行いません）。ipam.Service の protocol／ports は port_mappings に置き換えられる予定です。一括書き込みのエラーはオブジェクトごとになり、一括書き込みでは ?background=true を使用できます。
• エコシステム：netbox-docker 5.x（v4.7-5.1.1）には NetBox 4.7 以降が必要です。Ansible コレクションと Terraform プロバイダーは、4.7 のサポートをまだ表明していません（参考資料を参照）。

NetBox 4.6（2026-05-05）

• Webhook コンテキストに request オブジェクトが追加され、username／request_id は非推奨になりました。
• 大規模な読み取りに対応する、カーソルベースの start ページネーション。
• 4.5 では、Webhook コンテキストに username／request_id のみが存在します。

---

参考資料

ドキュメント	読み込むタイミング
references/event-rules-and-webhooks.md	Webhook 統合の構築、イベントルールの設定、Webhook 配信のデバッグ
references/ansible-patterns.md	NetBox を管理または照会する Ansible プレイブックの作成
references/terraform-patterns.md	Terraform による NetBox リソースの管理
references/gitops-workflows.md	NetBox を組み込んだ CI/CD パイプラインの設計