infrahub-managing-transforms

Infrahub Transform Creator

概要

Infrahub トランスフォームを作成するための専門的なガイダンスです。 トランスフォームは Infrahub のデータをさまざまな形式 -- JSON、テキスト、CSV、デバイスコンフィグ、または任意のテキストベースの 出力 -- に変換します。Python クラスまたは Jinja2 テンプレートを使用します。

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

Infrahub 設定: !cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"

既存のトランスフォーム: !find . -name "*.py" -path "*/transforms/*" -o -name "*.j2" -path "*/templates/*" 2>/dev/null | head -20

使用する場面

• データ変換の構築 (Infrahub データ -> 別の形式)
• インフラストラクチャデータからのデバイスコンフィグの生成
• CSV レポート、ケーブルマトリクス、またはインベントリエクスポートの作成
• クエリデータを使用した Jinja2 テンプレートのレンダリング
• Python ロジックと Jinja2 レンダリングの組み合わせ
• 自動出力のためにトランスフォームをアーティファクトに接続
• 既存のトランスフォームまたはテンプレートがレンダリングする内容の変更
• 誤った出力、または生成に失敗するアーティファクトのデバッグ

ルールカテゴリ

優先度	カテゴリ	プレフィックス	説明
CRITICAL	Types	types-	Python と Jinja2 の選択
CRITICAL	Python	python-	InfrahubTransform クラス
CRITICAL	Jinja2	jinja2-	テンプレート構文、フィルター
HIGH	Hybrid	hybrid-	Python + Jinja2 の組み合わせ
HIGH	Artifacts	artifacts-	出力ファイル、ターゲット
HIGH	API Ref	api-	クラス属性、メソッド
MEDIUM	Patterns	patterns-	ユーティリティ、CSV、共有
HIGH	Testing	testing-	Resources Testing Framework、transform/render コマンド

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

トランスフォームはスキーマ形式のデータを読み取り、ファイルを生成します。トランスフォームとスキーマの不一致は遅い段階で失敗します — 成果物のレンダリング時、誰かが出力を待っているときに。

トランスフォームが...	スキーマ（または .infrahub.yml）は...	参照
artifact_definitions エントリに供給する	対象ノードは inherit_from: CoreArtifactTarget を持つ必要がある。そうすることで成果物パイプラインがそれをアタッチできる	../infrahub-managing-schemas/rules/extension-artifact-target.md
ノードから属性を読み取る	GraphQL でそれらの属性を完全な __value アクセスパスとともに定義する — 沈黙の空文字列は値ではなくノードにアクセスすることで生じる	../infrahub-managing-schemas/rules/attribute-defaults-and-types.md
プラットフォーム/ロールごとにデバイスごとのテンプレートを選択する	スキーマはそのプラットフォーム/ロールを実際の属性またはリレーションシップとして公開する必要がある — display_label の文字列マッチングは壊れやすい	../infrahub-managing-schemas/rules/display-human-friendly-id.md
artifact_definitions.transformation から参照される	トランスフォームの登録された name は transformation: フィールドと完全に一致する必要がある — 不一致はレンダリング時に「transformation not found」を引き起こす	rules/artifacts-definitions.md
Jinja2（Python ではなく）を使用する	トップレベルの query: フィールドとともに jinja2_transforms に登録する — python_transforms はクラス上でクエリをバインドし、2 つのキーは互換性がない	rules/api-reference.md
Python トランスフォームである	インポートするすべてのファーストパーティモジュールを列挙する watch: ブロックを持つ — インポートは決して追跡されないため、兄弟モジュールも含める。このキーがないと、Infrahub は依存関係リストを信頼できず、コミットのたびに成果物を再レンダリングする	rules/artifacts-watch-dependencies.md
実行時にデータファイルを読み取る、または変数名でテンプレートをインクルードする	それらのパスを watch.files に指定する — 検出は文字列としてのみ存在するパスを認識できないため、変更時に成果物が古くなり、エラーも発生しない	rules/artifacts-watch-dependencies.md
呼び出し元（カタログページ、CI ジョブ、オーケストレーター）によって成果物が再生成される	その呼び出し元は各成果物がボディ準備完了になるまで CoreArtifact をポーリングする必要がある — POST は再生成をキューに入れるだけであり、ノードはそのコンテンツより先に存在する	rules/artifacts-async-regen-polling.md

Python を記述する前に

変換処理の本体が文字列フォーマット（f 文字列、連結、条件付きセクション）であれば、Jinja2 を使うと同じ出力をより少ない行数で表現でき、変更提案 UI で直接レンダリングされます。また、.infrahub.yml の python_transforms ではなく jinja2_transforms の下に記述します。InfrahubTransform を使う前に、次の段階を確認してください。

シグナル	より簡易なレイヤー	ルール
変換処理の本体が return f"..." またはクエリ結果から作成した "\n".join([...])	Jinja2 テンプレートファイル	yagni-python-transform-that-could-be-jinja2
変換処理が計算せずにクエリデータをそのままコピーする	GraphQL クエリのみ — 変換処理は不要	段階 1（要件を取り除く）。判断が必要で、ルールはありません
条件分岐が if x: out += ...; else: out += ... のみで、それ以外は何もない	Jinja2 の {% if %} ブロック	yagni-python-transform-that-could-be-jinja2

解析、計算、または再構成を行う変換処理では Python を使います。たとえば、IP／サブネット計算、ハッシュ化、順序付きの集約、構造を維持した JSON の再構成などです。適切なケースについては、rules/python-transform.md を参照してください。

変換処理で SDK を介してオブジェクトを読み取る場合は、文字列の種類ではなく、生成されたプロトコルクラスで呼び出しに型を付けてください。たとえば kind="NetworkLink" ではなく client.filters(NetworkLink, ...) とします。こうすることで、スキーマの変更によって返されたオブジェクトの属性読み取りに問題が生じた場合、型チェック時に検出できます。create() に渡すフィールド名は型チェックされません。protocols-adopt-typed-kinds を参照してください。

変換の基本

変換処理には 2 種類あります。

種類	出力	エントリーポイント
Python	アーティファクトの content_type に応じた形式：application/json または application/yaml の場合のみ dict、それ以外の 6 種類では str	InfrahubTransform.transform()
Jinja2	テキスト	.j2 テンプレートファイル

from infrahub_sdk.transforms import InfrahubTransform

class MyTransform(InfrahubTransform):
    query = "my_query"

    # Returns a dict, so the artifact definition has to declare
    # content_type: application/json (or application/yaml). Under any
    # other content type this dict is stored as str(dict), with no
    # error. See rules/artifacts-definitions.md.
    async def transform(self, data: dict) -> dict:
        device = data["DcimDevice"]["edges"][0]["node"]
        return {"hostname": device["name"]["value"]}

ワークフロー

トランスフォームを作成するときは、次の手順に従ってください。

1. トランスフォームの種類を選択する — JSON/dict や複雑なロジックには Python、テキストテンプレートには Jinja2、両方にはハイブリッドを使用します。詳しくは rules/types-overview.md をお読みください。
2. GraphQL クエリを作成する — トランスフォームするデータを取得する .gql ファイルを作成します。クエリのパターンについては ../infrahub-common/graphql-queries.md をお読みください。
3. トランスフォームを実装する — Python の場合は、InfrahubTransform を継承し、transform() を実装します。詳しくは rules/python-transform.md をお読みください。 Jinja2 の場合は、.j2 テンプレートを作成します。詳しくは rules/jinja2-template.md をお読みください。 ハイブリッドの場合は、 rules/hybrid-python-jinja2.md をお読みください。
4. アーティファクトに接続する — トランスフォームの出力をファイルとして保存する場合は、アーティファクト定義を構成します。詳しくは rules/artifacts-definitions.md をご覧ください。
5. .infrahub.yml に登録する — python_transforms または jinja2_transforms の下に追加します。詳しくは rules/api-reference.md をご覧ください。 次に、watch.files でトランスフォームの依存関係を宣言します。エントリーポイントのインポートと実行時のファイル読み取りを確認し、それらが解決するすべてのファーストパーティパスを指定してください。Python トランスフォームは常にこのキーを持つべきです — 自身のファイル以外に依存関係が本当にない場合は files: [] とします。詳しくは rules/artifacts-watch-dependencies.md をお読みください。このドキュメントでは、既存の watch ブロックについて、欠落しているエントリー、古くなったエントリー、誤ったエントリーを確認する方法も説明しています。
6. テストを追加する — トランスフォームと一緒に YAML 駆動のテスト定義（スモーク、ユニット、統合）を作成し、提案された変更パイプラインで自動的に検証されるようにします。詳しくは rules/testing-resource-framework.md をお読みください。
7. ローカルでテストする — infrahubctl transform または infrahubctl render を実行して検証します。詳しくは rules/testing-commands.md をご覧ください。

関連リファレンス

• rules/artifacts-definitions.md -- 8 つの content_type の値と、それぞれがトランスフォームの戻り値をどのようにシリアライズするか。どの戻り値の型を content type が受け入れるかに関する権威
• reference.md -- クラス API、ライフサイクル、.infrahub.yml の登録形式、フィルター env の概要
• examples.md -- 完全なトランスフォームのパターン（Python、Jinja2、ハイブリッド、CSV）
• ../infrahub-common/graphql-queries.md -- GraphQL クエリ作成リファレンス
• infrahub-yml-reference.md -- .infrahub.yml プロジェクト構成
• ../infrahub-common/rules/ -- すべてのスキルで共有されるルール（git 統合、キャッシュ）
• ../infrahub-common/rules/workflow-information-priority.md -- スキルの内容を優先すること。真のギャップ（例: ノードの削除）がある場合に docs.infrahub.app を参照する方法
• ../infrahub-managing-schemas/SKILL.md -- トランスフォームが扱うスキーマ定義
• rules/ -- カテゴリ別の個別ルール