Claude Code Instructions — fabric-orchestrator

Project Context

Fabric-orchestrator manages Arista EVPN-VXLAN fabrics using Infrahub as the source of truth. Gitea: https://gitea.arnodo.fr/Damien/fabric-orchestrator Branch: feature/41-infrahub-schema

Reference Topology (overlaid.net)

2 spines (AS 65000), 8 leafs in 4 MLAG pairs (AS 65001–65004)
Loopback0: BGP router-id per device, Loopback1: shared VTEP IP per MLAG pair
VLANs 4090 (MLAG peer) / 4091 (MLAG iBGP) with trunk groups
Underlay: eBGP point-to-point (spine↔leaf) + iBGP (leaf↔leaf peer)
Overlay: EVPN eBGP multihop on loopbacks, spines as route-reflectors with next-hop-unchanged
L2VXLAN (EVPN Type-2): VLAN→VNI mapping, redistribute learned
L3VXLAN (EVPN Type-5): VRF→VNI mapping, redistribute connected
Border peering: BGP sessions inside VRF (leaf7/8 → AS 64999 in VRF gold)

Schema Files (Infrahub YAML format, in `schemas/`)

File	Content
`base.yml`	Device, Interfaces (Ethernet, Loopback, Vlan, Lag, Vxlan), IPAddress
`bgp.yml`	AutonomousSystem, BGPRouterConfig, BGPPeerGroup, BGPSession, BGPAddressFamily
`vlan_vxlan.yml`	VLAN, VNI, VTEP, VlanVniMapping, EVPNInstance
`vrf.yml`	VRFConfig, RouteTarget, VRFDeviceAssignment
`mlag.yml`	MlagDomain, MlagPeerConfig, MlagInterface
`extensions.yml`	UnderlayLink, HostConnection, FabricSettings

Infrahub Schema Rules

human_friendly_id fields MUST have unique: true — globally unique across all instances
To scope human_friendly_id per-device, traverse Parent relationships: parent_rel__parent_attr__value (e.g. device__name__value)
Parent relationships (kind: Parent) need optional: false explicitly
Self-referencing relationships need direction: outbound
Multiple relationships to the same peer type need distinct identifier values
Don't model the same concept twice (e.g. VTEP source_address vs InterfaceVxlan source_interface)
kind: Attribute for association, kind: Component for ownership (lifecycle-coupled)
kind: Parent implies the child cannot exist without the parent

Validation

infrahubctl schema check schemas/

Always run before committing. Fix any errors before pushing.

Commit Convention

fix(schema): short description — refs #<issue>
feat(schema): short description — refs #<issue>

One logical change per commit
Reference the Gitea issue number
Comment on the issue after implementation with changes summary

Open Issues (prioritized)

Check https://gitea.arnodo.fr/Damien/fabric-orchestrator/issues for current backlog. Critical issues (blocking data load) take priority over functional improvements. Dependency chain: resolve critical → significant → minor sequentially.

Workflow

Read the issue description fully before starting
Read relevant schema files to understand current state
Make minimal, targeted changes
Validate with infrahubctl schema check schemas/
Commit with proper message referencing the issue
Comment on the Gitea issue with what was changed

Don'ts

Don't add fields not needed by the reference topology
Don't change human_friendly_id without checking uniqueness implications
Don't remove existing relationships without checking reverse dependencies
Don't create new schema files without discussing first

3.6 KiB Raw Blame History Unescape Escape