photoncloud-monorepo/docs/por/T062-nix-nos-generic/task.yaml

id: T062
name: Nix-NOS Generic Network Module
goal: Create standalone Nix-NOS repository as generic network layer (VyOS/OpenWrt alternative)
status: complete
completed: 2025-12-13 01:38 JST
priority: P0
owner: peerA
created: 2025-12-13
depends_on: []
blocks: [T061.S4]

context: |
  **User Decision (2025-12-13 00:46 JST):**
  Separate Nix-NOS as generic network module in its own repository.

  **Three-Layer Architecture:**
  - Layer 1: Nix-NOS (generic) - BGP, VLAN, systemd-networkd, routing
  - Layer 2: PlasmaCloud Network - FiberLB BGP, PrismNET integration
  - Layer 3: PlasmaCloud Cluster - cluster-config, Deployer, service orchestration

  **Key Principle:**
  Nix-NOS should NOT know about PlasmaCloud, FiberLB, ChainFire, etc.
  It's a generic network configuration system usable by anyone.

  **Repository:** github.com/centra/nix-nos (new, separate from plasmacloud)

acceptance:
  - Standalone flake.nix that works independently
  - BGP module with BIRD2 and GoBGP backends
  - Network interface abstraction via systemd-networkd
  - VLAN support
  - Example configurations for non-PlasmaCloud use cases
  - PlasmaCloud can import as flake input

steps:
  - step: S1
    name: Repository Skeleton
    done: Create nix-nos repo with flake.nix and module structure
    status: complete
    owner: peerB
    priority: P0
    notes: |
      Create structure:
      ```
      nix-nos/
      ├── flake.nix
      ├── modules/
      │   ├── network/
      │   ├── bgp/
      │   ├── routing/
      │   └── topology/
      └── lib/
          └── generators.nix
      ```

      flake.nix exports nixosModules.default
    outputs:
      - path: nix-nos/flake.nix
        note: Flake definition with nixosModules.default export (62L)
      - path: nix-nos/modules/default.nix
        note: Root module importing all submodules (30L)
      - path: nix-nos/modules/network/interfaces.nix
        note: Network interface configuration (98L)
      - path: nix-nos/modules/bgp/default.nix
        note: BGP abstraction with backend selection (107L)
      - path: nix-nos/modules/bgp/bird.nix
        note: BIRD2 backend implementation (61L)
      - path: nix-nos/modules/bgp/gobgp.nix
        note: GoBGP backend implementation (88L)
      - path: nix-nos/modules/routing/static.nix
        note: Static route configuration (67L)
      - path: nix-nos/lib/generators.nix
        note: Configuration generation utilities (95L)

  - step: S2
    name: BGP Module
    done: Generic BGP abstraction with BIRD2 and GoBGP backends
    status: complete
    started: 2025-12-13 00:51 JST
    completed: 2025-12-13 00:53 JST
    owner: peerB
    priority: P0
    notes: |
      - nix-nos.bgp.enable
      - nix-nos.bgp.asn
      - nix-nos.bgp.routerId
      - nix-nos.bgp.peers
      - nix-nos.bgp.backend = "bird" | "gobgp"
      - nix-nos.bgp.announcements

      Backend-agnostic: generates BIRD2 or GoBGP config
    outputs:
      - path: nix-nos/modules/bgp/
        note: "Delivered in S1 (256L total - default.nix 107L + bird.nix 61L + gobgp.nix 88L)"

  - step: S3
    name: Network Interface Abstraction
    done: systemd-networkd based interface configuration
    status: complete
    completed: 2025-12-13 01:30 JST
    owner: peerB
    priority: P1
    notes: |
      Enhanced nix-nos/modules/network/interfaces.nix:
      - nix-nos.interfaces.<name>.addresses (CIDR notation)
      - nix-nos.interfaces.<name>.gateway
      - nix-nos.interfaces.<name>.dns
      - nix-nos.interfaces.<name>.dhcp (boolean)
      - nix-nos.interfaces.<name>.mtu
      - Maps to systemd.network.networks
      - Assertions for validation (dhcp OR addresses required)
      - Backward compatible with existing nix-nos.network.interfaces
    outputs:
      - path: nix-nos/modules/network/interfaces.nix
        note: Enhanced with systemd-networkd support (193L total, +88L added)
      - path: .cccc/work/test-nix-nos-interfaces.nix
        note: Test configuration with static, DHCP, and IPv6 examples

  - step: S4
    name: VLAN Support
    done: VLAN configuration module
    status: complete
    completed: 2025-12-13 01:36 JST
    owner: peerB
    priority: P2
    notes: |
      Created nix-nos/modules/network/vlans.nix:
      - nix-nos.vlans.<name>.id (1-4094 validation)
      - nix-nos.vlans.<name>.interface (parent interface)
      - nix-nos.vlans.<name>.addresses (CIDR notation)
      - nix-nos.vlans.<name>.gateway
      - nix-nos.vlans.<name>.dns
      - nix-nos.vlans.<name>.mtu
      - Maps to systemd.network.netdevs (VLAN netdev creation)
      - Maps to systemd.network.networks (VLAN network config + parent attachment)
      - Assertions for VLAN ID range and address requirement
      - Useful for storage/management network separation
    outputs:
      - path: nix-nos/modules/network/vlans.nix
        note: Complete VLAN module with systemd-networkd support (137L)
      - path: nix-nos/modules/default.nix
        note: Updated to import vlans.nix (+1L)
      - path: .cccc/work/test-nix-nos-vlans.nix
        note: Test configuration with storage/mgmt/backup VLANs

  - step: S5
    name: Documentation & Examples
    done: README, examples for standalone use
    status: complete
    completed: 2025-12-13 01:38 JST
    owner: peerB
    priority: P2
    notes: |
      Created comprehensive documentation:
      - README.md with module documentation, quick start, examples
      - examples/home-router.nix - Simple WAN/LAN with NAT
      - examples/datacenter-node.nix - BGP + VLANs for data center
      - examples/edge-router.nix - Multi-VLAN with static routing
      - No PlasmaCloud references - fully generic and reusable
    outputs:
      - path: nix-nos/README.md
        note: Complete documentation with module reference and quick start (165L)
      - path: nix-nos/examples/home-router.nix
        note: Home router example with WAN/LAN and NAT (41L)
      - path: nix-nos/examples/datacenter-node.nix
        note: Data center example with BGP and VLANs (55L)
      - path: nix-nos/examples/edge-router.nix
        note: Edge router with multiple VLANs and static routes (52L)

evidence:
  - item: T062.S1 Nix-NOS Repository Skeleton
    desc: Complete flake.nix structure with modules (network, BGP, routing) and lib utilities
    total_loc: 516
    validation: nix flake check nix-nos/ passes
  - item: T062.S3 Network Interface Abstraction
    desc: systemd-networkd based interface configuration with nix-nos.interfaces option
    total_loc: 88
    validation: nix-instantiate returns <LAMBDA>, test config evaluates without errors
  - item: T062.S4 VLAN Support
    desc: VLAN configuration module with systemd.network.netdevs and parent interface attachment
    total_loc: 137
    validation: nix-instantiate returns <LAMBDA>, netdev Kind="vlan", VLAN ID=100 correct
  - item: T062.S5 Documentation & Examples
    desc: Complete README with module documentation and 3 example configurations
    total_loc: 313
    validation: README.md exists, examples/ has 3 configs (home-router, datacenter-node, edge-router)

notes: |
  This is Layer 1 of the three-layer architecture.
  PlasmaCloud (T061) builds on top of this.
  Reusable by other projects (VyOS/OpenWrt alternative vision).