Infrahub Transform Creator

Overview

Expert guidance for creating Infrahub transforms. Transforms convert Infrahub data into different formats -- JSON, text, CSV, device configs, or any text-based output -- using Python classes or Jinja2 templates.

Project Context

Infrahub config: !cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"

Existing transforms: !find . -name ".py" -path "/transforms/" -o -name ".j2" -path "/templates/" 2>/dev/null | head -20

When to Use

• Building data transformations (Infrahub data -> another format)
• Generating device configurations from infrastructure data
• Creating CSV reports, cable matrices, or inventory exports
• Rendering Jinja2 templates with query data
• Combining Python logic with Jinja2 rendering
• Connecting transforms to artifacts for automated output

Rule Categories

Schema Features This Skill Depends On

A transform reads schema-shaped data and produces a file. Misalignment between the transform and the schema fails late — at artifact-render time, when someone is waiting for the output.

Before writing Python

If the transform body is string formatting — f-strings, concatenation, conditional sections — Jinja2 expresses the same output in fewer lines, renders directly in the proposed-change UI, and lives under jinja2transforms in .infrahub.yml instead of pythontransforms. Walk this ladder before reaching for InfrahubTransform:

Use Python when the transform parses, computes, or reshapes — IP/subnet math, hashing, ordered aggregation, structural JSON re-shaping. See [rules/python-transform.md](./rules/python-transform.md) for the legitimate cases.

When the transform reads objects through the SDK, type those calls with generated protocol classes rather than string kinds — client.filters(NetworkLink, ...), not kind="NetworkLink" — so schema drift fails type-check instead of at runtime. See [protocols-adopt-typed-kinds](../infrahub-common/rules/protocols-adopt-typed-kinds.md).

Transform Basics

Two types of transforms:

from infrahub_sdk.transforms import InfrahubTransform

class MyTransform(InfrahubTransform):
    query = "my_query"

    async def transform(self, data: dict) -> dict:
        device = data["DcimDevice"]["edges"][0]["node"]
        return {"hostname": device["name"]["value"]}

Workflow

Follow these steps when creating a transform:

1. Choose the transform type — Python for JSON/dict

or complex logic, Jinja2 for text templates, hybrid for both. Read [rules/types-overview.md](./rules/types-overview.md).

1. Write the GraphQL query — Create a .gql file

that fetches the data to transform. Read [../infrahub-common/graphql-queries.md](../infrahub-common/graphql-queries.md) for query patterns.

1. Implement the transform — For Python, inherit

from InfrahubTransform and implement transform(). Read [rules/python-transform.md](./rules/python-transform.md). For Jinja2, create a .j2 template. Read [rules/jinja2-template.md](./rules/jinja2-template.md). For hybrid, read [rules/hybrid-python-jinja2.md](./rules/hybrid-python-jinja2.md).

1. Connect to artifacts — If the transform output

should be stored as a file, configure artifact definitions. See [rules/artifacts-definitions.md](./rules/artifacts-definitions.md).

1. Register in .infrahub.yml — Add under

pythontransforms or jinja2transforms. See [rules/api-reference.md](./rules/api-reference.md).

1. Add tests — Create YAML-driven test definitions

(smoke, unit, integration) alongside the transform so it is validated automatically in the proposed change pipeline. Read [rules/testing-resource-framework.md](./rules/testing-resource-framework.md).

1. Test locally — Run infrahubctl transform or

infrahubctl render to validate. See [rules/testing-commands.md](./rules/testing-commands.md).

Supporting References

• [reference.md](./reference.md) -- Class API,

lifecycle, return-type matrix, .infrahub.yml registration shapes, filter env overview

• [examples.md](./examples.md) -- Complete transform

patterns (Python, Jinja2, hybrid, CSV)

• [../infrahub-common/graphql-queries.md](../infrahub-common/graphql-queries.md)

-- GraphQL query writing reference

• [infrahub-yml-reference.md](../infrahub-common/infrahub-yml-reference.md)

-- .infrahub.yml project configuration

• [../infrahub-common/rules/](../infrahub-common/rules/) -- Shared rules

(git integration, caching) across all skills

• [../infrahub-common/rules/workflow-information-priority.md](../infrahub-common/rules/workflow-information-priority.md)

-- Skill content first; how to consult docs.infrahub.app on a genuine gap (e.g. deleting nodes)

• [../infrahub-managing-schemas/SKILL.md](../infrahub-managing-schemas/SKILL.md)

-- Schema definitions transforms work with

• [rules/](./rules/) -- Individual rules by category