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" # 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:
- 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
1---2name: infrahub-managing-checks-33description: >-4 Creates Infrahub check definitions — Python validation logic, GraphQL queries, and YAML-driven tests for proposed change pipelines.5 TRIGGER when: writing validation checks, creating Python checks, building data quality guards for proposed changes, writing or running tests for a check.6 DO NOT TRIGGER when: designing schemas, querying live data, building transforms or generators.7allowed-tools:8 - Read9 - Write10 - Edit11 - Bash12 - Grep13argument-hint: "[check-name] [description...]"14metadata:15 source: https://skillmd.com/skills/opsmill/infrahub-managing-checks-316 version: 1.2.817 author: OpsMill18---1920# Infrahub Check Creator2122## Overview2324Expert guidance for creating Infrahub checks. Checks are25user-defined validation logic (Python + GraphQL) that run as26part of a proposed change pipeline. If a check logs any27errors, the proposed change cannot be merged.2829## Project Context3031Infrahub config:32!`cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"`3334Existing checks:35!`find . -name "*.py" -path "*/checks/*" 2>/dev/null | head -20`3637Existing queries:38!`find . -name "*.gql" -path "*/queries/*" 2>/dev/null | head -20`3940## When to Use4142- Writing validation logic for proposed changes43- Creating data quality guards (e.g., rack collision44 detection)45- Building global checks that validate all objects of a type46- Building targeted checks that validate specific grouped47 objects48- Debugging check failures or understanding the check49 lifecycle5051## Rule Categories5253<!-- markdownlint-disable MD013 -->5455| Priority | Category | Prefix | Description |56| -------- | -------- | ------ | ----------- |57| CRITICAL | Architecture | `architecture-` | Three components, global vs targeted, execution flow |58| CRITICAL | Python Class | `python-` | InfrahubCheck base class, validate(), log_error/log_info |59| HIGH | API Reference | `api-` | Class attributes, instance properties, methods, lifecycle |60| HIGH | Registration | `registration-` | .infrahub.yml config, query name matching, parameters |61| MEDIUM | Patterns | `patterns-` | Error collection, shared utilities, scoped validation, relationship-traversal validation |62| HIGH | Testing | `testing-` | Resources Testing Framework (YAML-driven tests), infrahubctl check commands |6364<!-- markdownlint-enable MD013 -->6566## Schema Features This Skill Depends On6768A check is only useful if it can fetch and validate69the right data. Most check failures at deploy time70are actually schema-side gaps:7172| If the check... | The schema (or .infrahub.yml) must... | See |73| --------------- | ------------------------------------- | --- |74| 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](../infrahub-managing-schemas/rules/attribute-defaults-and-types.md) |75| 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](../infrahub-managing-schemas/rules/relationship-identifiers.md) |76| 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 fetch | [rules/patterns-relationship-traversal.md](./rules/patterns-relationship-traversal.md) |77| Is targeted (per-object) | Register a `CoreStandardGroup` as `targets:` in `.infrahub.yml` and map `parameters:` to bind GraphQL variables | [rules/registration-config.md](./rules/registration-config.md) |78| 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](../infrahub-common/graphql-queries.md) |79| 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](./rules/python-validate.md) |8081## Before writing Python8283If a cheaper layer can express the constraint, use it.84A schema constraint runs at load time on every write85path; a Python check runs only inside the proposed-86change pipeline, so bad data created via other paths87slips through. Walk this short ladder before reaching88for `InfrahubCheck`:8990| Signal | Cheaper layer | See rule |91| ------ | ------------- | -------- |92| Validating uniqueness, presence, allowed values, or regex on a single attribute | Schema constraint (`uniqueness_constraints`, `optional: false`, `kind: Dropdown` choices, `regex`) | [yagni-python-validator-vs-schema-constraint](../infrahub-auditing-repo/rules/yagni-python-validator-vs-schema-constraint.md) |93| Check whose body is a GraphQL query plus a single `if len(...) > 0: raise` | One `.gql` file plus 5 lines of Python | [yagni-redundant-check-that-graphql-can-answer](../infrahub-auditing-repo/rules/yagni-redundant-check-that-graphql-can-answer.md) |94| Enforcing that a relationship is single-peered or non-optional | Schema `cardinality: one`, `kind: Parent` / `Component`, `optional: false` | [yagni-python-validator-vs-schema-constraint](../infrahub-auditing-repo/rules/yagni-python-validator-vs-schema-constraint.md) |9596Only when none of these apply should you write a97Python check. The cross-node business rules,98out-of-band reconciliations, and stateful assertions99in [rules/python-validate.md](./rules/python-validate.md)100are the legitimate use cases.101102When the check reads objects through the SDK (rather than only its GraphQL103query), type those calls with generated protocol classes rather than string104kinds — `client.get(DcimDevice, ...)`, not `kind="DcimDevice"`. Match the105`--sync` protocol variant to the check's client. See106[protocols-adopt-typed-kinds](../infrahub-common/rules/protocols-adopt-typed-kinds.md).107108## Check Basics109110Every check has three components:1111121. **GraphQL query** (`.gql` file) -- fetches the data to113 validate, and is registered under the top-level114 `queries:` section of `.infrahub.yml`1152. **Python class** -- inherits from `InfrahubCheck`,116 sets `query = "<query_name>"`, implements117 `validate()`1183. **Configuration** -- declared in `.infrahub.yml` under119 `check_definitions` (which does **not** take a120 `query:` field — see below)121122```python123from infrahub_sdk.checks import InfrahubCheck124125126class MyCheck(InfrahubCheck):127 query = "my_query" # Must match queries[].name in .infrahub.yml128129 def validate(self, data: dict) -> None:130 # Validation logic here131 if something_is_wrong:132 self.log_error(133 message="Problem description"134 )135```136137> **Where the query is bound:** the Python class138> (`query = "..."`), not `check_definitions`. The139> repository config model uses `extra="forbid"`, so140> putting `query:` under `check_definitions:` makes141> the whole repo config fail validation. This is the142> #1 confusion vs. `generator_definitions:`, which143> *does* take a top-level `query:`. See144> [rules/registration-config.md](./rules/registration-config.md).145146## Workflow147148Follow these steps when creating a check:1491501. **Understand the validation goal** — What data151 condition should block a proposed change? Determine152 whether this is a global check (all objects of a153 type) or targeted (specific group). Read154 [rules/architecture-types.md](./rules/architecture-types.md).1552. **Write the GraphQL query** — Create a `.gql` file156 that fetches the data to validate. Read157 [../infrahub-common/graphql-queries.md](../infrahub-common/graphql-queries.md)158 for query patterns. If the rule compares a node159 against a related node's state (child vs parent160 lifecycle, peer consistency), the query must fetch161 that related attribute by traversing the relationship162 now — a check runs one query with no later fetch. See163 [rules/patterns-relationship-traversal.md](./rules/patterns-relationship-traversal.md).1643. **Implement the Python class** — Inherit from165 `InfrahubCheck`, implement `validate()`. Read166 [rules/python-validate.md](./rules/python-validate.md)167 for the class pattern and168 [rules/api-reference.md](./rules/api-reference.md)169 for available methods.1704. **Register in .infrahub.yml** — Add the check under171 `check_definitions`. The query name must match the172 Python class `query` attribute. See173 [rules/registration-config.md](./rules/registration-config.md).1745. **Add tests** — Create YAML-driven test definitions175 (smoke, unit, integration) alongside the check so it176 is validated automatically in the proposed change177 pipeline. Read178 [rules/testing-resource-framework.md](./rules/testing-resource-framework.md).1796. **Test locally** — Run `infrahubctl check` to validate180 against a feature branch. See181 [rules/testing-commands.md](./rules/testing-commands.md).182183## Supporting References184185- **[reference.md](./reference.md)** -- Class API,186 log_error/log_info (no log_warning), lifecycle,187 `.infrahub.yml` registration (with the no-`query:`188 shape that differs from generator_definitions)189- **[examples.md](./examples.md)** -- Complete check190 patterns (global, targeted, minimal)191- **[../infrahub-common/graphql-queries.md](../infrahub-common/graphql-queries.md)**192 -- GraphQL query writing reference193- **[../infrahub-common/infrahub-yml-reference.md](../infrahub-common/infrahub-yml-reference.md)**194 -- .infrahub.yml project configuration195- **[../infrahub-common/rules/](../infrahub-common/rules/)** -- Shared rules196 (git integration, caching gotchas) that apply across all197 skills198- **[../infrahub-common/rules/workflow-information-priority.md](../infrahub-common/rules/workflow-information-priority.md)**199 -- Skill content first; how to consult `docs.infrahub.app`200 on a genuine gap (e.g. deleting nodes)201- **[../infrahub-managing-schemas/SKILL.md](../infrahub-managing-schemas/SKILL.md)**202 -- Schema definitions checks validate against203- **[rules/](./rules/)** -- Individual rules organized by204 category prefix