opsmill/infrahub-skills

infrahub-managing-transforms

Creates, modifies and debugs Infrahub transforms that convert data into JSON, text, CSV, or device configs using Python or Jinja2 templates, with YAML-driven tests.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/opsmill/infrahub-skills --skill infrahub-managing-transforms

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

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
  • Changing what an existing transform or template renders
  • Debugging wrong output, or an artifact that fails to generate

Rule Categories

PriorityCategoryPrefixDescription
CRITICALTypestypes-Python vs Jinja2 choice
CRITICALPythonpython-InfrahubTransform class
CRITICALJinja2jinja2-Template syntax, filters
HIGHHybridhybrid-Python + Jinja2 combined
HIGHArtifactsartifacts-Output files, targets
HIGHAPI Refapi-Class attrs, methods
MEDIUMPatternspatterns-Utilities, CSV, shared
HIGHTestingtesting-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.

If the transform...The schema (or .infrahub.yml) must...See
Will feed an artifact_definitions entryThe target node must inherit_from: CoreArtifactTarget so the artifact pipeline can attach to it../infrahub-managing-schemas/rules/extension-artifact-target.md
Reads attributes from a nodeDefine 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
Picks a template per device by platform/roleThe 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
Is referenced from artifact_definitions.transformationThe transform's registered name must match the transformation: field exactly — mismatch produces "transformation not found" at render timerules/artifacts-definitions.md
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 interchangeablerules/api-reference.md
Is a Python transformCarry a watch: block naming every first-party module it imports — sibling modules included, since imports are never followed. Without the key, Infrahub cannot trust the dependency list and re-renders the artifacts on every commitrules/artifacts-watch-dependencies.md
Reads a data file at runtime, or includes a template by variable nameName those paths in watch.files — detection cannot see a path that exists only as a string, so the artifacts go stale on a change with no error raisedrules/artifacts-watch-dependencies.md
Has its artifacts regenerated by a caller (catalog page, CI job, orchestrator)That caller must poll CoreArtifact until each artifact is body-ready — the POST only queues the regen, and the node exists before its content doesrules/artifacts-async-regen-polling.md

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:

SignalCheaper layerSee rule
Transform body is return f"..." or "\n".join([...]) built from query resultsJinja2 template fileyagni-python-transform-that-could-be-jinja2
Transform copies query data verbatim without computationThe GraphQL query alone — no transform neededLadder step 1 (drop the requirement); judgment call, no rule
Conditionals are if x: out += ...; else: out += ... and nothing elseJinja2 {% if %} blocksyagni-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 breaks attribute reads on the returned objects at type-check time. Field names passed to create() are not type-checked. See protocols-adopt-typed-kinds.

Transform Basics

Two types of transforms:

TypeOutputEntry Point
PythonWhatever the artifact's content_type asks for: a dict only under application/json or application/yaml, a str for the other sixInfrahubTransform.transform()
Jinja2Text.j2 template file
python
from infrahub_sdk.transforms import InfrahubTransform

class MyTransform(InfrahubTransform):
    query = "my_query"

    # Returns a dict, so the artifact definition has to declare
    # content_type: application/json (or application/yaml). Under any
    # other content type this dict is stored as str(dict), with no
    # error. See rules/artifacts-definitions.md.
    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.

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

that fetches the data to transform. Read ../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. For Jinja2, create a .j2 template. Read rules/jinja2-template.md. For hybrid, read 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.

  1. Register in .infrahub.yml — Add under

python_transforms or jinja2_transforms. See rules/api-reference.md. Then declare the transform's dependencies with watch.files: read the entry point's imports and runtime file reads, and name every first-party path they resolve to. A Python transform should always carry the key — files: [] when it genuinely has no dependency beyond its own file. Read rules/artifacts-watch-dependencies.md, which also covers reviewing an existing watch block for entries that are missing, stale, or wrong.

  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.

  1. Test locally — Run infrahubctl transform or

infrahubctl render to validate. See rules/testing-commands.md.

Supporting References

  • [rules/artifacts-definitions.md](./rules/artifacts-definitions.md)

-- The eight content_type values and how each serialises the transform's return value. Authority on which return type a content type accepts

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

lifecycle, .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
from this repository

More skills

All skills
opsmill
Community

infrahub-analyzing-diagnostics

Analyze an already-collected infrahub-collect diagnostic bundle — traceback and failure triage across service logs, incident correlation, and known-issue matching against opsmill/infrahub GitHub issues. TRIGGER when: the user says they collected a diagnostic bundle, gives you a bundle path, or pastes bundle contents — and asks what's wrong, wants the logs or tracebacks analyzed, asks "what does this bundle say", wants errors triaged/correlated, or asks whether a crash is a known issue. DO NOT TR

1h installs
2
GitHub stars
27
Updated
Nov 9
opsmill
Community

infrahub-analyzing-data

Analyzes and correlates live Infrahub data via the MCP server — answers operational questions, detects drift, and investigates impact. TRIGGER when: querying infrastructure data, checking compliance, investigating change impact, producing ad-hoc reports. DO NOT TRIGGER when: writing automated checks, building transforms, designing schemas, populating data files, planning an Infrahub version upgrade (use infrahub-planning-upgrades). ALWAYS pass the user's question verbatim as args — this skill ru

1h installs
3
GitHub stars
27
Updated
Nov 9
opsmill
Community

infrahub-auditing-repo

Audits an Infrahub repository against best practices and rules, producing a structured compliance report. TRIGGER when: reviewing repo for compliance, onboarding to existing project, pre-deployment validation, catching issues. DO NOT TRIGGER when: creating schemas, writing checks/generators, querying live data, populating objects, planning an Infrahub version upgrade (use infrahub-planning-upgrades).

1h installs
3
GitHub stars
27
Updated
Nov 9
opsmill
Community

infrahub-collecting-diagnostics

Collect a redacted local diagnostic bundle (logs, config, version, state) for an OpsMill expert hand-off. TRIGGER when: Infrahub is broken/failing/erroring, the user asks for help debugging, wants to collect logs/diagnostics, prepares a hand-off for OpsMill support, or reports a crash/timeout/connection issue (upgrade failure, stuck branch, container CrashLoopBackOff, 500s, OOM). DO NOT TRIGGER when: debugging a check, transform, generator, menu, or schema in the repository (use the infrahub-man

1h installs
3
GitHub stars
27
Updated
Nov 9