Multi-layer XRD architecture

[mbakalarski]

1. Top-level XRD (user-facing)

• Minimal, vendor-agnostic API
• Exposes profiles, intents, selectors
• Users only care about intent, not vendor details.

Example:

apiVersion: netclab.dev/v1
kind: BGPIntent
spec:
  profile: low-latency
  deviceSelector:
    matchLabels:
      role: edge

2. Mid-level XRD (vendor-specific)

• One XRD per vendor or platform family
• Exposes more detailed fields for the composition to implement
• These are mid-level definitions - they define what is possible for each vendor
• Not meant for direct user consumption

Example:

apiVersion: eos.netclab.dev/v1
kind: BGPConfig
spec:
  peerIP: string
  addPathEnabled: bool
  gracefulRestartEnabled: bool

apiVersion: juniper.netclab.dev/v1
kind: BGPConfig
spec:
  peerIP: string
  gracefulRestartEnabled: bool
  localPreference: int

3. Compositions glue top -> mid

• Take user intent XR (top-level XRD)
• Expand it into vendor-specific XR (mid-level XRDs)
• Apply capability-aware logic
• Deploy via provider

Example:

resources:
  - name: router1-bgp
    base:
      apiVersion: cisco.network.io/v1
      kind: BGPConfig
    patches:
      - fromFieldPath: "spec.profile"
        toFieldPath: "spec.addPathEnabled"
        transform: low-latency → true if device supports AddPath

Advantages of this layering

1. Separation of concerns

• Top XRD: user intent, vendor-agnostic
• Mid XRD: vendor capabilities
• Composition: translation + logic

2. Reusability

• Same top-level XRD can target multiple vendors
• Mid-level XRDs can be reused in multiple compositions

3. Capability-awareness

• Top-level XRD stays clean
• Compositions and mid-level XRDs handle vendor differences and feature checks

4. Versioning & evolution

• Top-level XRD stable for users
• Mid-level XRDs can evolve with vendor features
• Composition logic adapts automatically

Pattern summary

User → Top-level XRD (intent)
      ↓
Composition (maps intent → vendor)
      ↓
Mid-level XRD per vendor (capability & config)
      ↓
Provider applies to actual devices

• Mid-level XRD = “internal building block”
• Top-level XRD = “user-facing API”

Think of it like:

• Top XRD = user asks “I want a low-latency BGP peer on edge routers”
• Mid XRD = defines exactly how Arista, Cisco, Juniper, etc. implement it
• Composition = figures out which mid-XRD to use for each device, applies capability-aware logic