# microsoft/sdn architecture

> Architecture diagram of the GitHub repository microsoft/sdn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/sdn
- Repository: https://github.com/microsoft/sdn

## Overview

##### Project Type and Purpose
- This is an open-source deployment and automation toolkit for Microsoft’s Software Defined Networking (SDN) stack on Windows Server and Azure Stack HCI.
- It consists of PowerShell scripts and modules (SDNExpress, VMMExpress), SCVMM service templates, diagnostic scripts, Kubernetes CNI plugins (flannel, wincni, containerd), REST examples, switch configurations, and sample RDMA/C CI code.
- Its goal is to automate the provisioning of the SDN fabric (Network Controller, Software Load Balancer, RRAS gateways) and integrate container and Kubernetes networking into that fabric.

##### File Structure
- Top-level directories indicate major functional areas:
· SDNExpress (interactive deployment CLI + PowerShell module)
· VMM (SCVMM-based deployment via scripts and Service Templates)
· Kubernetes (flannel overlays, Windows CNI plugin, containerd integration)
· Containers, Diagnostics, NCRESTExamples (post-deployment validation & REST usage)
· SwitchConfigExamples (physical switch setup)
· NDKCI (native RDMA sample code)
- Configuration files (.psd1, .toml, .json, .xml) and scripts (.ps1, .sh) drive the automation.
- REST API is surfaced by the Network Controller (JSON schemas).

##### Main Components
a. Deployment Clients
- SDNExpress.ps1 + SDNExpressModule.psm1 (interactive CLI & reusable module)
- VMMExpress scripts + SCVMM Service Template XMLs
- Optional SCVMM Console GUI
- Kubernetes tooling (flannel l2bridge/overlay, wincni plugin, containerd configs)
b. Control Plane
- Network Controller VMs (RESTful API endpoints)
- SCVMM (when used)
c. Data Plane Infrastructure
- Hyper-V hosts running:
- Network Controller VMs
- SLB Mux VMs
- RRAS Gateway VMs
- Hyper-V Host Agents (SLB host agent)
d. Physical Network
- Trunked VLANs, DCB settings, BGP peerings
- Physical switches (Cisco/Dell examples)
e. Tenant Workloads
- VMs on overlay networks
- Kubernetes pods/containers attached via CNI + flannel/wincni

##### Relationships and Interactions
- Deployment client (SDNExpress/VMMExpress) reads user configuration → invokes Network Controller REST API or SCVMM PowerShell cmdlets → deploys resource-definition VMs (Controller, SLB, Gateway).
- Network Controller exposes JSON/REST endpoints → manipulated by PowerShell modules or curl/Invoke-WebRequest.
- SLB Mux agents on each host receive instructions from Controller → program load-balancing tables.
- RRAS Gateway VMs get configuration for tunnels/routes via Controller.
- Kubernetes CNI components contact Controller to provision overlay or l2bridge networks for pods.
- Diagnostics scripts query host and Controller state for troubleshooting.

##### Architectural Patterns and Design Principles
- Modular CLI + module pattern (SDNExpress + SDNExpressModule.psm1)
- Infrastructure-as-code: declarative config files drive VM/template provisioning
- RESTful control plane (Network Controller API) with idempotent JSON operations
- Plugin pattern for container networking (CNI spec: flannel, wincni, containerd)
- Separation of control plane (Controller) and data plane (Hyper-V hosts, Mux, Gateway)

##### Key Technologies and Frameworks
- PowerShell 5.x/7.x scripting, PowerShell modules (.psm1)
- SCVMM Service Templates & PowerShell cmdlets
- JSON/REST API (Network Controller)
- Kubernetes CNI plugins (Go code), flannel (overlay, l2bridge)
- containerd config for Windows containers
- BGP, VLAN, DCB, GRE, IPSec via RRAS Gateway

##### Final Recommendations
- Error-handling or rollback patterns (VMMExpress rollbacks).
- If space allows, show sample tenant workflows (create overlay, attach VM, define ACL).
- Share drafts for peer review—accuracy in depicting these dynamic interactions is critical.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Deployment Clients
    subgraph "Deployment Clients"
        SDNExpress["SDNExpress Deployment Client"]:::deploy
        SDNExplorer["SDNExplorer Tool"]:::deploy
        SDNSec["SDNSecurityToolkit Module"]:::deploy
        VMMExpress["VMMExpress Deployment Client"]:::deploy
        SCVMMConsole["SCVMM Console GUI"]:::deploy
        Templates["SCVMM Service Templates"]:::deploy
        subgraph "Kubernetes Tooling"
            FlannelL2["Flannel L2 Bridge"]:::deploy
            FlannelO["Flannel Overlay"]:::deploy
            WinCNI["Windows CNI Plugin"]:::deploy
            ContainerdCNI["containerd Integration"]:::deploy
        end
        Containers["Containers Integration Scripts"]:::deploy
        Diagnostics["Diagnostics & Validation Scripts"]:::deploy
        RESTExamples["Network Controller REST Examples"]:::deploy
        SwitchConfig["Switch Configuration Examples"]:::deploy
        NDKCI["NDKCI RDMA Sample"]:::deploy
    end

    %% Control Plane
    subgraph "Control Plane"
        NC["Network Controller"]:::control
        SCVMM["SCVMM"]:::control
    end

    %% Data Plane Infrastructure
    subgraph "Data Plane"
        subgraph "Hyper-V Hosts"
            HostAgents["SLB Host Agent"]:::data
            SLBMux["SLB Mux VMs"]:::data
            GatewayVM["RRAS Gateway VMs"]:::data
        end
    end

    %% Physical Network
    Physical["Physical Network"]:::physical

    %% Tenant Workloads
    Workloads["Tenant Workloads"]:::work

    %% Connections
    SDNExpress -->|"REST/JSON & PS"| NC
    VMMExpress -->|"PowerShell"| SCVMM
    SCVMMConsole -->|"GUI Actions"| SCVMM
    VMMExpress -->|"uses Templates"| Templates
    Templates -->|"deploy via SCVMM"| SCVMM
    SCVMM -->|"provisions"| NC
    SCVMM -->|"provisions"| SLBMux
    SCVMM -->|"provisions"| GatewayVM

    FlannelL2 -->|"CNI calls"| NC
    FlannelO -->|"CNI calls"| NC
    WinCNI -->|"CNI calls"| NC
    ContainerdCNI -->|"CNI calls"| NC

    Containers -->|"integration scripts"| NC
    Diagnostics -->|"queries via PS/REST"| NC
    Diagnostics -->|"queries via PS"| HostAgents
    RESTExamples -->|"sample calls"| NC
    SwitchConfig -->|"configures"| Physical
    NDKCI -->|"RDMA code"| Physical

    NC -->|"config updates"| HostAgents
    NC -->|"tunnel/routes config"| GatewayVM
    NC -->|"load-balancer tables"| SLBMux

    Workloads -->|"overlay networking"| SLBMux
    Workloads -->|"gateway access"| GatewayVM

    %% Click Events
    click SDNExpress "https://github.com/microsoft/sdn/tree/master/SDNExpress/scripts"
    click SDNExplorer "https://github.com/microsoft/sdn/tree/master/SDNExpress/Tools/SDNExplorer"
    click SDNSec "https://github.com/microsoft/sdn/blob/master/SDNExpress/Tools/SDNSecurityToolkit/SDNSecurityToolkit.psm1"
    click VMMExpress "https://github.com/microsoft/sdn/blob/master/VMM/VMM SDN Express/VMMExpress.ps1"
    click Templates "https://github.com/microsoft/sdn/tree/master/VMM/Templates"
    click FlannelL2 "https://github.com/microsoft/sdn/tree/master/Kubernetes/flannel/l2bridge"
    click FlannelO "https://github.com/microsoft/sdn/tree/master/Kubernetes/flannel/overlay"
    click WinCNI "https://github.com/microsoft/sdn/tree/master/Kubernetes/wincni"
    click ContainerdCNI "https://github.com/microsoft/sdn/tree/master/Kubernetes/containerd"
    click Containers "https://github.com/microsoft/sdn/tree/master/Containers"
    click Diagnostics "https://github.com/microsoft/sdn/tree/master/Diagnostics"
    click RESTExamples "https://github.com/microsoft/sdn/tree/master/NCRESTExamples"
    click SwitchConfig "https://github.com/microsoft/sdn/tree/master/SwitchConfigExamples"
    click NDKCI "https://github.com/microsoft/sdn/tree/master/NDKCI/RdmaSample"

    %% Styles
    classDef deploy fill:#CFE2F3,stroke:#0b5394
    classDef control fill:#D9EAD3,stroke:#38761D
    classDef data fill:#FCE5CD,stroke:#E69138
    classDef physical fill:#D9D9D9,stroke:#7f7f7f
    classDef work fill:#DAE8FC,stroke:#6C8EBF
```
