infrahub-managing-schemas

Infrahub Schema Creator

概要

Infrahub スキーマの設計と構築に関する専門的なガイダンスです。スキーマは、ノード(具象型)、ジェネリック(抽象基底型)、属性、リレーションシップ、拡張を定義する YAML ファイルです。

プロジェクトのコンテキスト

このプロジェクト内の既存のスキーマ: !find . -name "*.yml" -path "*/schemas/*" -o -name "*schema*" -name "*.yml" 2>/dev/null | head -20

Infrahub 設定(存在する場合): !cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"

引数を付けて呼び出された場合(例: /infrahub:managing-schemas Ipam Vlan VlanGroup)、最初の引数を名前空間として、残りの引数をノード名として使用します。

使用する場面

• 新しいデータモデルやスキーマノードを設計するとき
• 既存のスキーマに属性やリレーションシップを追加するとき
• 階層的なロケーションツリーやコンポーネント/親のパターンを設定するとき
• 表示プロパティ(human_friendly_id、display_label)を構成するとき
• 既存のスキーマを移行またはリファクタリングするとき
• スキーマ検証エラーをデバッグするとき

ルールのカテゴリ

優先度	カテゴリ	プレフィックス	説明
CRITICAL	ブランチファーストの変更	workflow-	スキーマをデフォルトブランチではなくブランチにロードする
CRITICAL	命名	naming-	名前空間、ノード、属性の命名
CRITICAL	リレーションシップ	relationship-	ID、ピア、コンポーネント/親、on_delete
HIGH	属性	attribute-	デフォルト値、ドロップダウン、計算済み Jinja2、ブランチ非依存、非推奨
HIGH	階層	hierarchy-	階層的なジェネリック、親/子
HIGH	表示	display-	human_friendly_id、order_weight、order_by、メニュー配置
MEDIUM	拡張	extension-	extensions ブロックによるファイル間参照、アーティファクトターゲット
HIGH	一意性	uniqueness-	制約の形式、必須リレーションシップ、スコープ。ジェネリックか具象 kind か
MEDIUM	移行	migration-	属性の追加/削除、state: absent
MEDIUM	ファイルフォーマット	format-	正規のキー順序、infrahubctl schema format(オフライン)
HIGH	検証	validation-	ロード時の文字列長の上限(description / label / identifier)、一般的なエラーメッセージ、事前チェックリスト
HIGH	再利用	reuse-	モデリングの前にマーケットプレイスを確認する。参照する前に kind が存在することを検証する。ファイル単位ではなくジェネリック単位で採用する
HIGH	ジェネリックメンバーシップ	generic-	ジェネリックの実装者の集合はインターフェースです。参加すると、それを対象とするすべてのクエリ、制約、コンシューマーが変わります

スキーマファイルの基本

---
# yaml-language-server: $schema=https://schema.infrahub.app/infrahub/schema/latest.json
version: "1.0"

generics:      # Abstract base definitions (shared attributes/relationships)
  - ...
nodes:         # Concrete object types
  - ...
extensions:    # Add attributes/relationships to existing nodes from other files
  nodes:
    - ...

IDE 検証のために常に $schema コメントを含めてください。 トップレベルで必須なのは version のみです。

下流の利用者向けの設計

スキーマノードが単独で存在することはほとんどありません。それを確定する前に、 プロジェクトの他の部分でどのように使用されるかを確認し、 それらの機能が必要とする継承 / 設定を追加してください。

ノードが次のような場合	スキーマに追加するもの	参照
アーティファクトのターゲットになる（artifact_definition から参照されるグループメンバー）	具象ノードに inherit_from: [..., CoreArtifactTarget]	rules/extension-artifact-target.md
ジェネレーターのターゲットになる（generator_definition から参照されるグループメンバー）	具象ノードに inherit_from: [..., CoreArtifactTarget]	rules/extension-artifact-target.md
カスタムサイドバーメニューに表示される	自動メニューが手動エントリを重複させないように include_in_menu: false	../infrahub-managing-menus/rules/schema-integration.md
オブジェクトテンプレート（ノードとそのコンポーネントの子）としてクローン可能にする	generate_template: true	rules/extension-object-template.md
多数のインスタンス間で共有されるデフォルト値を提供する	generate_profile: true（+ Profile インスタンス）	rules/extension-object-profile.md
アップロードされたファイル（PDF、画像、Visio、KMZ、契約書など）を保存する	具象ノードに inherit_from: [..., CoreFileObject]	rules/extension-file-object.md
UI のリストや API 全体で安定した名前で表示される	human_friendly_id と display_label	rules/display-human-friendly-id.md

この監査が、「検証は通る」スキーマと「より広いプロジェクトで実際に機能する」スキーマの違いを生みます。これを省略すると、下流の機能を接続した時点でスキーママイグレーションが避けられなくなりますが、その時点ではすでにデータが読み込まれています。

タスクが複数のスキル（スキーマ + 変換、スキーマ + メニューなど）にまたがる場合は、境界を排他的に扱うのではなく、両方のスキルのルールを一緒に読み込んでください。

より低コストなレイヤーのための設計

スキーマの選択によって、ダウンストリームでの Python や非正規化データの必要性をなくせます。これを正しく行うにはスキーマが最も低コストな場所です — 後から修正すると、すでに読み込まれたデータのマイグレーションが必要になります。フィールドやノードを追加する前に、組み込み機能や構造的な機能ですでにカバーされていないかを確認してください:

シグナル	より低コストなレイヤー	参照ルール
あらゆるドメインをゼロから構築する場合（マーケットプレイスは DCIM / ロケーション / 組織のはるか先まで公開しています — ルーティング、セキュリティ、コンピュートなど多数）	マーケットプレイス全体を検索し、公開されているスキーマを再利用します: infrahubctl marketplace get <ns>/<name> の後に inherit_from。採用は依存関係であり、無償ではありません: kind のティアを確認し、来歴を記録します	yagni-reuse-existing-marketplace-schema、reuse-verify-kind-availability、reuse-evaluate-per-generic
リレーションシップをたどって到達できるノードに値をコピーする場合（device.location.region.code が存在するのに region_code を定義するなど）	間接的なリレーションシップのたどり方。コンシューマーにリンクをたどらせます	yagni-denormalized-vs-indirect-relationship
複数の兄弟ノードが同じ属性とリレーションシップを繰り返している場合	ジェネリックを抽出して inherit_from します	yagni-duplicate-shape-not-extracted-to-generic
カスタム IP アドレス / プレフィックスノードを定義する場合	組み込みプリミティブ（BuiltinIPAddress、BuiltinIPPrefix）を inherit_from します。VLAN プリミティブはコアではなくマーケットプレイスで公開されているため、ピアリングする前に確認してください	yagni-custom-domain-primitives-instead-of-builtin、reuse-verify-kind-availability
相手側に逆リレーションシップがない Attribute + cardinality: one のリレーションシップ	対応する逆リレーションシップを宣言し、コンシューマーが Python ではなくクエリでフィルタリングできるようにします	yagni-missing-inverse-forces-python-filter
オブジェクト間で決して変化しない単一の値を保持する Profile	属性の default_value を使います — Profile は値が変化する場合や中央で再調整される場合にのみ、そのコストに見合います	yagni-profile-over-default
ライブ値を共有するために Object Template を使ったり、ノードの子コンポーネントを複製するために Profile を使ったりする場合	ツールを意図に合わせます: Profile はライブ値を共有し、Object Template は構造を複製します	yagni-template-profile-confusion
どの Profile やテンプレートも使わないうちに generate_profile / generate_template を有効にする場合	デフォルト値 / 複製のワークフローが実際に存在するときにフラグを有効にします	yagni-unused-generate-flag

これらは、チェック、トランスフォーム、ジェネレーターのスキルにある「Python を書く前に」というガイダンスに対応するスキーマ側の項目です。リポジトリ監査ツールはこれらを修正コストに関する参考所見として指摘します。設計時に捕捉すれば、所見も後からのマイグレーションも回避できます。

ワークフロー

スキーマを作成または変更する際は、次のステップに従ってください:

1. 要件を収集する — ノードの種類、その属性、およびそれらが互いにどのように関係するかを特定します。階層、ドロップダウン、表示要件について確認してください。
2. まずマーケットプレイスを確認する — あらゆるドメインをゼロからモデリングする前に、Infrahub マーケットプレイス全体を検索し、公開済みのスキーマがそれをカバーしている場合は再利用してください：infrahubctl marketplace get <namespace>/<name> を実行し、取得したジェネリックを inherit_from して、サイト固有の属性のみを追加します。ディスカバリー、コレクション（-c）、エアギャップのフォールバック、および必要な SDK バージョンについては、../infrahub-common/marketplace-reference.md を参照してください。公開されているファイルはジェネリックごとに判断し、単位として扱わないでください。そして、採用するものについては出所を記録してください（rules/reuse-evaluate-per-generic.md）。継承またはピアとして指定するすべての kind が、クリーンなインスタンス上に実際に存在することを、依存する前に確認してください。Core/Builtin というプレフィックスは慣例であり、保証ではありません。また、プラットフォームコアには location kind が存在しません（rules/reuse-verify-kind-availability.md）。
3. 関連するルールを読む — 命名制約については rules/naming-conventions.md を、属性の種類とデフォルトについては rules/attribute-defaults-and-types.md を、双方向リレーションシップの設定については rules/relationship-identifiers.md を読んでください。いずれかのノードがジェネリックを継承する場合は、rules/relationship-peer-kind.md も読んでください。リレーションシップのピアは、それを宣言するジェネリックによって固定され、どの実装者もそれを狭めることはできません。したがって、どのリレーションシップをジェネリック上に置くかという決定は、後ではなくここで行われる一方通行の選択です。これから書こうとしているすべての cardinality: one は、形だけでなく書き込み時のデータ制約でもあるため、ロードが失敗した後ではなく、選択している間に rules/relationship-cardinality-consequences.md を読んでください。
4. スキーマ YAML を構築する — $schema コメントと version: "1.0" から始めます。まずジェネリックを定義し（存在する場合）、次にノードを定義します。ステップ 3 の命名、表示、およびリレーションシップのルールを適用します。ノードがすでに実装者を持つジェネリックに参加する場合、その inherit_from 行は公開済みインターフェースへの変更として扱ってください。それは schema check を通過し、マイグレーションを生成せず、それでもそのジェネリックに対するすべてのクエリ、制約、およびコンシューマーが返す内容を変えます。rules/generic-membership-is-a-published-interface.md を参照してください。
5. 下流のコンシューマーを監査する — 上記の「Designing for Downstream Consumers」の表を確認してください。いずれかのノードがアーティファクトまたはジェネレーターのターゲットになる場合は、rules/extension-artifact-target.md に従って、今すぐその inherit_from に CoreArtifactTarget を追加してください。後から追加すると、ロード済みデータに対してスキーママイグレーションが強制されます。
6. 表示プロパティを設定する — rules/display-human-friendly-id.md と rules/display-order-weight.md に従って、human_friendly_id、display_label、および order_weight を設定します。ある kind にデフォルトのリスト順序が必要な場合は、rules/display-order-by-scope.md に従って order_by を設定します — ジェネリック上では、そのジェネリック自身が宣言するフィールドに対してのみ解決されます。
7. ファイルをフォーマットする — コミット前にキーを正規の順序に並べて、差分を小さく保ちます。あなたの infrahubctl が対応している場合は infrahubctl schema format を実行します（オフライン、サーバー不要）。そうでない場合は、順序を手作業で書いてください。rules/format-schema-files.md を参照してください。
8. ブランチ上で検証してロールアウトする — infrahubctl schema check を実行し、validation.md と rules/validation-common-errors.md に従ってエラーを修正します。次に、デフォルトブランチ（慣例では main ですが、名前は変更される可能性があります）ではなく、専用ブランチで変更を適用します：infrahubctl branch create <name> → schema check --branch <name> → schema load --branch <name> を実行し、問題ないことを確認したら提案された変更を介してマージします。スキーマのロードは、ロード済みデータに対してマイグレーションを即座に実行するため、共有サーバー上のデフォルトブランチではプレビューもステップごとの取り消しもできません — ブランチなら可能です。rules/workflow-branch-first.md を参照してください。デフォルトブランチが妥当なのは、ローカルの使い捨てインスタンス上のみです。

知っておくべき本番環境のパターン

繰り返し登場する 7 つのパターン — 計算された Jinja2 属性、 カスケード削除と no-action 削除の比較、メニューの可視性、 ブランチに依存しない識別子、アーティファクトのターゲット、オブジェクト テンプレート、ファイルオブジェクト — については、examples.md の 冒頭で説明しています。スキーマを確定する前にこれらを読んでください。 各パターンはゼロから構築するときには見落としやすく、 データをロードした後に後から取り入れるのは高コストです。

参考資料

• reference.md -- ノード、ジェネリクス、属性、リレーションシップの 完全なプロパティ表
• examples.md -- 本番リポジトリの 完全なスキーマパターン
• validation.md -- infrahubctl コマンド、移行戦略、検証前チェックリスト
• ../infrahub-common/infrahub-yml-reference.md -- .infrahub.yml のプロジェクト設定
• ../infrahub-common/marketplace-reference.md -- 公開済みのマーケットプレイススキーマとコレクションの再利用 (infrahubctl marketplace get / list / search / show、エアギャップ)
• ../infrahub-common/rules/ -- すべてのスキルで共有されるルール (Git 連携、キャッシュ)
• ../infrahub-common/rules/workflow-information-priority.md -- スキルの内容を優先。真に不足がある場合 (例: ノードの削除) に docs.infrahub.app を参照する方法
• rules/ -- カテゴリプレフィックスごとの 個別ルール