Update CLAUDE.md
This commit is contained in:
Damien
99
CLAUDE.md
99
CLAUDE.md
@@ -1,35 +1,82 @@
|
||||
# Claude Code Instructions — Schema Refinement
|
||||
# Claude Code Instructions — fabric-orchestrator
|
||||
|
||||
## Project Context
|
||||
This is a fabric-orchestrator project managing Arista EVPN-VXLAN fabrics.
|
||||
Branch: `feature/41-infrahub-schema`
|
||||
Schema files are in `schemas/` directory (Infrahub YAML format).
|
||||
|
||||
## Reference Topology (from overlaid.net)
|
||||
- 2 spines (AS 65000), 8 leafs in 4 MLAG pairs (AS 65001-65004)
|
||||
- Loopback0: BGP router-id, Loopback1: shared VTEP IP per MLAG pair
|
||||
- VLANs 4090/4091: MLAG peering with trunk groups
|
||||
- EVPN overlay via eBGP multihop on loopbacks
|
||||
- L2VXLAN (Type-2) and L3VXLAN (Type-5) with VRFs
|
||||
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` attributes MUST have `unique: true`
|
||||
2. If human_friendly_id needs to be scoped per-device, traverse Parent
|
||||
relationships: `parent_rel__parent_attr__value`
|
||||
3. Parent relationships need `optional: false` explicitly
|
||||
|
||||
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 same peer type need unique `identifier`
|
||||
6. Validate with: `infrahubctl schema check schemas/`
|
||||
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
|
||||
- Reference issue: `fix(schema): description — refs #41`
|
||||
- One logical change per commit
|
||||
- Run schema validation before committing
|
||||
|
||||
## Files
|
||||
- `schemas/base.yml` — Device, Interfaces, IPAddress
|
||||
- `schemas/bgp.yml` — AS, BGPRouterConfig, PeerGroup, Session, AF
|
||||
- `schemas/vlan_vxlan.yml` — VLAN, VNI, VTEP, VlanVniMapping, EVPN
|
||||
- `schemas/vrf.yml` — VRF, RouteTarget, VRFDeviceAssignment
|
||||
- `schemas/mlag.yml` — MlagDomain, MlagPeerConfig, MlagInterface
|
||||
- `schemas/extensions.yml` — UnderlayLink, HostConnection, FabricSettings
|
||||
```
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user