Nexus-Guard-Suite/reference/namespace-vrf/comparison.md

Namespace + VRF vs Current Architecture

Executive Summary

This document compares the current NexusGuard architecture with the proposed Namespace + VRF architecture, highlighting the benefits, trade-offs, and implementation considerations.

Current Architecture

Overview

┌─────────────────────────────────────────────────────────┐
│  Server (172.20.8.191)                                  │
│                                                         │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Default Namespace (root)                        │   │
│  │    ├── eth0 (mgmt interface)                     │   │
│  │    ├── wg0 (10.172.21.1/24)                     │   │
│  │    │     ├── Device A: 10.172.21.2 (alice)      │   │
│  │    │     ├── Device B: 10.172.21.3 (bob)        │   │
│  │    │     └── Device C: 10.172.21.4 (charlie)    │   │
│  │    └── nftables (global rules)                   │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Data Model

User
  └── Device
        └── WgServer

Characteristics

Aspect	Current
Isolation	Routing only (nftables)
IP conflicts	Possible
API access	Global
Resource overhead	Low
Complexity	Low

Limitations

1. IP conflicts — Same IP on different WgServers causes routing issues
2. No user isolation — Users can see each other's traffic
3. API access control — Limited multi-user support
4. Scalability — Limited by kernel routing table size

Proposed Architecture: Namespace + VRF

Overview

┌─────────────────────────────────────────────────────────┐
│  Linux Kernel                                            │
│                                                         │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Default Namespace (root)                        │   │
│  │    ├── eth0 (mgmt interface)                     │   │
│  │    └── wg0 (server WireGuard)                    │   │
│  └──────────────────────────────────────────────────┘   │
│                                                         │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Namespace: ns_zerocode                          │   │
│  │    ├── veth0 (virtual ethernet)                  │   │
│  │    ├── VRF: vrf_main (table 100)                │   │
│  │    │     └── wg-z-main (10.100.0.1/24)          │   │
│  │    │           ├── Device A: 10.100.0.2         │   │
│  │    │           └── Device B: 10.100.0.3         │   │
│  │    └── nftables (isolated rules)                 │   │
│  └──────────────────────────────────────────────────┘   │
│                                                         │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Namespace: ns_alice                             │   │
│  │    ├── veth0 (virtual ethernet)                  │   │
│  │    ├── VRF: vrf_main (table 100)                │   │
│  │    │     └── wg-a-main (10.100.0.1/24) ← SAMA! │   │
│  │    │           ├── Device C: 10.100.0.2         │   │
│  │    │           └── Device D: 10.100.0.3         │   │
│  │    └── nftables (isolated rules)                 │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Data Model

User
  ├── Namespace (1:1)
  │     ├── NamespaceUser (N:N with role)
  │     └── VRF (1:N)
  │           └── WgServer (1:N)
  │                 └── Device (1:N)
  └── Device (legacy, for backward compatibility)

Characteristics

Aspect	Namespace + VRF
Isolation	Full network stack
IP conflicts	Impossible (per namespace)
API access	Per namespace
Resource overhead	Medium
Complexity	High

Benefits

1. Complete isolation — Full network stack isolation per namespace
2. No IP conflicts — Same IP can exist in different namespaces
3. Multi-user API — Role-based access per namespace
4. Scalability — Limited by number of namespaces, not routing table size
5. Security — Stronger isolation than nftables alone

Comparison Table

Feature	Current	Namespace + VRF	Winner
Isolation level	Routing only	Full network stack	Namespace + VRF
IP conflict prevention	Manual	Automatic	Namespace + VRF
API access control	Global	Per namespace	Namespace + VRF
Resource overhead	Low	Medium	Current
Implementation complexity	Low	High	Current
Scalability	Good	Good	Tie
Security	Medium	High	Namespace + VRF
Backward compatibility	N/A	Required	Current
Learning curve	Low	High	Current
Debugging difficulty	Low	High	Current

Use Case Analysis

Use Case 1: Multi-Tenant SD-WAN

Current:

• All tenants share same routing domain
• IP conflicts possible
• No tenant isolation

Namespace + VRF:

• Each tenant gets own namespace
• Complete isolation
• No IP conflicts

Winner: Namespace + VRF

Use Case 2: Development/Testing

Current:

• Dev and test share same network
• Conflicts possible
• No isolation

Namespace + VRF:

• Dev and test in separate namespaces
• Complete isolation
• Same IPs allowed

Winner: Namespace + VRF

Use Case 3: Single Tenant

Current:

• Simple setup
• Low overhead
• Easy debugging

Namespace + VRF:

• Overkill for single tenant
• Unnecessary complexity
• Higher resource usage

Winner: Current

Use Case 4: Compliance (PCI DSS, HIPAA)

Current:

• Shared network
• Audit challenges
• Compliance gaps

Namespace + VRF:

• Isolated networks
• Clean audit trail
• Compliance ready

Winner: Namespace + VRF

Resource Comparison

Memory Usage

Component	Current	Namespace + VRF
Per user	~10KB	~1MB
10 users	~100KB	~10MB
100 users	~1MB	~100MB
1000 users	~10MB	~1GB

CPU Usage

Operation	Current	Namespace + VRF
Packet routing	Low	Low
Namespace creation	N/A	Medium
VRF creation	Low	Low
nftables rules	Low	Low

Kernel Resources

Resource	Current	Namespace + VRF
Network namespaces	1	1 + N users
VRF devices	0	N per user
Routing tables	1	1 + N per user
nftables tables	1	1 + N users

Implementation Considerations

Phase 1: Database Schema

Changes:

• Add namespaces table
• Add namespace_users table
• Add vrfs table
• Add VRF fields to wg_servers

Effort: 1 week

Phase 2: Namespace Manager

Changes:

• Namespace CRUD operations
• User-role management
• API access control middleware

Effort: 1 week

Phase 3: VRF Manager

Changes:

• VRF CRUD operations
• Kernel VRF commands
• Routing table management

Effort: 1 week

Phase 4: WireGuard Integration

Changes:

• WG creation in namespace
• WG binding to VRF
• Peer management in namespace

Effort: 1 week

Phase 5: Firewall Integration

Changes:

• nftables per namespace
• Rules per VRF
• Cross-namespace isolation

Effort: 1 week

Phase 6: API Gateway

Changes:

• Namespace-scoped API routes
• Authentication per namespace
• Authorization per role

Effort: 1 week

Phase 7: Dashboard UI

Changes:

• Namespace management UI
• VRF configuration UI
• User-role management UI

Effort: 1 week

Phase 8: Testing & Documentation

Changes:

• Unit tests
• Integration tests
• Documentation
• Deployment guide

Effort: 1 week

Total Effort: 8 weeks

Migration Strategy

Backward Compatibility

1. Legacy mode — Keep current architecture as default
2. Opt-in — Users can opt-in to namespace + VRF
3. Migration tool — Script to migrate existing users to namespaces

Migration Steps

1. Create namespace for each existing user
2. Move devices to user's namespace
3. Create VRF in namespace
4. Move WireGuard interfaces to VRF
5. Update API routes
6. Test and validate

Rollback Plan

1. Keep legacy mode available
2. Migration tool can reverse changes
3. No data loss during migration

Decision Matrix

Choose Current Architecture If:

• Single tenant deployment
• Simple network requirements
• Limited resources
• Quick time-to-market
• Low complexity tolerance

Choose Namespace + VRF If:

• Multi-tenant deployment
• Strong isolation requirements
• Compliance needs (PCI DSS, HIPAA)
• Same IP across tenants
• Role-based API access

Recommendation

For Small Deployments (< 10 users)

Recommendation: Current architecture

Reasons:

• Simpler to implement and maintain
• Lower resource overhead
• Faster time-to-market
• Easier debugging

For Enterprise Deployments (> 10 users)

Recommendation: Namespace + VRF

Reasons:

• Stronger isolation
• Better security
• Compliance ready
• Scalable

For Multi-Tenant Deployments

Recommendation: Namespace + VRF (required)

Reasons:

• Complete tenant isolation
• No IP conflicts
• Role-based access control
• Audit trail

Conclusion

The Namespace + VRF architecture provides superior isolation and security at the cost of increased complexity and resource usage. It's the right choice for enterprise and multi-tenant deployments, but overkill for simple single-tenant setups.

Key takeaway: Choose the architecture that matches your deployment requirements. Don't over-engineer for simplicity, but don't under-engineer for security.

---

Status: Reference comparison — not yet implemented Last Updated: 2026-07-10 Author: NexusGuard Team