infrahub-managing-generators

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Infrahub Generator Creator

Infrahub生成器创建指南

Overview

概述

Expert guidance for creating Infrahub Generators. Generators query data from Infrahub via GraphQL and create new nodes and relationships based on the result -- enabling design-driven automation where a "design" object automatically creates downstream infrastructure.

提供创建Infrahub生成器的专业指导。生成器通过GraphQL从Infrahub查询数据，并根据查询结果创建新节点和关系——实现由设计驱动的自动化，即“设计”对象可自动创建下游基础设施。

Project Context

项目上下文

Infrahub config: !

cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"

Existing generators: !

find . -name "*.py" -path "*/generators/*" 2>/dev/null | head -20

Infrahub配置： !

cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"

现有生成器： !

find . -name "*.py" -path "*/generators/*" 2>/dev/null | head -20

When to Use

适用场景

Building design-driven automation (topology -> devices)
Creating objects from templates or design definitions
Implementing idempotent create-or-update workflows
Auto-generating infrastructure from high-level designs
Understanding the generator tracking system

构建设计驱动的自动化（拓扑 -> 设备）
从模板或设计定义创建对象
实现幂等性的创建或更新工作流
从高层设计自动生成基础设施
了解生成器跟踪系统

Rule Categories

规则分类

Priority	Category	Prefix	Description
CRITICAL	Architecture	`architecture-`	Components, groups
CRITICAL	Python Class	`python-`	Generator, generate()
HIGH	Tracking	`tracking-`	Upsert, idempotent
HIGH	API Ref	`api-`	Constructor, props
HIGH	Registration	`registration-`	.infrahub.yml config
MEDIUM	Patterns	`patterns-`	Cleaning, batch, store
LOW	Testing	`testing-`	infrahubctl commands

优先级	分类	前缀	描述
关键	架构	`architecture-`	组件、组
关键	Python类	`python-`	生成器、generate()方法
高	跟踪	`tracking-`	插入更新、幂等性
高	API参考	`api-`	构造函数、属性
高	注册	`registration-`	.infrahub.yml配置
中	模式	`patterns-`	清理、批量处理、存储
低	测试	`testing-`	infrahubctl命令

Generator Basics

生成器基础

Every generator has three components:

Target group -- objects that trigger the generator
GraphQL query (
```
.gql
```
file) -- fetches the design data
Python class -- inherits from
```
InfrahubGenerator
```
, implements
```
generate()
```

python

from infrahub_sdk.generator import InfrahubGenerator

class MyGenerator(InfrahubGenerator):
    async def generate(self, data: dict) -> None:
        obj = await self.client.create(
            kind="DcimDevice",
            data={"name": "spine-01"},
        )
        await obj.save(allow_upsert=True)

每个生成器包含三个组件：

目标组 —— 触发生成器的对象
GraphQL查询（
```
.gql
```
文件）—— 获取设计数据
Python类 —— 继承自
```
InfrahubGenerator
```
，实现
```
generate()
```
方法

python

from infrahub_sdk.generator import InfrahubGenerator

class MyGenerator(InfrahubGenerator):
    async def generate(self, data: dict) -> None:
        obj = await self.client.create(
            kind="DcimDevice",
            data={"name": "spine-01"},
        )
        await obj.save(allow_upsert=True)

Workflow

工作流程

Follow these steps when creating a generator:

Identify the design pattern — What "design" object triggers generation? What objects should be created from it? Read rules/architecture-components.md for the target group and generator components.
Write the GraphQL query — Create a
```
.gql
```
file that fetches the design data. Read ../infrahub-common/graphql-queries.md for query patterns.
Implement the Python class — Inherit from
```
InfrahubGenerator
```
, implement
```
generate()
```
. Read rules/python-generate.md for the class pattern and rules/api-reference.md for available methods.
Make it idempotent — Use
```
allow_upsert=True
```
so re-running creates or updates without duplicates. See rules/tracking-idempotent.md.
Register in .infrahub.yml — Add under
```
generator_definitions
```
with the target group. See rules/registration-config.md.
Test — Run
```
infrahubctl generator
```
to validate. See rules/testing-commands.md.

创建生成器请遵循以下步骤：

确定设计模式 —— 哪些“设计”对象会触发生成？要从中创建哪些对象？请阅读rules/architecture-components.md了解目标组和生成器组件。
编写GraphQL查询 —— 创建一个
```
.gql
```
文件来获取设计数据。请阅读../infrahub-common/graphql-queries.md了解查询模式。
实现Python类 —— 继承自
```
InfrahubGenerator
```
，实现
```
generate()
```
方法。请阅读rules/python-generate.md了解类模式，阅读rules/api-reference.md了解可用方法。
实现幂等性 —— 使用
```
allow_upsert=True
```
，确保重新运行时可创建或更新对象而不产生重复。请查看rules/tracking-idempotent.md。
在.infrahub.yml中注册 —— 在
```
generator_definitions
```
下添加目标组。请查看rules/registration-config.md。
测试 —— 运行
```
infrahubctl generator
```
进行验证。请查看rules/testing-commands.md。

Supporting References

参考资料

examples.md -- Complete Generator patterns (POP topology, network segment, minimal)
../infrahub-common/graphql-queries.md -- GraphQL query writing reference
../infrahub-common/infrahub-yml-reference.md -- .infrahub.yml project configuration
../infrahub-common/rules/ -- Shared rules (git integration, caching gotchas)
../infrahub-managing-schemas/SKILL.md -- Schema definitions Generators work with
rules/ -- Individual rules organized by category prefix

examples.md —— 完整的生成器模式（POP拓扑、网段、最简示例）
../infrahub-common/graphql-queries.md —— GraphQL查询编写参考
../infrahub-common/infrahub-yml-reference.md —— .infrahub.yml项目配置参考
../infrahub-common/rules/ —— 通用规则（Git集成、缓存注意事项）
../infrahub-managing-schemas/SKILL.md —— 生成器适用的模式定义
rules/ —— 按分类前缀整理的独立规则