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.

Ver código-fonte

Como usar

  1. Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
  2. Consulte no original as ferramentas, credenciais e ambientes necessários.
  3. Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/opsmill/infrahub-skills --skill infrahub-managing-transforms

Antes de começar

  • A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
  • Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Documento original do Skill

Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.

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
do mesmo repositório

Mais Skills

Todos os Skills
opsmill
Comunidade

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

Instalações / 1h
2
GitHub Stars
27
Atualizado
9 de nov.
opsmill
Comunidade

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

Instalações / 1h
3
GitHub Stars
27
Atualizado
9 de nov.
opsmill
Comunidade

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).

Instalações / 1h
3
GitHub Stars
27
Atualizado
9 de nov.
opsmill
Comunidade

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

Instalações / 1h
3
GitHub Stars
27
Atualizado
9 de nov.