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
| Priority |
Category |
Prefix |
Description |
| CRITICAL |
Types |
types- |
Python vs Jinja2 choice |
| CRITICAL |
Python |
python- |
InfrahubTransform class |
| CRITICAL |
Jinja2 |
jinja2- |
Template syntax, filters |
| HIGH |
Hybrid |
hybrid- |
Python + Jinja2 combined |
| HIGH |
Artifacts |
artifacts- |
Output files, targets |
| HIGH |
API Ref |
api- |
Class attrs, methods |
| MEDIUM |
Patterns |
patterns- |
Utilities, CSV, shared |
| HIGH |
Testing |
testing- |
Resources Testing Framework, transform/render commands |
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
jinja2_transforms in .infrahub.yml instead of
python_transforms. Walk this ladder before reaching
for InfrahubTransform:
| Signal |
Cheaper layer |
See rule |
Transform body is return f"..." or "\n".join([...]) built from query results |
Jinja2 template file |
yagni-python-transform-that-could-be-jinja2 |
| Transform copies query data verbatim without computation |
The GraphQL query alone — no transform needed |
Ladder step 1 (drop the requirement); judgment call, no rule |
Conditionals are if x: out += ...; else: out += ... and nothing else |
Jinja2 {% if %} blocks |
yagni-python-transform-that-could-be-jinja2 |
Use Python when the transform parses, computes, or
reshapes — IP/subnet math, hashing, ordered
aggregation, structural JSON re-shaping. See
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.
Transform Basics
Two types of transforms:
| Type |
Output |
Entry Point |
| Python |
JSON/dict or text |
InfrahubTransform.transform() |
| Jinja2 |
Text |
.j2 template file |
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:
- Choose the transform type — Python for JSON/dict
or complex logic, Jinja2 for text templates, hybrid
for both. Read
rules/types-overview.md.
- Write the GraphQL query — Create a
.gql file
that fetches the data to transform. Read
../infrahub-common/graphql-queries.md
for query patterns.
- Implement the transform — For Python, inherit
from
InfrahubTransform and implement transform().
Read rules/python-transform.md.
For Jinja2, create a .j2 template. Read
rules/jinja2-template.md.
For hybrid, read
rules/hybrid-python-jinja2.md.
- Connect to artifacts — If the transform output
should be stored as a file, configure artifact
definitions. See
rules/artifacts-definitions.md.
- Register in .infrahub.yml — Add under
python_transforms or jinja2_transforms. See
rules/api-reference.md.
- 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.
- Test locally — Run
infrahubctl transform or
infrahubctl render to validate. See
rules/testing-commands.md.
Supporting References
1---2name: infrahub-managing-transforms-33description: >-4 Creates Infrahub transforms that convert data into JSON, text, CSV, or device configs using Python or Jinja2 templates, with YAML-driven tests.5 TRIGGER when: building config generation, data export, format conversion, Jinja2 templates, artifact pipelines, writing or running tests for a transform.6 DO NOT TRIGGER when: designing schemas, writing validation checks, creating generators, querying live data.7allowed-tools:8 - Read9 - Write10 - Edit11 - Bash12 - Grep13argument-hint: "[transform-name] [format]"14metadata:15 source: https://skillmd.com/skills/opsmill/infrahub-managing-transforms-316 version: 1.2.817 author: OpsMill18---1920# Infrahub Transform Creator2122## Overview2324Expert guidance for creating Infrahub transforms.25Transforms convert Infrahub data into different formats26-- JSON, text, CSV, device configs, or any text-based27output -- using Python classes or Jinja2 templates.2829## Project Context3031Infrahub config:32!`cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"`3334Existing transforms:35!`find . -name "*.py" -path "*/transforms/*" -o -name "*.j2" -path "*/templates/*" 2>/dev/null | head -20`3637## When to Use3839- Building data transformations (Infrahub data -> another format)40- Generating device configurations from infrastructure data41- Creating CSV reports, cable matrices, or inventory exports42- Rendering Jinja2 templates with query data43- Combining Python logic with Jinja2 rendering44- Connecting transforms to artifacts for automated output4546## Rule Categories4748| Priority | Category | Prefix | Description |49| -------- | --------- | ------------ | ------------------------------------------------------ |50| CRITICAL | Types | `types-` | Python vs Jinja2 choice |51| CRITICAL | Python | `python-` | InfrahubTransform class |52| CRITICAL | Jinja2 | `jinja2-` | Template syntax, filters |53| HIGH | Hybrid | `hybrid-` | Python + Jinja2 combined |54| HIGH | Artifacts | `artifacts-` | Output files, targets |55| HIGH | API Ref | `api-` | Class attrs, methods |56| MEDIUM | Patterns | `patterns-` | Utilities, CSV, shared |57| HIGH | Testing | `testing-` | Resources Testing Framework, transform/render commands |5859## Schema Features This Skill Depends On6061A transform reads schema-shaped data and produces a62file. Misalignment between the transform and the63schema fails late — at artifact-render time, when64someone is waiting for the output.6566| If the transform... | The schema (or .infrahub.yml) must... | See |67| ------------------- | ------------------------------------- | --- |68| Will feed an `artifact_definitions` entry | The target node must `inherit_from: CoreArtifactTarget` so the artifact pipeline can attach to it | [../infrahub-managing-schemas/rules/extension-artifact-target.md](../infrahub-managing-schemas/rules/extension-artifact-target.md) |69| Reads attributes from a node | Define those attributes with their full `__value` access path in GraphQL — silent empty strings come from accessing the node, not the value | [../infrahub-managing-schemas/rules/attribute-defaults-and-types.md](../infrahub-managing-schemas/rules/attribute-defaults-and-types.md) |70| Picks a template per device by platform/role | The schema must expose that platform/role as a real attribute or relationship — string-matching on `display_label` is brittle | [../infrahub-managing-schemas/rules/display-human-friendly-id.md](../infrahub-managing-schemas/rules/display-human-friendly-id.md) |71| Is referenced from `artifact_definitions.transformation` | The transform's registered `name` must match the `transformation:` field exactly — mismatch produces "transformation not found" at render time | [rules/artifacts-definitions.md](./rules/artifacts-definitions.md) |72| Uses Jinja2 (not Python) | Register under `jinja2_transforms` with a top-level `query:` field — `python_transforms` binds query on the class, the two keys are not interchangeable | [rules/api-reference.md](./rules/api-reference.md) |7374## Before writing Python7576If the transform body is string formatting — f-strings,77concatenation, conditional sections — Jinja2 expresses78the same output in fewer lines, renders directly in79the proposed-change UI, and lives under80`jinja2_transforms` in `.infrahub.yml` instead of81`python_transforms`. Walk this ladder before reaching82for `InfrahubTransform`:8384| Signal | Cheaper layer | See rule |85| ------ | ------------- | -------- |86| Transform body is `return f"..."` or `"\n".join([...])` built from query results | Jinja2 template file | [yagni-python-transform-that-could-be-jinja2](../infrahub-auditing-repo/rules/yagni-python-transform-that-could-be-jinja2.md) |87| Transform copies query data verbatim without computation | The GraphQL query alone — no transform needed | Ladder step 1 (drop the requirement); judgment call, no rule |88| Conditionals are `if x: out += ...; else: out += ...` and nothing else | Jinja2 `{% if %}` blocks | [yagni-python-transform-that-could-be-jinja2](../infrahub-auditing-repo/rules/yagni-python-transform-that-could-be-jinja2.md) |8990Use Python when the transform parses, computes, or91reshapes — IP/subnet math, hashing, ordered92aggregation, structural JSON re-shaping. See93[rules/python-transform.md](./rules/python-transform.md)94for the legitimate cases.9596When the transform reads objects through the SDK, type those calls with97generated protocol classes rather than string kinds — `client.filters(NetworkLink, ...)`,98not `kind="NetworkLink"` — so schema drift fails type-check instead of at99runtime. See100[protocols-adopt-typed-kinds](../infrahub-common/rules/protocols-adopt-typed-kinds.md).101102## Transform Basics103104Two types of transforms:105106| Type | Output | Entry Point |107| ---------- | ----------------- | ------------------------------- |108| **Python** | JSON/dict or text | `InfrahubTransform.transform()` |109| **Jinja2** | Text | `.j2` template file |110111```python112from infrahub_sdk.transforms import InfrahubTransform113114class MyTransform(InfrahubTransform):115 query = "my_query"116117 async def transform(self, data: dict) -> dict:118 device = data["DcimDevice"]["edges"][0]["node"]119 return {"hostname": device["name"]["value"]}120```121122## Workflow123124Follow these steps when creating a transform:1251261. **Choose the transform type** — Python for JSON/dict127 or complex logic, Jinja2 for text templates, hybrid128 for both. Read129 [rules/types-overview.md](./rules/types-overview.md).1302. **Write the GraphQL query** — Create a `.gql` file131 that fetches the data to transform. Read132 [../infrahub-common/graphql-queries.md](../infrahub-common/graphql-queries.md)133 for query patterns.1343. **Implement the transform** — For Python, inherit135 from `InfrahubTransform` and implement `transform()`.136 Read [rules/python-transform.md](./rules/python-transform.md).137 For Jinja2, create a `.j2` template. Read138 [rules/jinja2-template.md](./rules/jinja2-template.md).139 For hybrid, read140 [rules/hybrid-python-jinja2.md](./rules/hybrid-python-jinja2.md).1414. **Connect to artifacts** — If the transform output142 should be stored as a file, configure artifact143 definitions. See144 [rules/artifacts-definitions.md](./rules/artifacts-definitions.md).1455. **Register in .infrahub.yml** — Add under146 `python_transforms` or `jinja2_transforms`. See147 [rules/api-reference.md](./rules/api-reference.md).1486. **Add tests** — Create YAML-driven test definitions149 (smoke, unit, integration) alongside the transform so150 it is validated automatically in the proposed change151 pipeline. Read152 [rules/testing-resource-framework.md](./rules/testing-resource-framework.md).1537. **Test locally** — Run `infrahubctl transform` or154 `infrahubctl render` to validate. See155 [rules/testing-commands.md](./rules/testing-commands.md).156157## Supporting References158159- **[reference.md](./reference.md)** -- Class API,160 lifecycle, return-type matrix, `.infrahub.yml`161 registration shapes, filter env overview162- **[examples.md](./examples.md)** -- Complete transform163 patterns (Python, Jinja2, hybrid, CSV)164- **[../infrahub-common/graphql-queries.md](../infrahub-common/graphql-queries.md)**165 -- GraphQL query writing reference166- **[infrahub-yml-reference.md](../infrahub-common/infrahub-yml-reference.md)**167 -- .infrahub.yml project configuration168- **[../infrahub-common/rules/](../infrahub-common/rules/)** -- Shared rules169 (git integration, caching) across all skills170- **[../infrahub-common/rules/workflow-information-priority.md](../infrahub-common/rules/workflow-information-priority.md)**171 -- Skill content first; how to consult `docs.infrahub.app`172 on a genuine gap (e.g. deleting nodes)173- **[../infrahub-managing-schemas/SKILL.md](../infrahub-managing-schemas/SKILL.md)**174 -- Schema definitions transforms work with175- **[rules/](./rules/)** -- Individual rules by category