infrahub-managing-transforms

Infrahub 转换创建器

概述

关于创建 Infrahub 转换的专家指导。 转换可将 Infrahub 数据转换为不同格式 —— JSON、文本、CSV、设备配置或任何基于文本的 输出 —— 使用 Python 类或 Jinja2 模板。

项目上下文

Infrahub 配置： !cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"

现有转换： !find . -name "*.py" -path "*/transforms/*" -o -name "*.j2" -path "*/templates/*" 2>/dev/null | head -20

适用场景

• 构建数据转换（Infrahub 数据 -> 另一种格式）
• 根据基础设施数据生成设备配置
• 创建 CSV 报告、线缆矩阵或库存导出文件
• 使用查询数据渲染 Jinja2 模板
• 将 Python 逻辑与 Jinja2 渲染结合使用
• 将转换连接到构件，以实现自动化输出
• 更改现有转换或模板的渲染结果
• 调试错误的输出，或生成失败的构件

规则类别

优先级	类别	前缀	描述
CRITICAL	类型	types-	Python 与 Jinja2 的选择
CRITICAL	Python	python-	InfrahubTransform 类
CRITICAL	Jinja2	jinja2-	模板语法、过滤器
HIGH	混合	hybrid-	Python + Jinja2 组合
HIGH	构件	artifacts-	输出文件、目标
HIGH	API 参考	api-	类属性、方法
MEDIUM	模式	patterns-	工具函数、CSV、共享
HIGH	测试	testing-	Resources Testing Framework、转换/渲染命令

此技能依赖的 Schema 功能

转换会读取 Schema 形状的数据并生成文件。转换与 Schema 不匹配会导致问题延迟暴露——直到制品渲染时， 也就是有人正等着输出的时候。

如果转换……	Schema（或 .infrahub.yml）必须……	参见
将为 artifact_definitions 条目提供数据	目标节点必须 inherit_from: CoreArtifactTarget，以便制品流水线能够关联到该节点	../infrahub-managing-schemas/rules/extension-artifact-target.md
从节点读取属性	在 GraphQL 中定义这些属性及其完整的 __value 访问路径——访问节点而非值会导致静默返回空字符串	../infrahub-managing-schemas/rules/attribute-defaults-and-types.md
按平台/角色为每台设备选择模板	Schema 必须将该平台/角色公开为实际属性或关系——通过字符串匹配 display_label 并不可靠	../infrahub-managing-schemas/rules/display-human-friendly-id.md
在 artifact_definitions.transformation 中被引用	转换注册的 name 必须与 transformation: 字段完全一致——不匹配会在渲染时导致“未找到转换”	rules/artifacts-definitions.md
使用 Jinja2（而非 Python）	在 jinja2_transforms 下注册，并设置顶层 query: 字段——python_transforms 会将 query 绑定到类上，这两个键不能互换	rules/api-reference.md
是 Python 转换	添加 watch: 块，列出导入的所有一方模块——包括同级模块，因为系统不会追踪导入。缺少此键时，Infrahub 无法信任依赖列表，因此每次提交都会重新渲染制品	rules/artifacts-watch-dependencies.md
在运行时读取数据文件，或通过变量名包含模板	在 watch.files 中列出这些路径——检测机制无法识别仅以字符串形式存在的路径，因此发生更改时制品会过时，且不会报错	rules/artifacts-watch-dependencies.md
由调用方（目录页面、CI 作业、编排器）重新生成制品	调用方必须轮询 CoreArtifact，直到每个制品都准备好正文——POST 只会将重新生成操作加入队列，节点会在其内容生成前就已存在	rules/artifacts-async-regen-polling.md

编写 Python 之前

如果转换主体只是字符串格式化——f-string、 拼接、条件片段——Jinja2 能用更少的代码行表达 相同的输出，可直接在提议的变更界面中渲染， 并且配置在 .infrahub.yml 的 jinja2_transforms 下，而不是 python_transforms 下。在使用 InfrahubTransform 之前，先按顺序检查以下选项：

信号	更简单的实现层	参见规则
转换主体是由查询结果构建的 return f"..." 或 "\n".join([...])	Jinja2 模板文件	yagni-python-transform-that-could-be-jinja2
转换只是原样复制查询数据，不做计算	仅使用 GraphQL 查询——不需要转换	第 1 步（去掉需求）；视情况判断，没有对应规则
条件逻辑是 if x: out += ...; else: out += ...，且没有其他操作	Jinja2 {% if %} 代码块	yagni-python-transform-that-could-be-jinja2

在转换需要解析、计算或重塑数据时使用 Python—— 例如 IP/子网计算、哈希、有序聚合、结构化 JSON 重塑。 有关适用场景，请参阅 rules/python-transform.md。

如果转换通过 SDK 读取对象，请使用生成的协议类为这些调用提供类型， 而不是使用字符串类型——例如 client.filters(NetworkLink, ...)， 而不是 kind="NetworkLink"——这样在类型检查时，模式变更会导致返回 对象的属性读取报错。传给 create() 的字段名称不会进行类型检查。 请参阅 protocols-adopt-typed-kinds。

转换基础

转换有两种类型：

类型	输出	入口点
Python	由工件的 content_type 决定：仅当值为 application/json 或 application/yaml 时返回 dict，其他六种类型均返回 str	InfrahubTransform.transform()
Jinja2	文本	.j2 模板文件

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"]}

工作流

创建 transform 时，请按以下步骤操作：

1. 选择 transform 类型 — 对于 JSON/dict 或复杂逻辑，使用 Python；对于文本模板，使用 Jinja2；两者兼用则使用 hybrid。阅读 rules/types-overview.md。
2. 编写 GraphQL 查询 — 创建一个 .gql 文件 来获取要转换的数据。查询模式请阅读 ../infrahub-common/graphql-queries.md。
3. 实现 transform — 对于 Python，继承 InfrahubTransform 并实现 transform()。 阅读 rules/python-transform.md。 对于 Jinja2，创建一个 .j2 模板。阅读 rules/jinja2-template.md。 对于 hybrid，请阅读 rules/hybrid-python-jinja2.md。
4. 连接到 artifacts — 如果 transform 的输出 应存储为文件，请配置 artifact 定义。参见 rules/artifacts-definitions.md。
5. 在 .infrahub.yml 中注册 — 在 python_transforms 或 jinja2_transforms 下添加。参见 rules/api-reference.md。 然后使用 watch.files 声明 transform 的依赖项：检查入口点的导入和 运行时文件读取，并列出它们解析到的所有第一方路径。Python transform 应始终 包含此键——如果确实没有自身文件以外的依赖，则使用 files: []。阅读 rules/artifacts-watch-dependencies.md， 其中也介绍了如何检查现有 watch 块中是否有缺失、过时或错误的条目。
6. 添加测试 — 在 transform 旁创建由 YAML 驱动的测试定义 （smoke、unit、integration），以便在提议变更的 流水线中自动验证。阅读 rules/testing-resource-framework.md。
7. 在本地测试 — 运行 infrahubctl transform 或 infrahubctl render 进行验证。参见 rules/testing-commands.md。

参考资料

• rules/artifacts-definitions.md -- 八种 content_type 值，以及它们各自如何 序列化 transform 的返回值。关于某种 content type 接受哪种返回类型的权威说明
• reference.md -- 类 API、 生命周期、.infrahub.yml 注册格式、 filter 环境概览
• examples.md -- 完整的 transform 模式（Python、Jinja2、hybrid、CSV）
• ../infrahub-common/graphql-queries.md -- GraphQL 查询编写参考
• infrahub-yml-reference.md -- .infrahub.yml 项目配置
• ../infrahub-common/rules/ -- 所有技能共用的规则 （git 集成、缓存）
• ../infrahub-common/rules/workflow-information-priority.md -- 优先参考技能内容；在确有信息缺口时，如何查阅 docs.infrahub.app （例如，删除节点）
• ../infrahub-managing-schemas/SKILL.md -- transform 使用的 Schema 定义
• rules/ -- 按类别整理的各项规则