infrahub-managing-objects

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

创建 Infrahub 对象（数据）文件的专家指南。对象是 YAML 文件，用于用实际的基础设施数据填充 Schema 节点—— 设备、位置、组织、模块等。

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.

现有 Schema 文件： !

find . -name "*.yml" -path "*/schemas/*" -o -name "*schema*" -name "*.yml" 2>/dev/null | head -10

现有对象文件： !

find . -name "*.yml" -path "*/objects/*" 2>/dev/null | head -20

如果调用时带有参数（例如

/infrahub:managing-objects DcimDevice spine-01

），请将第一个参数用作 kind，其余参数用作对象详细信息。

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
Updating attribute values or relationship links in an existing data file
Debugging why an object fails to load or resolves the wrong reference

为基础设施对象创建新的数据文件
填充设备、位置、组织或其他 Schema 节点
设置层级数据（位置树、租户组）
跨文件引用相关对象
管理组件子项（接口、模块）
组织对象文件以确保正确的加载顺序
更新现有数据文件中的属性值或关系链接
排查对象无法加载或解析到错误引用的原因

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

优先级	类别	前缀	描述
关键	Branch 优先加载	`workflow-`	加载到 branch，而非默认 branch
关键	文件格式	`format-`	apiVersion、kind、spec 结构
关键	值映射	`value-`	属性、Dropdown、引用
高	子项	`children-`	层级/组件嵌套
中	范围	`range-`	按序扩展接口
中	组织	`organization-`	命名、加载顺序、多文档
低	模式	`patterns-`	扁平列表、设备、Git 仓库

Schema Features This Skill Depends On

本 Skill 依赖的 Schema 功能

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 the object...	The schema must...	See
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
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
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
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
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

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.

对象文件引用由 Schema 定义的 shape；如果缺少 Schema 设置，同步时就会出现“object failed to load”或“reference not found”错误。填充数据前，请先在上游验证 Schema：

如果对象……	Schema 必须……	参考
跨文件引用另一个对象	在目标节点上定义 `human_friendly_id` （shape 决定使用标量引用还是列表引用）	../infrahub-managing-schemas/rules/display-human-friendly-id.md
位于 location/parent 树中	使用带有 `parent` / `children` 的层级 generic，并使用完整 kind 的同级引用	../infrahub-managing-schemas/rules/hierarchy-setup.md
设置 Dropdown 属性值	将 Dropdown 的 `choices` 声明为带 `name` 的对象（而不是裸字符串）；对象引用选项的 `name`	../infrahub-managing-schemas/rules/attribute-defaults-and-types.md
内联拥有 Component 子项	父对象的 Component 关系与子对象的 Parent 关系必须共享同一标识符，且子对象需要 `optional: false`	../infrahub-managing-schemas/rules/relationship-component-parent.md
将作为 artifact 流水线的目标	具体节点必须设置 `inherit_from: CoreArtifactTarget` （设置在节点上，而不是 generic 上）	../infrahub-managing-schemas/rules/extension-artifact-target.md

如果缺少其中任何一项，则必须先更新 Schema，对象才能加载—— 这属于 Schema 迁移，而不是对象修复。

Object File Basics

对象文件基础

yaml

---
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.

yaml

---
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

和

spec.data

。每个

spec

块都针对单个节点 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. If the object should inherit shared defaults from a Profile or be created from an Object Template, read rules/value-profiles-templates.md. 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.

创建对象数据文件时，请按以下步骤操作：

计划加载到 branch，而非默认 branch—— 在编写文件前，先确定这些数据要加载到的专用 branch，并在交付加载命令时明确指出。加载到默认 branch （未指定
```
--branch
```
时的目标，按惯例为
```
main
```
，但可以重命名）会将未经审查的数据写入事实来源；如果在那里进行了错误的批量加载，就只能逐个删除对象，而不是丢弃整个 branch。请阅读 rules/workflow-branch-first.md。只有在本地一次性实例中，使用默认 branch 才是合理的。
读取 Schema——确定目标节点 kind、属性和关系，以及它是否包含组件子项或层级父项。
规划文件结构——阅读 rules/format-structure.md 以了解必需的 YAML 结构，并阅读 rules/organization-load-order.md 以了解文件命名和加载顺序约定。
映射属性值——使用正确的值格式设置每个属性。阅读 rules/value-attributes.md 以了解属性映射，并阅读 rules/value-relationships.md 以了解关系引用。如果对象应从 Profile 继承共享默认值，或应基于 Object Template 创建，请阅读 rules/value-profiles-templates.md。若要标记值的 lineage 或锁定该值，请将其写为
```
value
```
+ metadata 映射——参见 ../infrahub-common/metadata-lineage.md （请记住，
```
source
```
仅表示 lineage；锁定需要
```
owner
```
+
```
is_protected
```
）。
处理子项——如果节点包含组件子项或层级嵌套，请阅读 rules/children-components.md 和 rules/children-hierarchy.md。
验证并加载到 branch——检查 YAML 语法，确保被引用的对象已存在，或已在加载顺序更靠前的文件中定义，然后针对你的 branch 进行验证和加载（
```
--branch
```
）。有关命令和加载前检查清单，请参阅 validation.md。

Supporting References

辅助参考

reference.md -- Object file format specification
validation.md --
```
infrahubctl object validate
```
/
```
object load
```
commands, common load errors, pre-load checklist
examples.md -- 15 complete object patterns from production repos
../infrahub-common/infrahub-yml-reference.md -- .infrahub.yml project configuration
../infrahub-common/marketplace-reference.md -- if the schema these objects populate came from the marketplace, reuse it rather than modelling a new one
../infrahub-common/metadata-lineage.md -- Value metadata (
```
source
```
,
```
owner
```
,
```
is_protected
```
): setting lineage/ownership and why
```
source
```
does not control edit access
../infrahub-common/rules/ -- Shared rules (git integration, caching) across all skills
../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 these objects conform to
rules/ -- Individual rules by category prefix

reference.md——对象文件格式规范
validation.md——
```
infrahubctl object validate
```
/
```
object load
```
命令、常见加载错误和加载前检查清单
examples.md——生产仓库中的 15 个完整对象模式
../infrahub-common/infrahub-yml-reference.md ——.infrahub.yml 项目配置
../infrahub-common/marketplace-reference.md ——如果这些对象要填充的 Schema 来自 Marketplace，请复用该 Schema，而不是重新建模
../infrahub-common/metadata-lineage.md ——值元数据（
```
source
```
、
```
owner
```
、
```
is_protected
```
）：设置 lineage/所有权，以及为何
```
source
```
不控制编辑权限
../infrahub-common/rules/——所有 Skill 共用的规则（Git 集成、缓存）
../infrahub-common/rules/workflow-information-priority.md ——优先遵循 Skill 内容；在确有信息缺口时，如何查阅 docs.infrahub.app（例如删除节点）
../infrahub-managing-schemas/SKILL.md ——这些对象所遵循的 Schema 定义
rules/——按类别前缀划分的各项规则