Infrahub Generator Creator
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.
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
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 |
Schema Features This Skill Depends On
Generators create real objects, so the schema must
permit the shape they emit. Catch these gaps before
the first run — re-running a buggy generator can
delete data via the tracking cleanup.
Before writing Python
A generator should compute objects from a design. If
what you're about to write is "make these N specific
objects from a hardcoded list," that list is data —
move it to objects/ and either let the object
loader handle it directly or pass it into a smaller
generator. Walk this ladder before reaching for
InfrahubGenerator:
| Signal |
Cheaper layer |
See rule |
| Generator hardcodes object lists, role catalogs, or status sets |
YAML data files under objects/ (loaded by the object loader) |
yagni-generator-hardcoding-data |
| Generator recreates a built-in IPAM/VLAN primitive (custom IP address, prefix, VLAN nodes) |
inherit_from: [BuiltinIPAddress / BuiltinIPPrefix / IpamVLAN] in the schema, then the generator computes references rather than reimplementing the primitive |
yagni-custom-domain-primitives-instead-of-builtin |
Generator's output shape duplicates objects already in opsmill/schema-library |
inherit_from a library generic; the generator computes the instance but not the shape |
yagni-duplicate-shape-not-extracted-to-generic |
Generator allocates a subnet/IP/VLAN/port with ipaddress math, random, or a hand-written "find the first free one" loop |
A built-in resource pool — allocate_next_ip_prefix / allocate_next_ip_address, CoreIPPrefixPool / CoreNumberPool — which tracks utilization and stays idempotent across re-runs |
yagni-imperative-allocation-vs-resource-pool |
generate() stamps a fixed set of children with constant values and no computation (no branching, derived naming, or allocation) |
An Object Template (generate_template: true) users clone — the structure lives in data, not Python |
yagni-generator-that-should-be-template |
Bootstrap, seed, and demo generators (under
bootstrap/, seed/, demo/) are exempt — they
exist specifically to hardcode initial state. Use
Python when the generator is genuinely computing
objects from a design definition; see
rules/python-generate.md
for the legitimate cases.
Once you are writing Python, type your SDK calls with generated protocol
classes rather than string kinds — client.create(NetworkDevice, ...), not
kind="NetworkDevice" — so a schema change fails type-check instead of at
runtime. See
protocols-adopt-typed-kinds.
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()
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.
- Check for
from_graphql adoption opportunity — if
generate() iterates response edges and calls
self.client.get() to re-fetch typed peers, consider
refactoring to InfrahubNode.from_graphql() to collapse
O(N + 1) round trips to O(1). Read
rules/patterns-hydration.md
for the decision tree, detection heuristic, and refactor
recipe.
- 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.
Supporting References
1---2name: infrahub-managing-generators-33description: >-4 Creates Infrahub Generators — design-driven automation that builds infrastructure objects from templates and topology definitions.5 TRIGGER when: building design-to-implementation workflows, auto-creating objects from templates, topology-driven generation.6 DO NOT TRIGGER when: designing schemas, writing data transforms, querying live data, populating static data files.7allowed-tools:8 - Read9 - Write10 - Edit11 - Bash12 - Grep13argument-hint: "[generator-name] [description...]"14metadata:15 source: https://skillmd.com/skills/opsmill/infrahub-managing-generators-316 version: 1.2.817 author: OpsMill18---1920# Infrahub Generator Creator2122## Overview2324Expert guidance for creating Infrahub Generators. Generators25query data from Infrahub via GraphQL and create new nodes and26relationships based on the result -- enabling design-driven27automation where a "design" object automatically creates28downstream infrastructure.2930## Project Context3132Infrahub config:33!`cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"`3435Existing generators:36!`find . -name "*.py" -path "*/generators/*" 2>/dev/null | head -20`3738## When to Use3940- Building design-driven automation (topology -> devices)41- Creating objects from templates or design definitions42- Implementing idempotent create-or-update workflows43- Auto-generating infrastructure from high-level designs44- Understanding the generator tracking system4546## Rule Categories4748| Priority | Category | Prefix | Description |49| -------- | ------------ | --------------- | ---------------------- |50| CRITICAL | Architecture | `architecture-` | Components, groups |51| CRITICAL | Python Class | `python-` | Generator, generate() |52| HIGH | Tracking | `tracking-` | Upsert, idempotent |53| HIGH | API Ref | `api-` | Constructor, props |54| HIGH | Registration | `registration-` | .infrahub.yml config |55| MEDIUM | Patterns | `patterns-` | Cleaning, batch, store |56| LOW | Testing | `testing-` | infrahubctl commands |5758## Schema Features This Skill Depends On5960Generators create real objects, so the schema must61permit the shape they emit. Catch these gaps before62the first run — re-running a buggy generator can63delete data via the tracking cleanup.6465| If the generator... | The schema must... | See |66| ------------------- | ------------------ | --- |67| Creates objects of kind X | Have node X defined with the attributes the generator sets — extra attributes silently fail validation, missing required ones abort the create | [../infrahub-managing-schemas/rules/attribute-defaults-and-types.md](../infrahub-managing-schemas/rules/attribute-defaults-and-types.md) |68| Links the created object to a parent | Have a Component/Parent relationship pair with matching identifiers and `optional: false` on the Parent side | [../infrahub-managing-schemas/rules/relationship-component-parent.md](../infrahub-managing-schemas/rules/relationship-component-parent.md) |69| Reads a "design" node to drive output | Define that node's `human_friendly_id` so the generator's tracking key stays stable across runs | [../infrahub-managing-schemas/rules/display-human-friendly-id.md](../infrahub-managing-schemas/rules/display-human-friendly-id.md) |70| Is triggered by membership in a group | The target group must be a `CoreGeneratorGroup` (not `CoreStandardGroup`) — the dispatcher only recognizes the former | [rules/registration-config.md](./rules/registration-config.md) |71| Should be idempotent on re-run | Every `save()` uses `allow_upsert=True`; the run's tracking context deletes objects from prior runs that aren't recreated | [rules/tracking-idempotent.md](./rules/tracking-idempotent.md) |7273## Before writing Python7475A generator should *compute* objects from a design. If76what you're about to write is "make these N specific77objects from a hardcoded list," that list is data —78move it to `objects/` and either let the object79loader handle it directly or pass it into a smaller80generator. Walk this ladder before reaching for81`InfrahubGenerator`:8283| Signal | Cheaper layer | See rule |84| ------ | ------------- | -------- |85| Generator hardcodes object lists, role catalogs, or status sets | YAML data files under `objects/` (loaded by the object loader) | [yagni-generator-hardcoding-data](../infrahub-auditing-repo/rules/yagni-generator-hardcoding-data.md) |86| Generator recreates a built-in IPAM/VLAN primitive (custom IP address, prefix, VLAN nodes) | `inherit_from: [BuiltinIPAddress / BuiltinIPPrefix / IpamVLAN]` in the schema, then the generator computes references rather than reimplementing the primitive | [yagni-custom-domain-primitives-instead-of-builtin](../infrahub-auditing-repo/rules/yagni-custom-domain-primitives-instead-of-builtin.md) |87| Generator's output shape duplicates objects already in `opsmill/schema-library` | `inherit_from` a library generic; the generator computes the *instance* but not the *shape* | [yagni-duplicate-shape-not-extracted-to-generic](../infrahub-auditing-repo/rules/yagni-duplicate-shape-not-extracted-to-generic.md) |88| Generator allocates a subnet/IP/VLAN/port with `ipaddress` math, `random`, or a hand-written "find the first free one" loop | A built-in resource pool — `allocate_next_ip_prefix` / `allocate_next_ip_address`, `CoreIPPrefixPool` / `CoreNumberPool` — which tracks utilization and stays idempotent across re-runs | [yagni-imperative-allocation-vs-resource-pool](../infrahub-auditing-repo/rules/yagni-imperative-allocation-vs-resource-pool.md) |89| `generate()` stamps a fixed set of children with constant values and no computation (no branching, derived naming, or allocation) | An Object Template (`generate_template: true`) users clone — the structure lives in data, not Python | [yagni-generator-that-should-be-template](../infrahub-auditing-repo/rules/yagni-generator-that-should-be-template.md) |9091Bootstrap, seed, and demo generators (under92`bootstrap/`, `seed/`, `demo/`) are exempt — they93exist specifically to hardcode initial state. Use94Python when the generator is genuinely computing95objects from a design definition; see96[rules/python-generate.md](./rules/python-generate.md)97for the legitimate cases.9899Once you *are* writing Python, type your SDK calls with generated protocol100classes rather than string kinds — `client.create(NetworkDevice, ...)`, not101`kind="NetworkDevice"` — so a schema change fails type-check instead of at102runtime. See103[protocols-adopt-typed-kinds](../infrahub-common/rules/protocols-adopt-typed-kinds.md).104105## Generator Basics106107Every generator has three components:1081091. **Target group** -- objects that trigger the generator1102. **GraphQL query** (`.gql` file) -- fetches the design data1113. **Python class** -- inherits from `InfrahubGenerator`,112 implements `generate()`113114```python115from infrahub_sdk.generator import InfrahubGenerator116117class MyGenerator(InfrahubGenerator):118 async def generate(self, data: dict) -> None:119 obj = await self.client.create(120 kind="DcimDevice",121 data={"name": "spine-01"},122 )123 await obj.save(allow_upsert=True)124```125126## Workflow127128Follow these steps when creating a generator:1291301. **Identify the design pattern** — What "design"131 object triggers generation? What objects should be132 created from it? Read133 [rules/architecture-components.md](./rules/architecture-components.md)134 for the target group and generator components.1352. **Write the GraphQL query** — Create a `.gql` file136 that fetches the design data. Read137 [../infrahub-common/graphql-queries.md](../infrahub-common/graphql-queries.md)138 for query patterns.1393. **Implement the Python class** — Inherit from140 `InfrahubGenerator`, implement `generate()`. Read141 [rules/python-generate.md](./rules/python-generate.md)142 for the class pattern and143 [rules/api-reference.md](./rules/api-reference.md)144 for available methods.1454. **Make it idempotent** — Use `allow_upsert=True` so146 re-running creates or updates without duplicates.147 See [rules/tracking-idempotent.md](./rules/tracking-idempotent.md).1485. **Check for `from_graphql` adoption opportunity** — if149 `generate()` iterates response edges and calls150 `self.client.get()` to re-fetch typed peers, consider151 refactoring to `InfrahubNode.from_graphql()` to collapse152 `O(N + 1)` round trips to `O(1)`. Read153 [rules/patterns-hydration.md](./rules/patterns-hydration.md)154 for the decision tree, detection heuristic, and refactor155 recipe.1566. **Register in .infrahub.yml** — Add under157 `generator_definitions` with the target group. See158 [rules/registration-config.md](./rules/registration-config.md).1597. **Test** — Run `infrahubctl generator` to validate.160 See [rules/testing-commands.md](./rules/testing-commands.md).161162## Supporting References163164- **[reference.md](./reference.md)** -- Class API,165 lifecycle, idempotency contract, `.infrahub.yml`166 registration (with the `query:`-required shape that167 differs from check_definitions)168- **[examples.md](./examples.md)** -- Complete Generator169 patterns (POP topology, network segment, minimal)170- **[../infrahub-common/graphql-queries.md](../infrahub-common/graphql-queries.md)**171 -- GraphQL query writing reference172- **[../infrahub-common/infrahub-yml-reference.md](../infrahub-common/infrahub-yml-reference.md)**173 -- .infrahub.yml project configuration174- **[../infrahub-common/marketplace-reference.md](../infrahub-common/marketplace-reference.md)**175 -- reuse a marketplace-published schema for the target176 data model before hand-rolling one to generate against177- **[../infrahub-common/rules/](../infrahub-common/rules/)** -- Shared rules178 (git integration, caching gotchas)179- **[../infrahub-common/rules/workflow-information-priority.md](../infrahub-common/rules/workflow-information-priority.md)**180 -- Skill content first; how to consult `docs.infrahub.app`181 on a genuine gap (e.g. deleting nodes)182- **[../infrahub-managing-schemas/SKILL.md](../infrahub-managing-schemas/SKILL.md)**183 -- Schema definitions Generators work with184- **[rules/](./rules/)** -- Individual rules organized by185 category prefix