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 |
| LOW | Testing | testing- | infrahubctl check commands, branch testing |
Check Basics
Every check has three components:
- GraphQL query (
.gqlfile) -- fetches the data to validate - Python class -- inherits from
InfrahubCheck, implementsvalidate() - Configuration -- declared in
.infrahub.ymlundercheck_definitions
from infrahub_sdk.checks import InfrahubCheck
class MyCheck(InfrahubCheck):
query = "my_query" # Must match query name
def validate(self, data: dict) -> None:
# Validation logic here
if something_is_wrong:
self.log_error(
message="Problem description"
)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
.gqlfile that fetches the data to validate. Read ../infrahub-common/graphql-queries.md for query patterns. - Implement the Python class — Inherit from
InfrahubCheck, implementvalidate(). 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 classqueryattribute. See rules/registration-config.md. - Test — Run
infrahubctl checkto validate. See rules/testing-commands.md.
Supporting References
- 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