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

Namespace + VRF Architecture

Enterprise Network Isolation for NexusGuard SD-WAN

Overview

This document describes the Namespace + VRF architecture for enterprise-grade network isolation. This is a reference architecture for future development — not currently implemented.

Problem Statement

Current architecture has limitations:

1. Single routing domain — All users share same kernel routing table
2. IP conflicts — Same IP on different WgServers causes routing issues
3. No user isolation — Users can see each other's traffic
4. API access control — Limited multi-user support per namespace

Solution: Network Namespace + VRF

Layer 1: Network Namespace (Kernel Isolation)

Network namespace provides complete network stack isolation:

┌─────────────────────────────────────────────────────────┐
│  Linux Kernel                                            │
│                                                         │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Default Namespace (root)                        │   │
│  │    ├── eth0 (mgmt interface)                     │   │
│  │    ├── wg0 (server WireGuard)                    │   │
│  │    └── nftables (global rules)                   │   │
│  └──────────────────────────────────────────────────┘   │
│                                                         │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Namespace: ns_zerocode                          │   │
│  │    ├── lo (loopback)                             │   │
│  │    ├── veth0 (virtual ethernet)                  │   │
│  │    ├── WireGuard interfaces                      │   │
│  │    └── nftables (isolated rules)                 │   │
│  └──────────────────────────────────────────────────┘   │
│                                                         │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Namespace: ns_alice                             │   │
│  │    ├── lo (loopback)                             │   │
│  │    ├── veth0 (virtual ethernet)                  │   │
│  │    ├── WireGuard interfaces                      │   │
│  │    └── nftables (isolated rules)                 │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

What's isolated per namespace:

• Network interfaces
• Routing tables
• iptables/nftables rules
• /proc/net entries
• Socket bindings

Layer 2: VRF (Routing Isolation within Namespace)

VRF provides routing table isolation within a namespace:

┌─────────────────────────────────────────────────────────┐
│  Namespace: ns_zerocode                                  │
│                                                         │
│  ┌──────────────────────────────────────────────────┐   │
│  │  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               │   │
│  │    └── Routing table 100                         │   │
│  └──────────────────────────────────────────────────┘   │
│                                                         │
│  ┌──────────────────────────────────────────────────┐   │
│  │  VRF: vrf_isolated (table 200)                  │   │
│  │    ├── wg-z-iso (10.200.0.1/24)                 │   │
│  │    │     └── Device C: 10.200.0.2               │   │
│  │    └── Routing table 200                         │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

What's isolated per VRF:

• Routing tables
• Gateway routes
• Policy routing

Layer 3: API Access Control (Multi-User)

Multi-control user access per namespace:

┌─────────────────────────────────────────────────────────┐
│  Namespace: ns_zerocode                                  │
│                                                         │
│  Users:                                                  │
│    ├── zerocode (admin)     → Full API access           │
│    ├── bob (operator)       → Limited API access        │
│    └── charlie (viewer)     → Read-only API access      │
│                                                         │
│  API Endpoints:                                          │
│    ├── POST   /api/v1/ns/zerocode/devices      [admin]  │
│    ├── GET    /api/v1/ns/zerocode/devices      [all]    │
│    ├── PUT    /api/v1/ns/zerocode/devices/:id  [admin]  │
│    ├── DELETE /api/v1/ns/zerocode/devices/:id  [admin]  │
│    └── GET    /api/v1/ns/zerocode/status       [all]    │
└─────────────────────────────────────────────────────────┘

Data Model

Current Model

User
  └── Device
        └── WgServer

Proposed Model

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

Database Schema

-- Namespace (1 per user, or shared)
CREATE TABLE namespaces (
    id UUID PRIMARY KEY,
    name VARCHAR(64) UNIQUE NOT NULL,  -- e.g., "zerocode"
    owner_id UUID REFERENCES users(id),
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);

-- Namespace users (multi-control)
CREATE TABLE namespace_users (
    id UUID PRIMARY KEY,
    namespace_id UUID REFERENCES namespaces(id),
    user_id UUID REFERENCES users(id),
    role VARCHAR(16) NOT NULL,  -- admin, operator, viewer
    created_at TIMESTAMP,
    UNIQUE(namespace_id, user_id)
);

-- VRF (per namespace)
CREATE TABLE vrfs (
    id UUID PRIMARY KEY,
    namespace_id UUID REFERENCES namespaces(id),
    name VARCHAR(64) NOT NULL,  -- e.g., "main", "isolated"
    table_id INTEGER NOT NULL,  -- routing table ID
    created_at TIMESTAMP,
    UNIQUE(namespace_id, name)
);

-- WgServer (per VRF)
ALTER TABLE wg_servers ADD COLUMN vrf_id UUID REFERENCES vrfs(id);
ALTER TABLE wg_servers ADD COLUMN namespace_id UUID REFERENCES namespaces(id);

API Design

Namespace API

POST   /api/v1/namespaces              # Create namespace
GET    /api/v1/namespaces              # List namespaces (admin only)
GET    /api/v1/namespaces/:name        # Get namespace details
DELETE /api/v1/namespaces/:name        # Delete namespace

POST   /api/v1/namespaces/:name/users  # Add user to namespace
DELETE /api/v1/namespaces/:name/users/:id  # Remove user
PUT    /api/v1/namespaces/:name/users/:id  # Update user role

VRF API

POST   /api/v1/ns/:namespace/vrfs              # Create VRF
GET    /api/v1/ns/:namespace/vrfs              # List VRFs
GET    /api/v1/ns/:namespace/vrfs/:name        # Get VRF details
DELETE /api/v1/ns/:namespace/vrfs/:name        # Delete VRF

Server API (Namespace-scoped)

POST   /api/v1/ns/:namespace/servers           # Create server in VRF
GET    /api/v1/ns/:namespace/servers           # List servers
GET    /api/v1/ns/:namespace/servers/:id       # Get server details
DELETE /api/v1/ns/:namespace/servers/:id       # Delete server

Device API (Namespace-scoped)

POST   /api/v1/ns/:namespace/devices           # Create device
GET    /api/v1/ns/:namespace/devices           # List devices
GET    /api/v1/ns/:namespace/devices/:id       # Get device details
DELETE /api/v1/ns/:namespace/devices/:id       # Delete device

Kernel Commands

Create Namespace

# Create namespace
ip netns add ns_zerocode

# Create veth pair (connect to default namespace)
ip link add veth0 type veth peer name veth1
ip link set veth1 netns ns_zerocode

# Configure veth in default namespace
ip addr add 10.0.0.1/24 dev veth0
ip link set veth0 up

# Configure veth in namespace
ip netns exec ns_zerocode ip addr add 10.0.0.2/24 dev veth1
ip netns exec ns_zerocode ip link set veth1 up
ip netns exec ns_zerocode ip route add default via 10.0.0.1

Create VRF in Namespace

# Create VRF
ip netns exec ns_zerocode ip link add vrf:main type vrf table 100
ip netns exec ns_zerocode ip link set vrf:main up

# Create WireGuard interface
ip netns exec ns_zerocode ip link add wg-z-main type wireguard

# Bind WG to VRF
ip netns exec ns_zerocode ip link set wg-z-main vrf vrf:main

# Configure WG
ip netns exec ns_zerocode ip addr add 10.100.0.1/24 dev wg-z-main
ip netns exec ns_zerocode wg set wg-z-main listen-port 51820 private-key /path/to/key

# Add routes to VRF table
ip netns exec ns_zerocode ip route add 10.100.0.0/24 dev wg-z-main table 100

Configure nftables in Namespace

# Create table in namespace
ip netns exec ns_zerocode nft add table ip nexusguard

# Create chains
ip netns exec ns_zerocode nft add chain ip nexusguard forward '{type filter hook forward priority filter; policy accept;}'
ip netns exec ns_zerocode nft add chain ip nexusguard input '{type filter hook input priority filter; policy accept;}'

# Add rules
ip netns exec ns_zerocode nft add rule ip nexusguard forward iifname wg-z-main accept

Use Cases

Use Case 1: Multi-Tenant SD-WAN

Company A (zerocode)
  └── Namespace: ns_zerocode
        ├── VRF: production → wg-prod (10.10.0.0/24)
        └── VRF: staging → wg-staging (10.20.0.0/24)

Company B (alice)
  └── Namespace: ns_alice
        └── VRF: main → wg-main (10.10.0.0/24) ← Same IP, isolated!

Use Case 2: Development/Testing Isolation

Developer: bob
  └── Namespace: ns_bob_dev
        └── VRF: dev → wg-dev (10.100.0.0/24)

QA Team
  └── Namespace: ns_qa
        └── VRF: test → wg-test (10.100.0.0/24) ← Same IP, isolated!

Use Case 3: Compliance Isolation

PCI DSS Workload
  └── Namespace: ns_pci
        └── VRF: pci → wg-pci (10.50.0.0/24)

HIPAA Workload
  └── Namespace: ns_hipaa
        └── VRF: hipaa → wg-hipaa (10.60.0.0/24)

Implementation Phases

Phase 1: Database Schema (Week 1)

• Create namespaces table
• Create namespace_users table
• Create vrfs table
• Add VRF fields to wg_servers
• Migration scripts

Phase 2: Namespace Manager (Week 2)

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

Phase 3: VRF Manager (Week 3)

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

Phase 4: WireGuard Integration (Week 4)

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

Phase 5: Firewall Integration (Week 5)

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

Phase 6: API Gateway (Week 6)

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

Phase 7: Dashboard UI (Week 7)

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

Phase 8: Testing & Documentation (Week 8)

• Unit tests
• Integration tests
• Documentation
• Deployment guide

Resource Overhead

Resource	Per Namespace	Per VRF	Total (10 users, 2 VRFs each)
Network namespaces	1	0	10
VRF devices	0	1	20
Routing tables	1	1	30
nftables tables	1	0	10
Memory overhead	~1MB	~10KB	~12MB

Security Considerations

1. Namespace isolation — Complete network stack isolation
2. VRF isolation — Routing table isolation within namespace
3. API access control — Role-based access per namespace
4. Audit logging — Track all namespace/VRF operations
5. Resource limits — Prevent namespace exhaustion

Comparison with Current Architecture

Aspect	Current	Namespace + VRF
Isolation level	Routing only	Full network stack
IP conflicts	Possible	Impossible (per namespace)
API access	Global	Per namespace
Resource overhead	Low	Medium
Complexity	Low	High
Scalability	Good	Good (with limits)

References

• Linux Network Namespaces: man ip-netns
• Linux VRF: man ip-link (vrf type)
• WireGuard: man wg
• nftables: man nft

---

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