Docker and containers (Part 6)

by [Published on 22 June 2016 / Last Updated on 22 June 2016]

This article examines how you can use Windows PowerShell for managing Windows Server Containers.

If you would like to be notified when Mitch Tulloch releases the next part in this article series please sign up to our Real-Time Article Update newsletter.

If you would like to read the other parts in this article series please go to:


Now that we have learned about the basics of how container virtualization is implemented in the soon to be released Windows Server 2016 operating system and have examined the two "flavors" of container technology coming in Windows Server 2016, namely Windows Server Containers and Hyper-V Containers, we will continue this short series of articles by looking at the different toolsets and various ways you can manage containers hosted on Windows Server 2016 container hosts. For this present series of articles we will continue to use the Technical Preview 4 (TP4) release version of Windows Server 2016 since at the time of writing this is the version you can deploy for free in Microsoft Azure if you have a trial subscription for Azure or if you currently have an MSDN subscription. We'll also focus specifically on managing Windows Server Containers since deploying Hyper-V Containers in Microsoft Azure is currently not supported, and we'll begin by looking at some of the ways you can use Windows PowerShell to manage Windows Server Containers.

Managing Windows Server Containers using Windows PowerShell

In the article Docker and Containers (Part 4) - Implementing Windows Server Containers we have already learned how you can use Windows PowerShell to perform various tasks with Windows Server Containers. In particular the Part 4 article demonstrates how you can use PowerShell to do things like:

  • View a list of existing container images on a container host and their state, update and parent image by using the Get-ContainerImage cmdlet
  • Create a new container image on the host by using the New-Container cmdlet
  • Start or stop a container by using the Start-Container or Stop-Container cmdlets

But this is only the start. Microsoft has steadily been adding more PowerShell support for working with Windows Containers since the earlier TP3 release of Windows Server 2012, and you can use the Get-Command cmdlet with the -Module parameter as shown below to display the various PowerShell cmdlets and functions that are currently available in the Containers module for PowerShell in TP4:

PS C:\Users\testadmin> Get-Command -Module Containers
CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Function        Install-ContainerOSImage                     Containers
Function        Uninstall-ContainerOSImage                   Containers
Cmdlet          Add-ContainerNetworkAdapter                  Containers
Cmdlet          Add-ContainerSharedFolder                    Containers
Cmdlet          Connect-ContainerNetworkAdapter              Containers
Cmdlet          Disconnect-ContainerNetworkAdapter           Containers
Cmdlet          Export-ContainerImage                        Containers
Cmdlet          Get-Container                                Containers
Cmdlet          Get-ContainerHost                            Containers
Cmdlet          Get-ContainerImage                           Containers
Cmdlet          Get-ContainerMemory                          Containers
Cmdlet          Get-ContainerNetworkAdapter                  Containers
Cmdlet          Get-ContainerProcessor                       Containers
Cmdlet          Get-ContainerSharedFolder                    Containers
Cmdlet          Get-ContainerStorage                         Containers
Cmdlet          Import-ContainerImage                        Containers
Cmdlet          Move-ContainerImageRepository                Containers
Cmdlet          New-Container                                Containers
Cmdlet          New-ContainerImage                           Containers
Cmdlet          Remove-Container                             Containers
Cmdlet          Remove-ContainerImage                        Containers
Cmdlet          Remove-ContainerNetworkAdapter               Containers
Cmdlet          Remove-ContainerSharedFolder                 Containers
Cmdlet          Set-Container                                Containers
Cmdlet          Set-ContainerMemory                          Containers
Cmdlet          Set-ContainerNetworkAdapter                  Containers
Cmdlet          Set-ContainerProcessor                       Containers
Cmdlet          Set-ContainerSharedFolder                    Containers
Cmdlet          Set-ContainerStorage                         Containers
Cmdlet          Start-Container                              Containers
Cmdlet          Stop-Container                               Containers
Cmdlet          Test-ContainerImage                          Containers

For example, in the Part 4 article we created and customized a container image for the specific purpose of deploying containers that will run web apps. We then used this container image to create a new container named Container01 and added the Web Server (IIS) server role to that container. Then we stopped Container01 and captured a new container image from it, naming the new container image IISContainer. Finally, we created a new "work" container named WebServer01 based on IISContainer as a template with the intention that we would be deploying and running a containerized web app in WebServer01.

To examine the environment we created in Part 4 we can use the Get-Container cmdlet which gets information about containers on our container host:

PS C:\Users\testadmin> Get-Container
Name        State Uptime   ParentImageName
----        ----- ------   ---------------
WebServer01 Off   00:00:00 IISContainer
And if we had wanted to display all of the containers on the host that are currently in the turned off state we could do so like this:
PS C:\Users\testadmin> Get-Container | Where-Object {$_.State -eq 'Off'}
Name        State Uptime   ParentImageName
----        ----- ------   ---------------
WebServer01 Off   00:00:00 IISContainer

More info about the Get-Container cmdlet can be displayed by using the Get-Help cmdlet, but be sure to run Update-Help first as the built-in cmdlet help in Windows Server 2016 TP4 is still very incomplete and more help is now available online.

You can also use PowerShell formatting like Format-List (fl) or Format-Table (ft) to display additional information for some cmdlets in the Containers module for PowerShell on Windows Server 2016. This doesn't always work however, for example if you use Format-List (fl) with Get-Container you don't see anything more than the default output:

PS C:\Users\testadmin> Get-Container | fl
Name   : WebServer01
State  : Off
Uptime : 00:00:00

By way of contrast, the default output of the Get-ContainerImage cmdlet on our testbed host looks like this:

PS C:\Users\testadmin> Get-ContainerImage
Name              Publisher    Version      IsOSImage
----              ---------    -------      ---------
WindowsServerCore CN=Microsoft 10.0.10586.0 True
IISContainer      CN=Test      False

But when we the output of Get-ContainerImage into Format-List (fl) we can see a bunch of additional info concerning the container images on our host:

PS C:\Users\testadmin> Get-ContainerImage | fl
Publisher    : CN=Microsoft
Name         : WindowsServerCore
Version      : 10.0.10586.0
IsOSImage    : True
ParentImage  :
FullName     : CN=Microsoft_WindowsServerCore_10.0.10586.0
CimSession   : CimSession: .
ComputerName : TESTCON
IsDeleted    : False
Publisher    : CN=Test
Name         : IISContainer
Version      :
IsOSImage    : False
ParentImage  : ContainerImage (Name = 'WindowsServerCore') [Publisher = 'CN=Microsoft', Version = '10.0.10586.0']
FullName     : CN=Test_IISContainer_1.0.0.0
CimSession   : CimSession: .
ComputerName : TESTCON
IsDeleted    : False

Some of the cmdlets in the Container module are almost self-explanatory and allow you to use them (at least to some degree) even without bothering to look at the help file. For example, we might guess that the Get-ContainerNetworkAdapter cmdlet might display information about not only the network adapter itself used by the container but also the name of the switch the container is connected to. If you look back to the Part 4 article in this series you can see that the virtual switch on the Hyper-V host that our WebServer01 container is connected to has the name "Virtual Switch". By running the Get-ContainerNetworkAdapter cmdlet we can easily verify this fact:

PS C:\Users\testadmin> Get-ContainerNetworkAdapter
cmdlet Get-ContainerNetworkAdapter at command pipeline position 1
Supply values for the following parameters:
ContainerName[0]: WebServer01
Connected                : True
DynamicMacAddressEnabled : True
Id                       : Microsoft:96672589-97ED-4055-B35F-07DA94214638\2868D7E3-2AF9-4341-9C7A-8EF82FA59F89
MacAddress               : 000000000000
Name                     : Network Adapter
SwitchId                 : 0da7d5bf-389b-49a1-9836-9b5893f41e05
SwitchName               : Virtual Switch
CimSession               : CimSession: .
ComputerName             : TESTCON
IsDeleted                : False

Notice from the above output that a dynamically generated Media Access Control (MAC) address of 000000000000 is currently being assigned to the virtual network adapter. Let's say that we want to give our container network adapter a static MAC address of 112233AABBCC instead. We should be able to do this by using the Set-ContainerNetworkAdapter cmdlet, but at the time of writing the documentation (and possibly also the functionality) for this cmdlet seems to be incomplete as I kept getting the following error when I tried running this cmdlet with various input:

Set-ContainerNetworkAdapter : Failed to modify device 'Synthetic Ethernet Port'.
Invalid MAC address.
'WebServer01' failed to modify device 'Synthetic Ethernet Port'.

The moral of the story is that we will need to revisit this topic of managing Windows Server Container using PowerShell in the future once Windows Server has reached General Availability (GA) and Windows Server Containers in their final form can be deployed in Microsoft Azure. 

If you would like to be notified when Mitch Tulloch releases the next part in this article series please sign up to our Real-Time Article Update newsletter.

If you would like to read the other parts in this article series please go to:

See Also

The Author — Mitch Tulloch

Mitch Tulloch avatar

Mitch Tulloch is a well-known expert on Windows Server administration and cloud computing technologies. He has published over a thousand articles on information technology topics and has written, contributed to or been series editor for over 50 books.


Featured Links