Managing Transforms Skill

Relevant source files

The following files were used as context for generating this wiki page:

• skills/infrahub-managing-transforms/SKILL.md
• dev/knowledges/architecture.md
• dev/knowledges/skill-writing-guide.md
• dev/guidelines/skill-authoring.md
• skills/infrahub-analyzing-data/rules/approach-selection.md
• skills/infrahub-common/rules/workflow-information-priority.md

Introduction

The Managing Transforms Skill provides expert guidance for creating, modifying, and debugging Infrahub transforms. Transforms convert infrastructure data fetched via GraphQL into various text-based formats such as JSON, CSV, or device configurations. This skill enables AI assistants to assist developers in building automated artifact pipelines and rendering data for external consumption.

This skill is part of a larger ecosystem of Agent Skills designed to manage the full Infrahub development lifecycle. It specifically handles the logic for data conversion using Python classes or Jinja2 templates.

Sources: skills/infrahub-managing-transforms/SKILL.md:20-24, dev/knowledges/architecture.md:8-13

Transform Types and Selection

Infrahub supports two primary methods for transforming data. Choosing the correct type depends on the complexity of the data manipulation required and the desired output format.

Type Comparison

Type	Best For	Entry Point	Output
Python	Complex logic, IP math, JSON re-shaping	InfrahubTransform.transform()	dict (JSON/YAML) or str
Jinja2	Text templates, configuration files	.j2 template file	str (Text)

Sources: skills/infrahub-managing-transforms/SKILL.md:92-100

Selection Logic

Developers should use the "ladder of complexity" when selecting a transform type. Jinja2 is preferred for simple string formatting and conditional text rendering because it renders directly in the Infrahub UI. Python is reserved for scenarios involving IP/subnet mathematics, hashing, or structural JSON manipulation.

The diagram above shows the decision flow for selecting the most efficient transformation layer.

Sources: skills/infrahub-managing-transforms/SKILL.md:73-88, skills/infrahub-analyzing-data/rules/approach-selection.md:70-80

Architecture and Data Flow

Transforms act as a bridge between the Infrahub data model (Schema) and external artifacts. They depend on accurately defined GraphQL queries to fetch data from the Infrahub server.

Component Interaction

A transform requires three main components to function:

1. GraphQL Query: Defines which nodes and attributes to fetch.
2. Transformation Logic: The Python code or Jinja2 template that processes the fetched data.
3. Artifact Definition: Configures the output file target and content type.

The sequence diagram illustrates how data flows from the server through the query and transform logic to produce an artifact.

Sources: skills/infrahub-managing-transforms/SKILL.md:52-70, dev/knowledges/architecture.md:32-46

Implementation Workflow

The implementation of a transform follows a structured seven-step process to ensure data integrity and automated testing.

1. Select Type: Choose between Python, Jinja2, or a hybrid approach.
2. Write Query: Create a .gql file to fetch the necessary Infrahub data.
3. Implement Logic: Write the InfrahubTransform class or .j2 template.
4. Define Artifacts: Configure how the output should be stored as a file in .infrahub.yml.
5. Register Transform: Add the transform to the python_transforms or jinja2_transforms section of .infrahub.yml.
6. Configure Dependencies: Use the watch.files key to track dependencies, ensuring artifacts regenerate when source files change.
7. Test and Validate: Use infrahubctl transform or infrahubctl render for local validation.

Sources: skills/infrahub-managing-transforms/SKILL.md:118-142

Dependency Tracking

Python transforms must explicitly list first-party modules and runtime files in a watch: block. Without this, Infrahub cannot detect changes in imported modules, which may result in stale artifacts.

Sources: skills/infrahub-managing-transforms/SKILL.md:65-70

Implementation Standards

To maintain high technical quality, transforms must adhere to specific coding standards and priority rules.

Source Priority

When resolving technical questions during transform development, developers must follow the Information-Source Priority:

1. Active skill files (rules/, reference.md).
2. Shared infrahub-common/ references.
3. Official Infrahub documentation via llms.txt.

Sources: skills/infrahub-common/rules/workflow-information-priority.md:20-30

Python Code Requirements

• Class Inheritance: All Python transforms must inherit from infrahub_sdk.transforms.InfrahubTransform.
• Type Safety: Use generated protocol classes (e.g., client.filters(NetworkLink, ...)) instead of string-based kind references to prevent runtime failures due to schema drift.
• Content Types: The return value of the transform() method must match the content_type declared in the artifact definition (e.g., dict for application/json).

Sources: skills/infrahub-managing-transforms/SKILL.md:86-90, skills/infrahub-managing-transforms/SKILL.md:103-113

Summary

The Managing Transforms Skill enables the creation of robust data transformation pipelines within Infrahub. By leveraging a structured workflow, prioritizing specific transformation layers (Jinja2 vs. Python), and enforcing strict dependency tracking through watch blocks, developers can ensure that infrastructure artifacts remain accurate and synchronized with the underlying data model. Proper implementation relies on clear GraphQL queries and adherence to the schema's defined attributes and relationships.