Connect container endpoints to a tenant virtual network

Applies To: Windows Server 2016

This topic shows you how to connect container endpoints to an existing tenant virtual network created through the Microsoft Software Defined Networking (SDN) stack. We will use the l2bridge (and optionally l2tunnel) network driver available with the Windows libnetwork plugin for Docker to create a container network on the container host (tenant) virtual machine.

As documented in the Container Networking topic on MSDN, multiple network drivers are available through Docker on Windows. The drivers most suitable for SDN are l2bridge and l2tunnel. For both drivers, each container endpoint is in the same virtual subnet as the container host (tenant) virtual machine. The IP addresses for container endpoints are assigned dynamically by the Host Networking Service (HNS) through the private cloud plugin. The container endpoints have unique IP addresses but share the same MAC address of the container host (tenant) virtual machine due to Layer-2 address translation. Network policy (for example: ACLs, encapsulation, and QoS) for these container endpoints are enforced in the physical Hyper-V host as received by the Network Controller and defined in upper-layer management systems. There is a slight difference between the l2bridge and l2tunnel drivers which is explained below.

  • L2 Bridge - container endpoints that reside on the same container host virtual machine and are in the same subnet have all network traffic bridged within the Hyper-V virtual switch. Container endpoints which reside on different container host VMs or which are in different subnets have their traffic forwarded to the physical Hyper-V host. Since network traffic between containers on the same host and in the same subnet do not flow to the physical host, no network policy is enforced. Policy is only applied for cross-host or cross-subnet container network traffic.

  • L2 Tunnel - all network traffic between two container endpoints is forwarded to the physical Hyper-V host regardless of host or subnet. Network policy is enforced for both cross-subnet and cross-host network traffic.


These networking modes do not work for connecting windows container endpoints to a tenant virtual network in Azure public cloud


  • An SDN infrastructure with the Network Controller has been deployed
  • A tenant virtual network has been created
  • A tenant virtual machine has been deployed with the Windows Container feature enabled, Docker installed, and Hyper-V feature enabled

Nested virtualization and exposing virtualization extensions is not required unless using Hyper-V Containers The HyperV feature is required to install several binaries for l2bridge and l2tunnel networks

# To install HyperV feature without checks for nested virtualization
dism /Online /Enable-Feature /FeatureName:Microsoft-Hyper-V /All 


  1. Add multiple IP configurations to an existing VM NIC resource through Network Controller (Hyper-V Host)
  2. Enable the network proxy on the host to allocate CA IP Addresses for container endpoints (Hyper-V Host)
  3. Install the private cloud plug-in to assign CA IP addresses to container endpoints (Container Host VM)
  4. Create an l2bridge or l2tunnel network using docker (Container Host VM)

Multiple IP configurations is not supported on VM NIC resources created through System Center Virtual Machine Manager. It is recommended for these deployments types that you create the VM NIC resource out of band using Network Controller PowerShell.

1. Add Multiple IP Configurations

For this example, we assume that the VM NIC of the tenant virtual machine already has one IP configuration with IP address of and is attached to a VNet Resource ID of 'VNet1' and VM Subnet Resource of 'Subnet1' in the IP subnet. We will add 10 IP addresses for containers from -

Import-Module NetworkController

# Specify Network Controller REST IP or FQDN
$uri = "<NC REST IP or FQDN>"
$vnetResourceId = "VNet1"
$vsubnetResourceId = "Subnet1"

$vmnic= Get-NetworkControllerNetworkInterface -ConnectionUri $uri | where {$ -eq "" }
$vmsubnet = Get-NetworkControllerVirtualSubnet -VirtualNetworkId $vnetResourceId -ResourceId $vsubnetResourceId -ConnectionUri $uri

# For this demo, we will assume an ACL has already been defined; any ACL can be applied here
$allowallacl = Get-NetworkControllerAccessControlList -ConnectionUri $uri -ResourceId "AllowAll"

foreach ($i in 1..10)
    $newipconfig = new-object Microsoft.Windows.NetworkController.NetworkInterfaceIpConfiguration
    $props = new-object Microsoft.Windows.NetworkController.NetworkInterfaceIpConfigurationProperties

    $resourceid = "IP_192_168_1_1"
    if ($i -eq 10) 
        $resourceid += "10"
        $ipstr = ""
        $resourceid += "0$i"
        $ipstr = "$i"

    $newipconfig.ResourceId = $resourceid
    $props.PrivateIPAddress = $ipstr    

    $props.PrivateIPAllocationMethod = "Static"
    $props.Subnet = new-object Microsoft.Windows.NetworkController.Subnet
    $props.Subnet.ResourceRef = $vmsubnet.ResourceRef
    $props.AccessControlList = new-object Microsoft.Windows.NetworkController.AccessControlList
    $props.AccessControlList.ResourceRef = $allowallacl.ResourceRef

    $newipconfig.Properties = $props
    $vmnic.Properties.IpConfigurations += $newipconfig

New-NetworkControllerNetworkInterface -ResourceId $vmnic.ResourceId -Properties $vmnic.Properties -ConnectionUri $uri

2. Enable the Network Proxy


Run this script on the Hyper-V Host which is hosting the container host (tenant) virtual machine to enable the network proxy to allocate multiple IP addresses for the container host virtual machine.

PS C:\> ConfigureMCNP.ps1

3. Install Private Cloud plug-in


Run this script inside the container host (tenant) virtual machine to allow the Host Networking Service (HNS) to communicate with the network proxy on the Hyper-V Host.

PS C:\> InstallPrivateCloudPlugin.ps1

4. Create an l2bridge Container Network

On the container host (tenant) virtual machine use the docker network create command to create an l2bridge network

# Create the container network
C:\> docker network create -d l2bridge --subnet="" --gateway="" MyContainerOverlayNetwork

# Attach a container to the MyContainerOverlayNetwork 
C:\> docker run -it --network=MyContainerOverlayNetwork <image> <cmd>

Static IP assignment is not supported with l2bridge or l2tunnel container networks when used with the Microsoft SDN Stack.

More information

For more infortation about deploying an SDN infrastructure, see Deploy a Software Defined Network Infrastructure.