| name | infrahub-managing-checks |
| description | Creates Infrahub check definitions — Python validation logic, GraphQL queries, and YAML-driven tests for proposed change pipelines. TRIGGER when: writing validation checks, creating Python checks, building data quality guards for proposed changes, writing or running tests for a check. DO NOT TRIGGER when: designing schemas, querying live data, building transforms or generators. |
| allowed-tools | ["Read","Write","Edit","Bash","Grep"] |
| argument-hint | [check-name] [description...] |
| metadata | {"version":"1.2.8","author":"OpsMill"} |
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, relationship-traversal 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:
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
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:
- GraphQL query (
.gql file) -- fetches the data to
validate, and is registered under the top-level
queries: section of .infrahub.yml
- Python class -- inherits from
InfrahubCheck,
sets query = "<query_name>", implements
validate()
- 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"
def validate(self, data: dict) -> None:
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:
- 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.
- 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.
- 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.
- 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.
- 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.
- Test locally — Run
infrahubctl check to validate
against a feature branch. See
rules/testing-commands.md.
Supporting References
