opsmill/infrahub-skills

infrahub-managing-checks

Creates, modifies and debugs Infrahub check definitions — Python validation logic, GraphQL queries, and YAML-driven tests for proposed change pipelines.

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/opsmill/infrahub-skills --skill infrahub-managing-checks

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

Infrahub Check Creator

Overview

Expert guidance for creating Infrahub checks. Checks are user-defined validation logic (Python + GraphQL) that run as part of a proposed change pipeline. If a check logs any errors, the proposed change cannot be merged.

Project Context

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

Existing checks: !find . -name "*.py" -path "*/checks/*" 2>/dev/null | head -20

Existing queries: !find . -name "*.gql" -path "*/queries/*" 2>/dev/null | head -20

When to Use

  • Writing validation logic for proposed changes
  • Creating data quality guards (e.g., rack collision

detection)

  • Building global checks that validate all objects of a type
  • Building targeted checks that validate specific grouped

objects

  • Debugging check failures or understanding the check

lifecycle

Rule Categories

<!-- markdownlint-disable MD013 -->

PriorityCategoryPrefixDescription
CRITICALArchitecturearchitecture-Three components, global vs targeted, execution flow
CRITICALPython Classpython-InfrahubCheck base class, validate(), logerror/loginfo
HIGHAPI Referenceapi-Class attributes, instance properties, methods, lifecycle, and which API surfaces a rejection (a GraphQL error is a 200)
HIGHRegistrationregistration-.infrahub.yml config, query name matching, parameters
MEDIUM (HIGH for patterns-shared-module)Patternspatterns-Error collection, shared utilities, scoped validation, relationship-traversal validation, sharing a module across artifact types
HIGHTestingtesting-Resources Testing Framework (YAML-driven tests), infrahubctl check commands, which repository commit a proposed change's checks run

<!-- markdownlint-enable MD013 -->

Schema Features This Skill Depends On

A check is only useful if it can fetch and validate the right data. Most check failures at deploy time are actually schema-side gaps:

If the check...The schema (or .infrahub.yml) must...See
Reads an attribute via GraphQLExpose it on the schema node with the same name (name__value-shaped paths)../infrahub-managing-schemas/rules/attribute-defaults-and-types.md
Walks a relationship to validate related objectsHave both sides of the relationship defined with matching identifiers; otherwise the traversal returns nothing../infrahub-managing-schemas/rules/relationship-identifiers.md
Validates a node against a related node's state (child vs parent lifecycle, peer consistency)Fetch the related node's comparison attribute in the query by traversing the relationship; a check runs one query with no lazy fetchrules/patterns-relationship-traversal.md
Is targeted (per-object)Register a CoreStandardGroup as targets: in .infrahub.yml and map parameters: to bind GraphQL variablesrules/registration-config.md
Needs the GraphQL response keyed to typed nodesSelect id and __typename in the query — the SDK relies on both../infrahub-common/graphql-queries.md
Should never block a merge but only annotateUse self.log_info() instead of log_error(); log_warning() does not existrules/python-validate.md

Before writing Python

If a cheaper layer can express the constraint, use it. A schema constraint runs at load time on every write path; a Python check runs only inside the proposed- change pipeline, so bad data created via other paths slips through. Walk this short ladder before reaching for InfrahubCheck:

SignalCheaper layerSee rule
Validating uniqueness, presence, allowed values, or regex on a single attributeSchema constraint (uniqueness_constraints, optional: false, kind: Dropdown choices, regex)yagni-python-validator-vs-schema-constraint
Check whose body is a GraphQL query plus a single if len(...) > 0: raiseOne .gql file plus 5 lines of Pythonyagni-redundant-check-that-graphql-can-answer
Enforcing that a relationship is single-peered or non-optionalSchema cardinality: one, kind: Parent / Component, optional: falseyagni-python-validator-vs-schema-constraint

Only when none of these apply should you write a Python check. The cross-node business rules, out-of-band reconciliations, and stateful assertions in rules/python-validate.md are the legitimate use cases.

When the check reads objects through the SDK (rather than only its GraphQL query), type those calls with generated protocol classes rather than string kinds — client.get(DcimDevice, ...), not kind="DcimDevice". Match the --sync protocol variant to the check's client. See protocols-adopt-typed-kinds.

Check Basics

Every check has three components:

  1. GraphQL query (.gql file) -- fetches the data to

validate, and is registered under the top-level queries: section of .infrahub.yml

  1. Python class -- inherits from InfrahubCheck,

sets query = "<query_name>", implements validate()

  1. Configuration -- declared in .infrahub.yml under

check_definitions (which does not take a query: field — see below)

python
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"
            )
Where the query is bound: the Python class (query = "..."), not check_definitions. The repository config model uses extra="forbid", so putting query: under check_definitions: makes the whole repo config fail validation. This is the most common confusion vs. generator_definitions:, which does take a top-level query:. See rules/registration-config.md.

Workflow

Follow these steps when creating a check:

  1. Understand the validation goal — What data

condition should block a proposed change? Determine whether this is a global check (all objects of a type) or targeted (specific group). Read rules/architecture-types.md.

  1. Write the GraphQL query — Create a .gql file

that fetches the data to validate. Read ../infrahub-common/graphql-queries.md for query patterns. If the rule compares a node against a related node's state (child vs parent lifecycle, peer consistency), the query must fetch that related attribute by traversing the relationship now — a check runs one query with no later fetch. See rules/patterns-relationship-traversal.md.

  1. Implement the Python class — Inherit from

InfrahubCheck, implement validate(). Read rules/python-validate.md for the class pattern and rules/api-reference.md for available methods. If the check calls back into Infrahub, read rules/api-error-surfaces.md too: a rejected GraphQL request still returns HTTP 200, so branching on a status code makes the check pass on the failure it exists to catch. If the logic is shared with a generator or a transform, read rules/patterns-shared-module.md before reaching for a relative import.

  1. Register in .infrahub.yml — Add the check under

check_definitions. The query name must match the Python class query attribute. See rules/registration-config.md.

  1. Add tests — Create YAML-driven test definitions

(smoke, unit, integration) alongside the check so it is validated automatically in the proposed change pipeline. Read rules/testing-resource-framework.md.

  1. Test locally — Run infrahubctl check to validate

against a feature branch. See rules/testing-commands.md. To run a changed check against an existing proposed change, read rules/testing-proposed-change-commit.md: the pipeline runs the code at the source branch's repository commit, not main's, and a branch rebase does not move it on a branch synced with Git.

Supporting References

  • [reference.md](./reference.md) -- Class API,

logerror/loginfo (no logwarning), lifecycle, `.infrahub.yml` registration (with the no-`query:` shape that differs from generatordefinitions)

  • [examples.md](./examples.md) -- Complete check

patterns (global, targeted, minimal)

  • [../infrahub-common/graphql-queries.md](../infrahub-common/graphql-queries.md)

-- GraphQL query writing reference

  • [../infrahub-common/infrahub-yml-reference.md](../infrahub-common/infrahub-yml-reference.md)

-- .infrahub.yml project configuration

  • [../infrahub-common/rules/](../infrahub-common/rules/) -- Shared rules

(git integration, caching gotchas) that apply across all skills

  • [../infrahub-common/rules/workflow-information-priority.md](../infrahub-common/rules/workflow-information-priority.md)

-- Skill content first; how to consult docs.infrahub.app on a genuine gap (e.g. deleting nodes)

  • [../infrahub-managing-schemas/SKILL.md](../infrahub-managing-schemas/SKILL.md)

-- Schema definitions checks validate against

  • [rules/](./rules/) -- Individual rules organized by

category prefix

同じリポジトリから

関連する Skills

すべての Skills
opsmill
コミュニティ

infrahub-analyzing-diagnostics

Analyze an already-collected infrahub-collect diagnostic bundle — traceback and failure triage across service logs, incident correlation, and known-issue matching against opsmill/infrahub GitHub issues. TRIGGER when: the user says they collected a diagnostic bundle, gives you a bundle path, or pastes bundle contents — and asks what's wrong, wants the logs or tracebacks analyzed, asks "what does this bundle say", wants errors triaged/correlated, or asks whether a crash is a known issue. DO NOT TR

1時間の導入数
2
GitHub Stars
27
更新日
11月9日
opsmill
コミュニティ

infrahub-analyzing-data

Analyzes and correlates live Infrahub data via the MCP server — answers operational questions, detects drift, and investigates impact. TRIGGER when: querying infrastructure data, checking compliance, investigating change impact, producing ad-hoc reports. DO NOT TRIGGER when: writing automated checks, building transforms, designing schemas, populating data files, planning an Infrahub version upgrade (use infrahub-planning-upgrades). ALWAYS pass the user's question verbatim as args — this skill ru

1時間の導入数
3
GitHub Stars
27
更新日
11月9日
opsmill
コミュニティ

infrahub-auditing-repo

Audits an Infrahub repository against best practices and rules, producing a structured compliance report. TRIGGER when: reviewing repo for compliance, onboarding to existing project, pre-deployment validation, catching issues. DO NOT TRIGGER when: creating schemas, writing checks/generators, querying live data, populating objects, planning an Infrahub version upgrade (use infrahub-planning-upgrades).

1時間の導入数
3
GitHub Stars
27
更新日
11月9日
opsmill
コミュニティ

infrahub-collecting-diagnostics

Collect a redacted local diagnostic bundle (logs, config, version, state) for an OpsMill expert hand-off. TRIGGER when: Infrahub is broken/failing/erroring, the user asks for help debugging, wants to collect logs/diagnostics, prepares a hand-off for OpsMill support, or reports a crash/timeout/connection issue (upgrade failure, stuck branch, container CrashLoopBackOff, 500s, OOM). DO NOT TRIGGER when: debugging a check, transform, generator, menu, or schema in the repository (use the infrahub-man

1時間の導入数
3
GitHub Stars
27
更新日
11月9日