infrahub-managing-checks

Infrahub チェック作成ガイド

概要

Infrahub チェックの作成に関する専門的なガイダンスです。チェックは、提案された変更のパイプラインの一部として実行される、ユーザー定義の検証ロジック（Python ＋ GraphQL）です。チェックでエラーがログに記録された場合、その提案された変更はマージできません。

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

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

既存のチェック： !find . -name "*.py" -path "*/checks/*" 2>/dev/null | head -20

既存のクエリ： !find . -name "*.gql" -path "*/queries/*" 2>/dev/null | head -20

使用する場面

• 提案された変更の検証ロジックを作成する
• データ品質を保護する仕組みを作成する（例：ラックの衝突検出）
• ある型のすべてのオブジェクトを検証するグローバルチェックを構築する
• 特定のグループ化されたオブジェクトを検証する対象限定チェックを構築する
• チェックの失敗をデバッグする、またはチェックのライフサイクルを理解する

ルールカテゴリ

優先度	カテゴリ	プレフィックス	説明
CRITICAL	アーキテクチャ	architecture-	3 つのコンポーネント、グローバルと対象限定の違い、実行フロー
CRITICAL	Python クラス	python-	InfrahubCheck 基底クラス、validate()、log_error/log_info
HIGH	API リファレンス	api-	クラス属性、インスタンスプロパティ、メソッド、ライフサイクル、および拒否を通知する API サーフェス（GraphQL エラーは 200）
HIGH	登録	registration-	.infrahub.yml の設定、クエリ名の一致、パラメーター
MEDIUM (patterns-shared-module の場合は HIGH)	パターン	patterns-	エラー収集、共有ユーティリティ、スコープ付き検証、リレーションシップをたどる検証、成果物タイプ間でのモジュール共有
HIGH	テスト	testing-	Resources Testing Framework（YAML 駆動のテスト）、infrahubctl のチェックコマンド、提案された変更のチェックが実行されるリポジトリのコミット

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

チェックは、適切なデータを取得して検証できる場合にのみ有用です。デプロイ時のチェック失敗の多くは、実際にはスキーマ側の不足が原因です。

チェックが...	スキーマ（または .infrahub.yml）で必要なこと...	参照先
GraphQL 経由で属性を読み取る	同じ名前の属性をスキーマノードで公開する（name__value 形式のパス）	../infrahub-managing-schemas/rules/attribute-defaults-and-types.md
リレーションシップをたどって関連オブジェクトを検証する	リレーションシップの両側を、対応する識別子を使って定義する。そうしないと、たどった結果が返りません	../infrahub-managing-schemas/rules/relationship-identifiers.md
関連ノードの状態に照らしてノードを検証する（子と親のライフサイクル、ピア間の整合性）	リレーションシップをたどるクエリで、関連ノードの比較対象属性を取得する。チェックはクエリを 1 回実行し、遅延取得は行いません	rules/patterns-relationship-traversal.md
対象限定（オブジェクト単位）である	.infrahub.yml の targets: に CoreStandardGroup を登録し、parameters: を GraphQL 変数にバインドする	rules/registration-config.md
GraphQL の応答で型付きノードをキーとして識別する必要がある	クエリで id と __typename を選択する。SDK は両方に依存します	../infrahub-common/graphql-queries.md
マージをブロックせず、注釈のみを付ける	log_error() の代わりに self.log_info() を使用する。log_warning() は存在しません	rules/python-validate.md

Python を書く前に

より低コストのレイヤーで制約を表現できるなら、そちらを使ってください。 スキーマ制約は、すべての書き込み経路で読み込み時に実行されます。 一方、Python のチェックは提案変更パイプライン内でのみ実行されるため、 別の経路で作成された不正なデータは見逃されます。 InfrahubCheck を使う前に、次の簡単な手順を確認してください。

シグナル	より低コストのレイヤー	ルールを参照
1 つの属性に対する一意性、存在、許可された値、または正規表現の検証	スキーマ制約（uniqueness_constraints、optional: false、kind: Dropdown の選択肢、regex）	yagni-python-validator-vs-schema-constraint
本体が GraphQL クエリと単一の if len(...) > 0: raise で構成されるチェック	1 つの .gql ファイルと 5 行の Python	yagni-redundant-check-that-graphql-can-answer
リレーションシップを単一ピアまたは任意でないものにする	スキーマの cardinality: one、kind: Parent / Component、optional: false	yagni-python-validator-vs-schema-constraint

これらのいずれにも該当しない場合にのみ、 Python のチェックを書いてください。rules/python-validate.md にあるノード間のビジネスルール、帯域外の調整、状態を伴うアサーションが 正当なユースケースです。

チェックが SDK を通じてオブジェクトを読み取る場合（GraphQL クエリのみを使う場合を除く）は、 文字列の kind ではなく、生成されたプロトコルクラスで呼び出しに型を指定してください。 kind="DcimDevice" ではなく、client.get(DcimDevice, ...) のようにします。 チェックのクライアントに対応する --sync プロトコルのバリアントを選んでください。 protocols-adopt-typed-kindsを参照してください。

チェックの基本

すべてのチェックは、次の 3 つの要素で構成されます。

1. GraphQL クエリ（.gql ファイル）-- 検証するデータを取得し、.infrahub.yml の最上位の queries: セクションに登録します
2. Python クラス -- InfrahubCheck を継承し、 query = "<query_name>" を設定して、 validate() を実装します
3. 設定 -- .infrahub.yml の check_definitions の下に宣言します（query: フィールドは 指定しません。下記を参照してください）

from infrahub_sdk.checks import InfrahubCheck


class MyCheck(InfrahubCheck):
    query = "my_query"  # Must match queries[].name in .infrahub.yml

    def validate(self, data: dict) -> None:
        # Validation logic here
        if something_is_wrong:
            self.log_error(
                message="Problem description"
            )

クエリがバインドされる場所： Python クラス （query = "..."）であり、check_definitions ではありません。 リポジトリの設定モデルでは extra="forbid" が使われているため、 check_definitions: の下に query: を置くと、 リポジトリ設定全体の検証に失敗します。これは、 最上位の query: を指定する generator_definitions: と 混同されるケースが最も多いものです。rules/registration-config.mdを参照してください。

ワークフロー

チェックを作成するときは、次の手順に従います。

1. 検証の目的を理解する — 提案された変更をブロックするデータ条件は何ですか？　これは、ある型のすべてのオブジェクトを対象とするグローバルチェックなのか、特定のグループを対象とするものなのかを判断します。 rules/architecture-types.mdを読みます。
2. GraphQL クエリを作成する — 検証するデータを取得する.gqlファイルを作成します。クエリのパターンについては、../infrahub-common/graphql-queries.mdを読みます。ルールがノードを関連ノードの状態と比較する場合（子と親のライフサイクル、ピア間の一貫性など）、クエリで関係をたどって関連属性を取得する必要があります。チェックではクエリを1回実行し、その後のデータ取得はありません。rules/patterns-relationship-traversal.mdを参照してください。
3. Python クラスを実装する — InfrahubCheckを継承し、validate()を実装します。クラスのパターンについてはrules/python-validate.mdを、利用可能なメソッドについてはrules/api-reference.mdを読みます。チェックからInfrahubを呼び出す場合は、rules/api-error-surfaces.mdも読んでください。GraphQLリクエストが拒否されてもHTTP 200が返されるため、ステータスコードで分岐すると、検出するはずの失敗時にチェックが成功してしまいます。ロジックをジェネレーターや変換処理と共有する場合は、相対インポートを使う前にrules/patterns-shared-module.mdを読んでください。
4. .infrahub.ymlに登録する — check_definitionsの下にチェックを追加します。クエリ名は、Pythonクラスのquery属性と一致させる必要があります。rules/registration-config.mdを参照してください。
5. テストを追加する — 提案された変更のパイプラインで自動検証されるよう、チェックと同じ場所にYAML駆動のテスト定義（スモーク、ユニット、統合）を作成します。rules/testing-resource-framework.mdを読みます。
6. ローカルでテストする — infrahubctl checkを実行して、フィーチャーブランチに対して検証します。rules/testing-commands.mdを参照してください。既存の提案された変更に対して変更済みのチェックを実行するには、rules/testing-proposed-change-commit.mdを読んでください。パイプラインはmainのコミットではなく、ソースブランチのリポジトリコミットのコードを実行します。また、Gitと同期しているブランチでは、ブランチのリベースをしてもそのコミットは更新されません。

補足資料

• reference.md -- クラス API、log_error/log_info（log_warningはありません）、ライフサイクル、.infrahub.ymlの登録（generator_definitionsとは異なり、query:を含まない形式）
• examples.md -- チェックの完全なパターン（グローバル、対象指定、最小構成）
• ../infrahub-common/graphql-queries.md -- GraphQLクエリ作成のリファレンス
• ../infrahub-common/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/ -- カテゴリ別のプレフィックスで整理された個別ルール