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 -->

<!-- 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:

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:

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](./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](../infrahub-common/rules/protocols-adopt-typed-kinds.md).

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)

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
#1 confusion vs. generator_definitions:, which
does take a top-level query:. See
[rules/registration-config.md](./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](./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](../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](./rules/patterns-relationship-traversal.md).

1. Implement the Python class — Inherit from

InfrahubCheck, implement validate(). Read [rules/python-validate.md](./rules/python-validate.md) for the class pattern and [rules/api-reference.md](./rules/api-reference.md) for available methods.

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](./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](./rules/testing-resource-framework.md).

1. Test locally — Run infrahubctl check to validate

against a feature branch. See [rules/testing-commands.md](./rules/testing-commands.md).

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