Checks and Validators
Relevant source files
The following files were used as context for generating this wiki page:
Checks and Validators ensure the integrity and accuracy of infrastructure data within the Infrahub ecosystem. These components validate data at different stages of the lifecycle, including during command execution, template rendering, and data transformation within the Infrahub pipeline.
The system uses a combination of local input validation in the CLI, specialized Jinja2 filters for template composition, and structured check classes for domain rules. This layered approach ensures that invalid data is caught as early as possible while maintaining a single source of truth for complex domain logic.
Sources: dev/constitution.md:46-56, dev/specs/infp-504-artifact-composition/tasks.md:15-18
Execution Contexts and Security
The validation system operates within different execution contexts that determine which operations are permitted. This security model prevents unauthorized or dangerous operations in sensitive environments like the Infrahub Core.
Execution Context Types
| Context | Description | Permitted Operations |
|---|---|---|
CORE | The Infrahub Core server environment. | Restricted; blocks external resource access (e.g., artifact_content). |
WORKER | Background workers (e.g., Prefect) executing transforms or generators. | Permits Infrahub API interactions and sub-artifact retrieval. |
LOCAL | Local execution, such as via infrahubctl on a user's machine. | Full permissions for local and remote SDK interactions. |
Sources: dev/specs/infp-504-artifact-composition/tasks.md:23-28, infrahub_sdk/template/filters.py
Validation Flow
The following diagram illustrates how the ExecutionContext gatekeeper validates operations based on the environment:
Template Validators (Jinja2)
Templates use specialized filters to compose content and validate data structures. These filters are registered with specific permissions to ensure they are used safely across different contexts.
Content Composition Filters
Infrahub provides specific filters for retrieving and validating content from the Infrahub Object Store. These filters are strictly blocked in the CORE context to maintain server stability.
artifact_content: Inlines the content of a rendered sub-artifact.file_object_content: Inlines content from file objects, rejecting binary data.from_json/from_yaml: Parses strings into structured Python dictionaries, raisingJinjaFilterErrorif the input is malformed.
Sources: dev/specs/infp-504-artifact-composition/tasks.md:32-48, infrahub_sdk/template/infrahub_filters.py
Error Handling in Templates
When a filter fails, the system raises a JinjaFilterError. This specific exception includes:
- Filter Name: Identifies which filter caused the failure.
- Message: Describes the error (e.g., retrieval failure, binary rejection).
- Hint: Provides a suggested corrective action for the user.
Sources: dev/specs/infp-504-artifact-composition/tasks.md:21-22, infrahub_sdk/template/infrahub_filters.py
SDK Checks Architecture
The infrahub_sdk/checks.py module defines the structural foundation for domain-specific validation. Infrastructure data is treated as native Python objects, allowing developers to write validation rules using standard Python logic.
Validation Sequence
CLI vs. Server Validation
The project follows a strict "layered architecture" principle regarding validation:
- CLI Layer: Limited to argument parsing and local-only input validation. It must not duplicate logic that the server is capable of validating.
- SDK Layer: Contains reusable logic for domain rules and data transformation.
- Server Layer: The ultimate authority for data integrity and schema constraints.
Sources: dev/constitution.md:46-56, infrahub_sdk/ctl/cli.py
Type Safety and Error Handling
Validators are enforced by strict type hinting. All function signatures must carry hints, and Pydantic v2 models are used at configuration and data boundaries to perform runtime validation.
Error Hierarchy
Errors raised during validation must follow the infrahub_sdk.exceptions hierarchy rooted at Error. This allows consumers to catch specific failure modes deterministically rather than matching error messages.
Sources: dev/constitution.md:58-64, infrahub_sdk/checks.py
Quality Gates
To maintain the integrity of validators and checks, the following gates are enforced:
- Type Checking: Both
tyandmypymust pass for all validation logic. - Documentation Accuracy: Docstrings for validators must accurately describe the behavior; generated documentation must be updated whenever checks change.
- Test-First Development: Every check or bug fix must include a reproduction test that fails before the fix and passes after.
Sources: dev/constitution.md:66-78, AGENTS.md
Summary
Checks and Validators in the Infrahub SDK provide a multi-layered defense against data corruption. By combining Pydantic-based type safety, context-aware template filters, and structured SDK checks, the system ensures that infrastructure data remains consistent from the local CLI through to the Infrahub Core server.