netbox-diode

NetBox Diode SDK

Diode は、NetBox 向けの gRPC ベースのデータ取り込みサービスです。REST API を使って依存関係の順序やオブジェクト ID を管理する代わりに、オブジェクトを名前で記述すると、Diode リコンサイラーが依存関係を解決し、不足しているオブジェクトを作成して、自動的にアップサートを実行します。

このスキルでは、オープンソースの Python および Go SDK（diode-sdk-python v1.14.2 / diode-sdk-go v1.12.0）を取り上げます。対象は NetBox 4.5–4.7 です。両方の SDK は、NetBox 4.7.0 向けにエンティティセットを再生成しました（python 1.14.0 / go 1.12.0）。Diode サーバーとリコンサイラーはプロプライエタリです。このスキルでは内部実装ではなく、外部から確認できる動作を説明します。

Diode SDK に関する知識は古くなっている可能性があります。 エンティティタイプ、SDK メソッド、リコンサイラーの動作はリリースごとに変化します。事前学習済みの知識よりも、情報を取得して確認することを優先してください。

情報の取得元

情報源	URL / 方法	用途
Diode ドキュメント	https://netboxlabs.com/docs/diode/	アーキテクチャ、導入
Diode Python SDK	https://netboxlabs.com/docs/diode/sdk/python/	Python SDK リファレンス
Python SDK リポジトリ	https://github.com/netboxlabs/diode-sdk-python	ソース、エンティティタイプ、変更履歴
Go SDK リポジトリ	https://github.com/netboxlabs/diode-sdk-go	ソース、エンティティタイプ、変更履歴
Protobuf リファレンス	https://netboxlabs.com/docs/diode/diode-proto/	エンティティスキーマ定義
NetBox MCP サーバー	設定されている場合 — Diode で作成されたオブジェクトが正しく反映されているか確認	取り込み後の検証

Diode と REST API の簡単な比較については、 netbox-api-integration/references/diode-integration.md を参照してください。

最初に：セットアップを確認する

Diode SDK がインストールされ、認証情報が設定されていることを確認してください。

# Python
pip show netboxlabs-diode-sdk

# Environment variables (recommended)
echo $DIODE_CLIENT_ID   # Should be set
echo $DIODE_CLIENT_SECRET  # Should be set

SDK がインストールされていない場合：pip install netboxlabs-diode-sdk

Diode サーバーへの接続を確認するには：

from netboxlabs.diode.sdk import DiodeClient
with DiodeClient(target="grpc://YOUR_DIODE_HOST:8080/diode", app_name="test", app_version="0.1") as client:
    print("Connected")  # Will raise DiodeConfigError if auth fails

---

Diode を使う場面

シナリオ	推奨
ネットワーク検出で大量のオブジェクトを送信する	Diode
一括インポート / 移行	Diode
関連する多数のオブジェクトを作成する（デバイス + インターフェース + IP）	Diode
NetBox データの読み取り / クエリ	REST または GraphQL（Diode は書き込み専用）
単一オブジェクトの CRUD と即時の読み戻し	REST API
複雑なフィルター検索	REST または GraphQL

REST と比べた主な利点： 依存関係の順序付けや ID の検索が不要で、オブジェクトが自動的に作成され、大量処理では gRPC の性能を活用できます。

主な制限： 書き込み専用です。Diode 経由で NetBox にクエリを実行することはできません。

クイックリファレンス

クライアントの種類

クライアント	Python	Go	用途
標準	DiodeClient	diode.NewClient	本番環境での取り込み（Diode サーバーが必要）
ドライラン	DiodeDryRunClient	diode.NewDryRunClient	テスト用の JSON 出力（サーバー不要）
OTLP	DiodeOTLPClient	diode.NewOTLPClient	OpenTelemetry ログレコードとしてエクスポート

認証

推奨される、環境変数を使った OAuth2 クライアントクレデンシャル認証：

export DIODE_CLIENT_ID="your-client-id"
export DIODE_CLIENT_SECRET="your-client-secret"

または、直接渡す方法もあります：client_id= / client_secret=（Python）、WithClientID() / WithClientSecret()（Go）。

Python の最小限の例

from netboxlabs.diode.sdk import DiodeClient
from netboxlabs.diode.sdk.ingester import Device, Interface, IPAddress, Entity

with DiodeClient(
    target="grpc://localhost:8080/diode",
    app_name="my-discovery",
    app_version="1.0.0",
) as client:
    entities = [
        Entity(device=Device(
            name="sw-01",
            device_type="Catalyst 9300",
            manufacturer="Cisco",
            site="NYC-DC1",
            role="Access Switch",
            status="active",
        )),
        Entity(interface=Interface(device="sw-01", name="Gi0/1", type="1000base-t")),
        Entity(ip_address=IPAddress(address="10.0.1.1/24")),
    ]
    response = client.ingest(entities=entities)
    if response.errors:
        for err in response.errors:
            print(f"Error: {err}")

Go の最小限の例

import diode "github.com/netboxlabs/diode-sdk-go/diode"  // exported types live in the diode/ subpackage

client, err := diode.NewClient(
    "grpc://localhost:8080/diode",
    "my-discovery",
    "1.0.0",
    diode.WithClientID("YOUR_CLIENT_ID"),
    diode.WithClientSecret("YOUR_CLIENT_SECRET"),
)
if err != nil { log.Fatal(err) }
defer client.Close()

entities := []diode.Entity{
    &diode.Device{
        Name:       diode.String("sw-01"),
        DeviceType: &diode.DeviceType{Model: diode.String("Catalyst 9300")},
        Site:       &diode.Site{Name: diode.String("NYC-DC1")},
        Role:       &diode.DeviceRole{Name: diode.String("Access Switch")},
        Status:     diode.String("active"),
    },
}
resp, err := client.Ingest(context.Background(), entities)

エンティティの構築

文字列の簡略表記（Python のみ）

PRIMARY_VALUE_MAP に主キーが定義されている Python エンティティでは、ネストされた参照に文字列の簡略表記を使用できます。

# These are equivalent:
Device(name="sw-01", site="NYC-DC1")
Device(name="sw-01", site=Site(name="NYC-DC1"))

主キー以外の属性も設定する必要がある場合は、完全なオブジェクトを使用してください。

Device(name="sw-01", site=Site(name="NYC-DC1", status="active", region="US-East"))

Go には文字列の簡略表記がありません。 ポインターヘルパー（diode.String()、diode.Int()）と完全な構造体型を常に使用してください。

必須フィールド

ほとんどのエンティティで必要なのは、主に識別に使うフィールドのみです（例：Device の name、IPAddress の address）。リコンサイラーが参照先のオブジェクトを自動的に作成します。全項目については references/entity-catalog.md を参照してください。

主な一意性制約

エンティティ	一意性の基準
Device	name + site + tenant
Interface	name + device
IPAddress	address + vrf
Prefix	prefix + vrf
VLAN	vid + group

リコンサイラーの動作

リコンサイラーは、取り込まれたデータを処理するサーバー側のコンポーネントです。主な確認可能な動作は次のとおりです。

1. 依存関係の自動解決 — site="NYC-DC1" を指定すると、存在しない場合は Site が作成されます
2. 名前ベースの照合 — オブジェクトは主な識別フィールドで照合されます
3. 作成順序は不要 — REST とは異なり、デバイスタイプより先にメーカーを作成する必要はありません
4. アップサートのセマンティクス — 一致するエンティティは重複して作成されず、更新されます
5. スラッグの自動生成 — 指定がない場合、slug は name から生成されます
6. 大文字と小文字を区別した照合 — "Site ABC" ≠ "site abc"
7. プロデューサーの来歴情報 — 監査用に、エンティティには app_name / app_version のタグが付けられます

取り込みパターン

バッチ取り込み

1 回の呼び出しで複数のエンティティを送信します。

response = client.ingest(entities=[
    Entity(device=device1),
    Entity(device=device2),
    Entity(interface=iface1),
], metadata={"batch_id": "scan-001"})

チャンク分割による取り込み（大規模バッチ）

gRPC のメッセージサイズ上限は約 4MB です。大きなペイロードには、組み込みのチャンク分割機能を使用してください。

from netboxlabs.diode.sdk import create_message_chunks

for chunk in create_message_chunks(entities):  # default 3MB chunks
    client.ingest(entities=chunk)

Go：client.Ingest(ctx, entities, diode.WithChunking(0))（0 = デフォルトの 3MB）。

ドライランと OTLP

ドライランテスト、再生、OTLP エクスポートについては、references/ingestion-patterns.md を参照してください。

エラー処理

Python の例外階層

DiodeConfigError          # Bad credentials, unreachable auth endpoint
DiodeClientError          # gRPC transport errors (inherits grpc.RpcError; has .code(), .details())
OTLPClientError           # OTLP export failures

注： DiodeClientError は grpc.RpcError を継承しているため、except grpc.RpcError でも捕捉されます。

認証期限切れ時の自動再試行と認証バックオフ

両方の SDK は、UNAUTHENTICATED gRPC エラー（トークンの期限切れ）が発生すると、デフォルトで最大 3 回まで再試行します（max_auth_retries / DIODE_MAX_AUTH_RETRIES）。同じ上限は OAuth2 トークンリクエストにも適用されます。

• トークン取得時のバックオフ (python 1.13+、go 1.10+)：/auth/token から 429、500、502、503 が返された場合、指数バックオフで再試行します（1 秒から倍増し、最大 30 秒、ジッターあり）。429 / 503 では Retry-After が尊重されます。その他の 200 以外のステータスでは、直ちに DiodeConfigError（Python）/ authentication failed エラー（Go）が発生します。
• 事前更新 (go 1.11.1+)：Go クライアントは expires_in で指定された有効期間が終了する約 1 分前にアクセストークンを更新し、同時に発生した更新を 1 回のトークンリクエストにまとめます。Python クライアントは UNAUTHENTICATED レスポンスを受け取った後にのみ再認証します。
• 再試行なしで 1 回だけ試行するには、DIODE_MAX_AUTH_RETRIES=1 を設定します（Go では 0 以下の値は拒否されますが、Python では値の検証は行われません）。

推奨パターン

from netboxlabs.diode.sdk.exceptions import DiodeClientError, DiodeConfigError

try:
    with DiodeClient(target=target, app_name="app", app_version="1.0") as client:
        response = client.ingest(entities=entities)
        if response.errors:  # Per-entity validation errors
            for err in response.errors:
                log.warning(f"Entity error: {err}")
except DiodeConfigError as e:
    log.error(f"Config/auth error: {e}")
except DiodeClientError as e:
    log.error(f"gRPC error: {e.status_code} - {e.details}")

避けるべきパターン

1. IPAddress には CIDR が必要です — "192.168.1.1" ではなく "192.168.1.1/24" を指定します
2. Interface には device が必要です — device の情報がない場合、名前だけでは一意になりません
3. Go には文字列の簡略記法がありません — ネストされた参照はすべて完全な構造体で指定する必要があります
4. Diode は書き込み専用です — データの読み戻しには REST/GraphQL を使用します
5. 大文字と小文字を区別した照合です — 大文字・小文字の不統一により、オブジェクトが重複して作成されます
6. gRPC の上限は 4MB です — 大規模なバッチにはチャンク分割を使用します
7. 文字列の簡略記法には制限があります — ネストされたオブジェクトの属性は設定できません（完全なオブジェクトを使用してください）
8. メタデータは JSON 互換である必要があります — 使用できるのは文字列、数値、ブール値、リスト、辞書のみです
9. 4.7 でのサービスポート — port_mappings=["tcp/53", "udp/53"] を使用してください。protocol + ports も引き続き動作しますが、NetBox 4.7 では非推奨であり（5.0 で API から削除）、単一プロトコルのサービスのみを記述します

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

NetBox 4.7 (2026-09-02) — SDK python 1.14.x / go 1.12.0

• 新しいエンティティタイプ： CoolingSource、CoolingFeed、CoolingIntake、CoolingOutflow、ModuleBayType、および最小限の User（RackReservation.user としてのみ使用）。これらを取り込むのは、対応する Diode プラグインを備えた NetBox 4.7 に対してのみです。
• 新しいフィールド： Device.cooling_method、DeviceType／ModuleType.cooling_method と end_of_life、ModuleType／ModuleBay.module_bay_types、Rack／RackType.cooling_capability と cooling_capacity、Interface.channels と channel_id（チャネル化されたサブインターフェース）、書き込み可能な Interface.mac_address、Service.port_mappings。全一覧は references/entity-catalog.md を参照してください。
• 4.7 で Diode が書き込んだデータの読み戻し： 選択肢のカスタムフィールドは、REST／GraphQL から {"value": ..., "label": ...} オブジェクトとして返されます。デバイス／VM では、config_context がデフォルトで含まれます（4.7.3 以降では ?omit=config_context で省略できます）。netbox-api-integration を参照してください。
• python 1.14.2 (2026-10-06)： DIODE_SKIP_TLS_VERIFY=true を指定しても TLS 接続を維持し、証明書の検証のみをスキップするようになりました。以前のリリースでは、代わりに平文チャネルを開いていました。詳細は references/python-sdk-guide.md を参照してください。

NetBox 4.6 — SDK python 1.12.0 / go 1.9.0

• CableBundle、RackGroup、VirtualMachineType、ScriptModule、DeviceConfig を追加しました。

参考資料

ファイル	読み込むタイミング
references/entity-catalog.md	NetBox 4.7 での追加分を含む、110 種類のエンティティタイプとそのフィールドの全一覧が必要な場合
references/python-sdk-guide.md	Python 統合の構築 — セットアップ、パターン、例
references/go-sdk-guide.md	Go 統合の構築 — セットアップ、パターン、例
references/ingestion-patterns.md	高度なパターン：チャンク化、ドライラン、OTLP、メタデータ

スキル間の参照

• netbox-api-integration/references/diode-integration.md — 概要と Diode と REST の比較
• netbox-discovery — Diode 経由でデータを送信する Orb Agent のネットワークスキャン
• netbox-assurance — Diode で取り込んだデータと意図された状態を比較するアシュアランスエンジン