Skip to main content

Check Manager

Skill: infrahub-managing-checks

The Check Manager produces, modifies, and debugs Python validation checks that run in Infrahub's proposed change pipeline. Each check consists of three components: a GraphQL query file, a Python class inheriting from InfrahubCheck, and a .infrahub.yml registration entry. The skill generates all three and ensures they are correctly wired together.

When to use​

  • Enforcing naming conventions on devices, interfaces, or other nodes when a change is proposed
  • Validating that required relationships are populated (e.g., every device has a primary IP)
  • Blocking changes that would violate design intent (e.g., a BGP session referencing a decommissioned device)
  • Any validation that should block a proposed change from merging
  • Changing what an existing check validates, or working out why one fails, passes when it should not, or flags the wrong nodes

What it produces​

Three files that must be used together:

  1. GraphQL query file (.gql): fetches the data the check needs. Named to match the query attribute in the Python class.
  2. Python class (InfrahubCheck subclass): implements the validate() method. Uses self.log_error() to flag violations (which blocks the change) and self.log_info() for informational messages (which does not block).
  3. .infrahub.yml entry: registers the check under check_definitions with the class name, query name, and any parameters.

Example prompts​

  • "Create a check that validates every device has a primary IP assigned"
  • "Write a check that enforces the naming convention <site>-<role>-<number> for all device names"
  • "Create a check that blocks any proposed change that removes a BGP session from an active device"
  • "This check passes even when a device has no primary IP. Work out why and fix it"

Key rules enforced​

  • Three-component structure: all three files are always generated together; missing any one causes the check to fail at runtime
  • log_error() vs log_info(): log_error() blocks the proposed change; log_info() does not. The skill uses the correct one based on the intent described
  • GraphQL query naming: the query name in the .gql file must match the query class attribute exactly
  • Parameter mapping: if the check accepts parameters (e.g., to parameterize a naming pattern), the parameters are declared in both the Python class and the .infrahub.yml registration
  • Error collection before logging: errors are collected across all objects first, then logged together, rather than short-circuiting on the first error

Common mistakes it catches​

MistakeWhat the skill does instead
Using log_error() when log_info() was intendedMatches the log method to the described intent
Query name mismatch between .gql and Python classUses the same name in both
Missing .infrahub.yml registrationGenerates the registration entry alongside the check
Short-circuiting on first errorCollects all errors before logging

Running it​

Checks run automatically in the proposed change pipeline when a change is submitted to Infrahub. To test a check locally:

infrahubctl check <check-name>

Not sure this is the right skill?​

See Which skill do I use? for how the Check Manager differs from the Data Analyzer and the Transform Manager.