83 lines
3.6 KiB
Markdown
83 lines
3.6 KiB
Markdown
# 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
|
||
|
||
1. `human_friendly_id` fields MUST have `unique: true` — globally unique across all instances
|
||
2. To scope human_friendly_id per-device, traverse Parent relationships:
|
||
`parent_rel__parent_attr__value` (e.g. `device__name__value`)
|
||
3. Parent relationships (`kind: Parent`) need `optional: false` explicitly
|
||
4. Self-referencing relationships need `direction: outbound`
|
||
5. Multiple relationships to the same peer type need distinct `identifier` values
|
||
6. Don't model the same concept twice (e.g. VTEP source_address vs InterfaceVxlan source_interface)
|
||
7. `kind: Attribute` for association, `kind: Component` for ownership (lifecycle-coupled)
|
||
8. `kind: Parent` implies the child cannot exist without the parent
|
||
|
||
## Validation
|
||
|
||
```bash
|
||
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
|
||
|
||
1. Read the issue description fully before starting
|
||
2. Read relevant schema files to understand current state
|
||
3. Make minimal, targeted changes
|
||
4. Validate with `infrahubctl schema check schemas/`
|
||
5. Commit with proper message referencing the issue
|
||
6. 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
|