Managing Generators Skill
Relevant source files
The following files were used as context for generating this wiki page:
The infrahub-managing-generators skill provides expert guidance for building, modifying, and debugging design-driven automation within Infrahub. It focuses on creating idempotent InfrahubGenerator implementations that automate infrastructure tasks, such as creating BGP sessions or managing fabric designs. The skill covers both the structural architecture of generators and the specific Python SDK integration required to interact with the Infrahub server effectively.
Sources: README.md:92-93, README.md:162-163, dev/specs/2026-05-18-managing-generators-integration-rules-design.md:12-14
Generator Architecture and Integration
Generators in Infrahub bridge the gap between user intent and automated object creation. The Managing Generators skill organizes guidance into two primary layers: schema-layer concerns and integration-layer details. The integration layer specifically addresses common pitfalls in the Python SDK, such as relationship management and uniqueness collisions.
Sources: dev/specs/2026-05-18-managing-generators-integration-rules-design.md:12-16
Core Integration Rules
| Rule Category | Description | SDK Pattern |
|---|---|---|
| Relationship References | Defines how to link objects via the SDK. | Use {"hfid": ["<name>"]} or SDK object references. |
| Multi-Peer Operations | Manages adding multiple peers to a relationship. | Iterate peers and call .add() individually. |
| Natural Key Preflight | Handles uniqueness collisions for seeded data. | Use save(allow_upsert=True) or pre-flight client.get. |
| Integration Testing | Verifies logic against a live server. | infrahubctl generator run <name>. |
Sources: dev/specs/2026-05-18-managing-generators-integration-rules-design.md:43-89
SDK Data Flow
The following diagram illustrates the workflow for creating or updating objects within a generator to ensure idempotency and correct relationship mapping.
Implementation Standards
Relationship Management
Generators must use specific formats for relationship fields in client.create() to avoid runtime errors. A bare string is interpreted as a direct UUID lookup and fails if the string is not a valid UUID.
- HFID Lookup:
{"hfid": ["<part-a>", "<part-b>"]}. The list length must match the schema'shuman_friendly_iddefinition. - SDK Object Reference: Passing a variable returned by
client.getorclient.create. - Explicit ID:
{"id": "<uuid>"}.
Sources: dev/specs/2026-05-18-managing-generators-integration-rules-design.md:46-56
Relationship Manager Operations
When dealing with multiple peers (e.g., adding members to a group), the RelationshipManager.add() method requires one peer per call. Passing a list literal to a single .add() call results in incorrect mutation shapes.
# Correct Pattern: Iteration
for peer in peer_collection:
group.members.add(peer)
group.save()
Sources: dev/specs/2026-05-18-managing-generators-integration-rules-design.md:58-65
Testing and Validation
Verification of generator logic requires integration testing against a live Infrahub instance. Unit tests on input dictionaries often fail to catch SDK call shape errors, such as over-packed HFID lists or bare string relationship references.
Skill Components
The infrahub-managing-generators skill follows the standard Agent Skills anatomy, consisting of a central navigator and supporting rule files.
| Component | Function | File Path |
|---|---|---|
| SKILL.md | Entry point; provides overview and workflow navigation. | skills/infrahub-managing-generators/SKILL.md |
| Rule Index | Categorizes rules by prefix (python, patterns, testing). | skills/infrahub-managing-generators/rules/_sections.md |
| Python Rules | Guidance on SDK usage and code patterns. | skills/infrahub-managing-generators/rules/python-*.md |
| Architecture | Details on generator structure and logic. | skills/infrahub-managing-generators/rules/architecture-components.md |
Sources: dev/guides/adding-a-skill.md:9-18, dev/specs/2026-05-18-managing-generators-integration-rules-design.md:87-92
Information Priority
When working with generators, you must prioritize the skill's specific rules and reference files over external documentation. The curated rules in rules/ and infrahub-common/ encode specific version-matched constraints and SDK gotchas that generic training or web searches may miss.
Sources: skills/infrahub-common/rules/workflow-information-priority.md:12-25
The Managing Generators skill ensures that automation logic is not only syntactically correct but also compatible with Infrahub's data model and SDK constraints. By enforcing specific relationship patterns and pre-flight checks, it prevents common runtime failures in complex automation pipelines.