Infrahub Managing Generators

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

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:

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:

1. Target group -- objects that trigger the generator
2. GraphQL query (.gql file) -- fetches the design data
3. 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:

1. 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.
2. Write the GraphQL query — Create a .gql file that fetches the design data. Read ../infrahub-common/graphql-queries.md for query patterns.
3. 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.
4. Make it idempotent — Use allow_upsert=True so re-running creates or updates without duplicates. See rules/tracking-idempotent.md.
5. 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.
6. Register in .infrahub.yml — Add under generator_definitions with the target group. See rules/registration-config.md.
7. Test — Run infrahubctl generator to validate. See rules/testing-commands.md.

Supporting References

• reference.md -- Class API, lifecycle, idempotency contract, .infrahub.yml registration (with the query:-required shape that differs from check_definitions)
• 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/marketplace-reference.md -- reuse a marketplace-published schema for the target data model before hand-rolling one to generate against
• ../infrahub-common/rules/ -- Shared rules (git integration, caching gotchas)
• ../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 -- Schema definitions Generators work with
• rules/ -- Individual rules organized by category prefix