Object Creator
Overview
Expert guidance for creating Infrahub object (data) files.
Objects are YAML files that populate schema nodes with actual
infrastructure data -- devices, locations, organizations,
modules, and more.
Project Context
Existing schema files:
!find . -name "*.yml" -path "*/schemas/*" -o -name "*schema*" -name "*.yml" 2>/dev/null | head -10
Existing object files:
!find . -name "*.yml" -path "*/objects/*" 2>/dev/null | head -20
If invoked with arguments (e.g., /infrahub:managing-objects DcimDevice spine-01),
use the first argument as the kind and remaining arguments as object details.
When to Use
- Creating new data files for infrastructure objects
- Populating devices, locations, organizations, or other schema nodes
- Setting up hierarchical data (location trees, tenant groups)
- Referencing related objects across files
- Managing component children (interfaces, modules)
- Organizing object files for correct load order
Rule Categories
| Priority |
Category |
Prefix |
Description |
| CRITICAL |
Branch-First Loading |
workflow- |
Load onto a branch, not the default branch |
| CRITICAL |
File Format |
format- |
apiVersion, kind, spec structure |
| CRITICAL |
Value Mapping |
value- |
Attributes, dropdowns, references |
| HIGH |
Children |
children- |
Hierarchy/component nesting |
| MEDIUM |
Range |
range- |
Sequential interface expansion |
| MEDIUM |
Organization |
organization- |
Naming, load order, multi-doc |
| LOW |
Patterns |
patterns- |
Flat lists, devices, git repos |
Schema Features This Skill Depends On
Object files reference schema-defined shapes; missing
schema setup turns into "object failed to load" or
"reference not found" errors at sync time. Before
populating data, verify the schema upstream:
If any of these is missing, the schema needs an
update before the objects can load — that's a
schema migration, not an object fix.
Object File Basics
---
apiVersion: infrahub.app/v1
kind: Object
spec:
kind: <NodeKind> # Schema node kind (e.g., DcimDellServer)
data:
- <attribute>: <value> # List of object instances
apiVersion, kind: Object, spec.kind, and spec.data
are always required. Each spec block targets a single
node kind.
Workflow
Follow these steps when creating object data files:
- Plan to load onto a branch, not the default branch —
Decide the dedicated branch this data will load onto
before writing the files, and surface it when you hand
off the load commands. Loading into the default branch
(the target when no
--branch is given — main by
convention, but it can be renamed) writes unreviewed
data to the source of truth, and a bad bulk load there
means deleting objects one by one instead of discarding
a branch. Read
rules/workflow-branch-first.md.
The default branch is only reasonable on a local
throwaway instance.
- Read the schema — Identify the target node kind,
its attributes, relationships, and whether it has
component children or hierarchy parents.
- Plan the file structure — Read
rules/format-structure.md
for the required YAML structure and
rules/organization-load-order.md
for file naming and load order conventions.
- Map attribute values — Set each attribute using
the correct value format. Read
rules/value-attributes.md
for attribute mapping and
rules/value-relationships.md
for relationship references. To stamp lineage or lock
a value, write it as a
value + metadata mapping —
see ../infrahub-common/metadata-lineage.md
(remember source is lineage only; locking needs
owner + is_protected).
- Handle children — If the node has component
children or hierarchy nesting, read
rules/children-components.md
and rules/children-hierarchy.md.
- Validate and load on the branch — Check YAML syntax,
ensure referenced objects exist or are defined in
earlier load-order files, then validate and load against
your branch (
--branch). See
validation.md for the commands and
pre-load checklist.
Supporting References
1---2name: infrahub-managing-objects-23description: "Creates and manages Infrahub object data YAML files for populating infrastructure instances — devices, locations, organizations, and modules. TRIGGER when: creating device instances, populating data files, defining locations or organizations, adding infrastructure objects. DO NOT TRIGGER when: designing schemas, writing Python checks/generators, querying live data."4---56# Object Creator78## Overview910Expert guidance for creating Infrahub object (data) files.11Objects are YAML files that populate schema nodes with actual12infrastructure data -- devices, locations, organizations,13modules, and more.1415## Project Context1617Existing schema files:18!`find . -name "*.yml" -path "*/schemas/*" -o -name "*schema*" -name "*.yml" 2>/dev/null | head -10`1920Existing object files:21!`find . -name "*.yml" -path "*/objects/*" 2>/dev/null | head -20`2223If invoked with arguments (e.g., `/infrahub:managing-objects DcimDevice spine-01`),24use the first argument as the kind and remaining arguments as object details.2526## When to Use2728- Creating new data files for infrastructure objects29- Populating devices, locations, organizations, or other schema nodes30- Setting up hierarchical data (location trees, tenant groups)31- Referencing related objects across files32- Managing component children (interfaces, modules)33- Organizing object files for correct load order3435## Rule Categories3637| Priority | Category | Prefix | Description |38| -------- | -------- | ------ | ----------- |39| CRITICAL | Branch-First Loading | `workflow-` | Load onto a branch, not the default branch |40| CRITICAL | File Format | `format-` | apiVersion, kind, spec structure |41| CRITICAL | Value Mapping | `value-` | Attributes, dropdowns, references |42| HIGH | Children | `children-` | Hierarchy/component nesting |43| MEDIUM | Range | `range-` | Sequential interface expansion |44| MEDIUM | Organization | `organization-` | Naming, load order, multi-doc |45| LOW | Patterns | `patterns-` | Flat lists, devices, git repos |4647## Schema Features This Skill Depends On4849Object files reference schema-defined shapes; missing50schema setup turns into "object failed to load" or51"reference not found" errors at sync time. Before52populating data, verify the schema upstream:5354| If the object... | The schema must... | See |55| ---------------- | ------------------ | --- |56| References another object across files | Define `human_friendly_id` on the target node (the shape determines scalar-vs-list reference) | [../infrahub-managing-schemas/rules/display-human-friendly-id.md](../infrahub-managing-schemas/rules/display-human-friendly-id.md) |57| Sits in a location/parent tree | Use a hierarchical generic with `parent`/`children` and full-kind peer references | [../infrahub-managing-schemas/rules/hierarchy-setup.md](../infrahub-managing-schemas/rules/hierarchy-setup.md) |58| Sets a Dropdown attribute value | Declare the dropdown `choices` as objects with `name` (not bare strings); the object references the choice `name` | [../infrahub-managing-schemas/rules/attribute-defaults-and-types.md](../infrahub-managing-schemas/rules/attribute-defaults-and-types.md) |59| Owns Component children inline | The parent's Component relationship and child's Parent relationship must share an identifier and the child needs `optional: false` | [../infrahub-managing-schemas/rules/relationship-component-parent.md](../infrahub-managing-schemas/rules/relationship-component-parent.md) |60| Will be the target of an artifact pipeline | The concrete node must `inherit_from: CoreArtifactTarget` (set on the node, not on a generic) | [../infrahub-managing-schemas/rules/extension-artifact-target.md](../infrahub-managing-schemas/rules/extension-artifact-target.md) |6162If any of these is missing, the schema needs an63update before the objects can load — that's a64schema migration, not an object fix.6566## Object File Basics6768```yaml69---70apiVersion: infrahub.app/v171kind: Object72spec:73 kind: <NodeKind> # Schema node kind (e.g., DcimDellServer)74 data:75 - <attribute>: <value> # List of object instances76```7778`apiVersion`, `kind: Object`, `spec.kind`, and `spec.data`79are always required. Each `spec` block targets a single80node kind.8182## Workflow8384Follow these steps when creating object data files:85861. **Plan to load onto a branch, not the default branch** —87 Decide the dedicated branch this data will load onto88 before writing the files, and surface it when you hand89 off the load commands. Loading into the default branch90 (the target when no `--branch` is given — `main` by91 convention, but it can be renamed) writes unreviewed92 data to the source of truth, and a bad bulk load there93 means deleting objects one by one instead of discarding94 a branch. Read95 [rules/workflow-branch-first.md](./rules/workflow-branch-first.md).96 The default branch is only reasonable on a local97 throwaway instance.982. **Read the schema** — Identify the target node kind,99 its attributes, relationships, and whether it has100 component children or hierarchy parents.1013. **Plan the file structure** — Read102 [rules/format-structure.md](./rules/format-structure.md)103 for the required YAML structure and104 [rules/organization-load-order.md](./rules/organization-load-order.md)105 for file naming and load order conventions.1064. **Map attribute values** — Set each attribute using107 the correct value format. Read108 [rules/value-attributes.md](./rules/value-attributes.md)109 for attribute mapping and110 [rules/value-relationships.md](./rules/value-relationships.md)111 for relationship references. To stamp lineage or lock112 a value, write it as a `value` + metadata mapping —113 see [../infrahub-common/metadata-lineage.md](../infrahub-common/metadata-lineage.md)114 (remember `source` is lineage only; locking needs115 `owner` + `is_protected`).1165. **Handle children** — If the node has component117 children or hierarchy nesting, read118 [rules/children-components.md](./rules/children-components.md)119 and [rules/children-hierarchy.md](./rules/children-hierarchy.md).1206. **Validate and load on the branch** — Check YAML syntax,121 ensure referenced objects exist or are defined in122 earlier load-order files, then validate and load against123 your branch (`--branch`). See124 [validation.md](./validation.md) for the commands and125 pre-load checklist.126127## Supporting References128129- **[reference.md](./reference.md)** -- Object file format130 specification131- **[validation.md](./validation.md)** --132 `infrahubctl object validate` / `object load`133 commands, common load errors, pre-load checklist134- **[examples.md](./examples.md)** -- 15 complete object135 patterns from production repos136- **[../infrahub-common/infrahub-yml-reference.md](../infrahub-common/infrahub-yml-reference.md)**137 -- .infrahub.yml project configuration138- **[../infrahub-common/metadata-lineage.md](../infrahub-common/metadata-lineage.md)**139 -- Value metadata (`source`, `owner`, `is_protected`):140 setting lineage/ownership and why `source` does not141 control edit access142- **[../infrahub-common/rules/](../infrahub-common/rules/)** -- Shared rules143 (git integration, caching) across all skills144- **[../infrahub-managing-schemas/SKILL.md](../infrahub-managing-schemas/SKILL.md)**145 -- Schema definitions these objects conform to146- **[rules/](./rules/)** -- Individual rules by category147 prefix