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 |
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.
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-23description: "Creates Infrahub Generators — design-driven automation that builds infrastructure objects from templates and topology definitions. TRIGGER when: building design-to-implementation workflows, auto-creating objects from templates, topology-driven generation. DO NOT TRIGGER when: designing schemas, writing data transforms, querying live data, populating static data files."4---56# Infrahub Generator Creator78## Overview910Expert guidance for creating Infrahub Generators. Generators11query data from Infrahub via GraphQL and create new nodes and12relationships based on the result -- enabling design-driven13automation where a "design" object automatically creates14downstream infrastructure.1516## Project Context1718Infrahub config:19!`cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"`2021Existing generators:22!`find . -name "*.py" -path "*/generators/*" 2>/dev/null | head -20`2324## When to Use2526- Building design-driven automation (topology -> devices)27- Creating objects from templates or design definitions28- Implementing idempotent create-or-update workflows29- Auto-generating infrastructure from high-level designs30- Understanding the generator tracking system3132## Rule Categories3334| Priority | Category | Prefix | Description |35| -------- | ------------ | --------------- | ---------------------- |36| CRITICAL | Architecture | `architecture-` | Components, groups |37| CRITICAL | Python Class | `python-` | Generator, generate() |38| HIGH | Tracking | `tracking-` | Upsert, idempotent |39| HIGH | API Ref | `api-` | Constructor, props |40| HIGH | Registration | `registration-` | .infrahub.yml config |41| MEDIUM | Patterns | `patterns-` | Cleaning, batch, store |42| LOW | Testing | `testing-` | infrahubctl commands |4344## Schema Features This Skill Depends On4546Generators create real objects, so the schema must47permit the shape they emit. Catch these gaps before48the first run — re-running a buggy generator can49delete data via the tracking cleanup.5051| If the generator... | The schema must... | See |52| ------------------- | ------------------ | --- |53| 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) |54| 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) |55| 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) |56| 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) |57| 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) |5859## Before writing Python6061A generator should *compute* objects from a design. If62what you're about to write is "make these N specific63objects from a hardcoded list," that list is data —64move it to `objects/` and either let the object65loader handle it directly or pass it into a smaller66generator. Walk this ladder before reaching for67`InfrahubGenerator`:6869| Signal | Cheaper layer | See rule |70| ------ | ------------- | -------- |71| 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) |72| 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) |73| 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) |74| 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) |7576Bootstrap, seed, and demo generators (under77`bootstrap/`, `seed/`, `demo/`) are exempt — they78exist specifically to hardcode initial state. Use79Python when the generator is genuinely computing80objects from a design definition; see81[rules/python-generate.md](./rules/python-generate.md)82for the legitimate cases.8384## Generator Basics8586Every generator has three components:87881. **Target group** -- objects that trigger the generator892. **GraphQL query** (`.gql` file) -- fetches the design data903. **Python class** -- inherits from `InfrahubGenerator`,91 implements `generate()`9293```python94from infrahub_sdk.generator import InfrahubGenerator9596class MyGenerator(InfrahubGenerator):97 async def generate(self, data: dict) -> None:98 obj = await self.client.create(99 kind="DcimDevice",100 data={"name": "spine-01"},101 )102 await obj.save(allow_upsert=True)103```104105## Workflow106107Follow these steps when creating a generator:1081091. **Identify the design pattern** — What "design"110 object triggers generation? What objects should be111 created from it? Read112 [rules/architecture-components.md](./rules/architecture-components.md)113 for the target group and generator components.1142. **Write the GraphQL query** — Create a `.gql` file115 that fetches the design data. Read116 [../infrahub-common/graphql-queries.md](../infrahub-common/graphql-queries.md)117 for query patterns.1183. **Implement the Python class** — Inherit from119 `InfrahubGenerator`, implement `generate()`. Read120 [rules/python-generate.md](./rules/python-generate.md)121 for the class pattern and122 [rules/api-reference.md](./rules/api-reference.md)123 for available methods.1244. **Make it idempotent** — Use `allow_upsert=True` so125 re-running creates or updates without duplicates.126 See [rules/tracking-idempotent.md](./rules/tracking-idempotent.md).1275. **Check for `from_graphql` adoption opportunity** — if128 `generate()` iterates response edges and calls129 `self.client.get()` to re-fetch typed peers, consider130 refactoring to `InfrahubNode.from_graphql()` to collapse131 `O(N + 1)` round trips to `O(1)`. Read132 [rules/patterns-hydration.md](./rules/patterns-hydration.md)133 for the decision tree, detection heuristic, and refactor134 recipe.1356. **Register in .infrahub.yml** — Add under136 `generator_definitions` with the target group. See137 [rules/registration-config.md](./rules/registration-config.md).1387. **Test** — Run `infrahubctl generator` to validate.139 See [rules/testing-commands.md](./rules/testing-commands.md).140141## Supporting References142143- **[reference.md](./reference.md)** -- Class API,144 lifecycle, idempotency contract, `.infrahub.yml`145 registration (with the `query:`-required shape that146 differs from check_definitions)147- **[examples.md](./examples.md)** -- Complete Generator148 patterns (POP topology, network segment, minimal)149- **[../infrahub-common/graphql-queries.md](../infrahub-common/graphql-queries.md)**150 -- GraphQL query writing reference151- **[../infrahub-common/infrahub-yml-reference.md](../infrahub-common/infrahub-yml-reference.md)**152 -- .infrahub.yml project configuration153- **[../infrahub-common/rules/](../infrahub-common/rules/)** -- Shared rules154 (git integration, caching gotchas)155- **[../infrahub-managing-schemas/SKILL.md](../infrahub-managing-schemas/SKILL.md)**156 -- Schema definitions Generators work with157- **[rules/](./rules/)** -- Individual rules organized by158 category prefix