infrahub-managing-objects

オブジェクト作成

概要

Infrahub オブジェクト（データ）ファイルを作成するための専門的なガイダンスです。 オブジェクトは、スキーマノードに実際のインフラストラクチャデータ ——デバイス、ロケーション、組織、モジュールなど——を投入する YAML ファイルです。

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

既存のスキーマファイル: !find . -name "*.yml" -path "*/schemas/*" -o -name "*schema*" -name "*.yml" 2>/dev/null | head -10

既存のオブジェクトファイル: !find . -name "*.yml" -path "*/objects/*" 2>/dev/null | head -20

引数を指定して呼び出した場合（例: /infrahub:managing-objects DcimDevice spine-01）、 最初の引数を種別として、残りの引数をオブジェクトの詳細として使用します。

使用する場面

• インフラストラクチャオブジェクトの新しいデータファイルを作成する
• デバイス、ロケーション、組織、その他のスキーマノードを投入する
• 階層データ（ロケーションツリー、テナントグループ）を設定する
• ファイルをまたいで関連オブジェクトを参照する
• コンポーネントの子（インターフェース、モジュール）を管理する
• 正しい読み込み順序になるようにオブジェクトファイルを整理する
• 既存のデータファイルの属性値やリレーションシップリンクを更新する
• オブジェクトの読み込みに失敗する理由、または誤った参照が解決される理由をデバッグする

ルールのカテゴリ

優先度	カテゴリ	プレフィックス	説明
CRITICAL	ブランチ優先の読み込み	workflow-	デフォルトブランチではなく、ブランチに読み込みます
CRITICAL	ファイル形式	format-	apiVersion、kind、spec 構造
CRITICAL	値のマッピング	value-	属性、ドロップダウン、参照
HIGH	子	children-	階層／コンポーネントのネスト
MEDIUM	範囲	range-	連番インターフェースの展開
MEDIUM	構成	organization-	命名、読み込み順序、マルチドキュメント
LOW	パターン	patterns-	フラットリスト、デバイス、git リポジトリ

このスキルが依存するスキーマ機能

オブジェクトファイルはスキーマで定義された形状を参照します。スキーマの 設定が欠けていると、同期時に「オブジェクトの読み込みに失敗しました」や 「参照が見つかりません」というエラーになります。データを投入する前に、 上流のスキーマを確認してください:

オブジェクトが...	スキーマは...	参照
ファイルをまたいで別のオブジェクトを参照する	対象ノードに human_friendly_id を定義する必要があります（その形状によってスカラー参照かリスト参照かが決まります）	../infrahub-managing-schemas/rules/display-human-friendly-id.md
ロケーション／親ツリーに属する	parent／children を持つ階層ジェネリックと、完全な種別のピア参照を使用する必要があります	../infrahub-managing-schemas/rules/hierarchy-setup.md
ドロップダウン属性の値を設定する	ドロップダウンの choices を name を持つオブジェクトとして宣言する必要があります（単なる文字列ではありません）。オブジェクトは選択肢の name を参照します	../infrahub-managing-schemas/rules/attribute-defaults-and-types.md
コンポーネントの子をインラインで所有する	親の Component リレーションシップと子の Parent リレーションシップが同じ識別子を共有している必要があり、子には optional: false が必要です	../infrahub-managing-schemas/rules/relationship-component-parent.md
アーティファクトパイプラインのターゲットになる	具象ノードが inherit_from: CoreArtifactTarget を持つ必要があります（ジェネリックではなくノードに設定します）	../infrahub-managing-schemas/rules/extension-artifact-target.md

これらのいずれかが欠けている場合、オブジェクトを読み込む前にスキーマの 更新が必要です。これはオブジェクトの修正ではなく、スキーマのマイグレーションです。

オブジェクトファイルの基礎

---
apiVersion: infrahub.app/v1
kind: Object
spec:
  kind: <NodeKind>          # Schema node kind (e.g., DcimDellServer)
  data:
    - <attribute>: <value>  # List of object instances

apiVersion、kind: Object、spec.kind、spec.data は常に必須です。各 spec ブロックは単一の ノード種別を対象とします。

ワークフロー

オブジェクトデータファイルを作成する際は、次の手順に従ってください。

1. デフォルトブランチではなく、ブランチにロードするよう計画する — ファイルを書き始める前に、このデータをロードする専用ブランチを 決めておき、ロードコマンドを引き渡す際にそれを明示してください。 デフォルトブランチ（--branch を指定しない場合のターゲット — 慣例では main ですが、名前は変更できます）にロードすると、 レビューされていないデータが信頼できる情報源に書き込まれることになり、 そこで誤った一括ロードが行われると、ブランチを破棄する代わりに オブジェクトを1つずつ削除することになります。次の文書をお読みください: rules/workflow-branch-first.md。 デフォルトブランチが妥当なのは、ローカルの使い捨てインスタンスの場合だけです。
2. スキーマを読む — 対象のノード種別、その属性、 リレーションシップ、およびコンポーネントの子や 階層の親を持つかどうかを特定します。
3. ファイル構造を計画する — 必須の YAML 構造については rules/format-structure.md を、 ファイル命名とロード順の規約については rules/organization-load-order.md をお読みください。
4. 属性値をマッピングする — 正しい値フォーマットを使用して 各属性を設定します。属性マッピングについては rules/value-attributes.md を、 リレーションシップ参照については rules/value-relationships.md をお読みください。 オブジェクトが Profile から共有デフォルトを継承する場合や、 Object Template から作成される場合は、 rules/value-profiles-templates.md をお読みください。 リネージを刻印したり値をロックしたりするには、 value + メタデータのマッピングとして記述します — ../infrahub-common/metadata-lineage.md を参照してください（source はリネージ専用であることを 忘れないでください。ロックには owner + is_protected が必要です）。
5. 子を処理する — ノードにコンポーネントの子や 階層のネストがある場合は、 rules/children-components.md と rules/children-hierarchy.md をお読みください。
6. ブランチ上で検証してロードする — YAML 構文を確認し、 参照されたオブジェクトが存在するか、より早いロード順のファイルで 定義されていることを確認してから、ブランチ（--branch）に対して 検証とロードを行います。コマンドとロード前チェックリストについては validation.md を参照してください。

関連リファレンス

• reference.md -- オブジェクトファイル フォーマット仕様
• validation.md -- infrahubctl object validate / object load コマンド、一般的なロードエラー、ロード前チェックリスト
• examples.md -- 本番リポジトリからの15個の 完全なオブジェクトパターン
• ../infrahub-common/infrahub-yml-reference.md -- .infrahub.yml プロジェクト設定
• ../infrahub-common/marketplace-reference.md -- これらのオブジェクトが投入するスキーマが マーケットプレイス由来である場合は、新しいものをモデリングするのではなく それを再利用してください
• ../infrahub-common/metadata-lineage.md -- 値のメタデータ（source、owner、is_protected）: リネージ/所有権の設定と、source が編集アクセスを 制御しない理由
• ../infrahub-common/rules/ -- すべてのスキルで共有される ルール（git 統合、キャッシュ）
• ../infrahub-common/rules/workflow-information-priority.md -- スキルコンテンツが最優先。真のギャップ（例: ノードの削除）に おいて docs.infrahub.app を参照する方法
• ../infrahub-managing-schemas/SKILL.md -- これらのオブジェクトが準拠するスキーマ定義
• rules/ -- カテゴリプレフィックス別の 個別ルール