infrahub-managing-checks

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

Priority	Category	Prefix	Description
CRITICAL	Architecture	architecture-	Three components, global vs targeted, execution flow
CRITICAL	Python Class	python-	InfrahubCheck base class, validate(), log_error/log_info
HIGH	API Reference	api-	Class attributes, instance properties, methods, lifecycle
HIGH	Registration	registration-	.infrahub.yml config, query name matching, parameters
MEDIUM	Patterns	patterns-	Error collection, shared utilities, scoped validation
HIGH	Testing	testing-	Resources Testing Framework (YAML-driven tests), infrahubctl check commands

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 GraphQL	Expose 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 objects	Have both sides of the relationship defined with matching identifiers; otherwise the traversal returns nothing	../infrahub-managing-schemas/rules/relationship-identifiers.md
Is targeted (per-object)	Register a CoreStandardGroup as targets: in .infrahub.yml and map parameters: to bind GraphQL variables	rules/registration-config.md
Needs the GraphQL response keyed to typed nodes	Select id and __typename in the query — the SDK relies on both	../infrahub-common/graphql-queries.md
Should never block a merge but only annotate	Use self.log_info() instead of log_error(); log_warning() does not exist	rules/python-validate.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
2. Python class -- inherits from InfrahubCheck, sets query = "<query_name>", implements validate()
3. 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.

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.
2. Write the GraphQL query — Create a .gql file that fetches the data to validate. Read ../infrahub-common/graphql-queries.md for query patterns.
3. 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.
4. 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.
5. 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.
6. Test locally — Run infrahubctl check to validate against a feature branch. See rules/testing-commands.md.

Supporting References

• reference.md -- Class API, log_error/log_info (no log_warning), lifecycle, .infrahub.yml registration (with the no-query: shape that differs from generator_definitions)
• examples.md -- Complete check patterns (global, targeted, minimal)
• ../infrahub-common/graphql-queries.md -- GraphQL query writing reference
• ../infrahub-common/infrahub-yml-reference.md -- .infrahub.yml project configuration
• ../infrahub-common/rules/ -- Shared rules (git integration, caching gotchas) that apply across all skills
• ../infrahub-managing-schemas/SKILL.md -- Schema definitions checks validate against
• rules/ -- Individual rules organized by category prefix