powershell / containerprovider

ContainerImageProvider

Introduction

Install a Container image from the online Package repository

The Container OS images for Nano Server and Windows Server Core are now available in an online package repository. They can be found and installed using the ContainerImage provider of PackageManagement (a.k.a. OneGet) PowerShell module. The provider needs to be installed before using it. The following PowerShell cmdlets can be used to install the provider.

• Install-PackageProvider ContainerImage
• Import-ContainerImage ContainerImage

Once the provider is installed and imported, you can search, download, or install Container images using PowerShell cmdlets. There are two sets of cmdlets, the first set is specific for the Container OS images, including:

• Find-ContainerImage
• Save-ContainerImage
• Install-ContainerImage

The 2nd set is generic PackageManagement cmdlets, including:

• Find-Package
• Save-Package
• Get-Package

The 2nd set of cmdlets are performed the same as the 1st set, with specifying –provider ContainerImage. Without specifying the –provider parameter, it may perform slightly slower as PackageManagement will iterate all its providers. Below is the detailed usage. For a complete usage of the cmdlets, use get-help . For the general usage of the Containers, read the container MSDN doc.

Search a Container Image

Both Find-ContainerImage and Find-Package search and return a list of Container images available in the online repository.

Example 1: Find the latest version of all available Container images.

Find-ContainerImage
Find-Package –provider ContainerImage

Example 2: Search by the image name. The –name parameter accepts wildcard.

Find-ContainerImage -Name *nano*
Find-Package –provider ContainerImage -Name *nano *

Example 3: Search by version, according to –RequiredVersion, -MinimumVersion, and –MaximumVersion requirements. With –AllVersions parameter, all available versions of a Container image are returned. Without it, only the latest version is returned.

Find-ContainerImage -Name *nano* -RequiredVersion 10.0.14300.1000
Find-Package –provider ContainerImage –AllVersions -Name *nano*

Install a Container

Install-ContainerImage installs a Container image to the local machine. Both cmdlets accept pipeline result from search cmdlets. The operating system: 1.must have the Containers Package (i.e. Microsoft-NanoServer-Containers-Package Windows package) installed 2.version must match the version of Container OS image, i.e. 10.0.14300.1000 Otherwise, the installation will fail.

Example 1: Install the latest version of a Container image to the local machine.

Install-ContainerImage -Name NanoServer

Example 2: Install a Container image with pipeline result from the search cmdlets.

Find-ContainerImage *nano* | Install-ContainerImage
Find-ContainerImage -Name *windowsServercore * |Install-ContainerImage

Download a Container image

You can download and save a Container image without installation, using Save-ContainerImage or Save-Package. Both cmdlets accept pipeline result from the search cmdlets.

Example 1: Download and save a Container image to a directory that matches the wildcard path. The latest version will be saved if you do not specify the version requirements.

Save-ContainerImage -Name NanoServer -Path C:\t*p\
Save-Package –provider ContainerImage  -Name WindowsServerCore -Path .\temp -MinimumVersion 10.0.14300.1000

Example 2: Download and save a ContainerImage from the search cmdlets.

Find-ContainerImage -Name *nano* -MaximumVersion 10.2 -MinimumVersion 1.0 | Save-ContainerImage -Path c:\
Find-Package -provider ContainerImage -Name *shield* -Culture es-es | Save-Package -Path .

Inventory installed Container images

You can inventory what Container images are installed, using PackageManagement Get-Package cmdlet.

Example 1: Inventory what Container images are installed in the local machine.

Get-Package –provider ContainerImage

ContainerImage cmdlets

- Find-ContainerImage [[-Name] <string[]>] [-MinimumVersion <version>] [-MaximumVersion <version>] [-RequiredVersion <version>] [-AllVersions] [-source <string>] [<CommonParameters>]
- Save-ContainerImage [-Name] <string[]> -Path <string> [-MinimumVersion <version>] [-MaximumVersion <version>] [-RequiredVersion <version>] [-Force] [-source <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
- Save-ContainerImage [-Name] <string[]> -LiteralPath <string> [-MinimumVersion <version>] [-MaximumVersion <version>] [-RequiredVersion <version>] [-Force] [-source <string>] [-WhatIf] [-Confirm]  [<CommonParameters>]
- Install-ContainerImage [-Force] [-Source <string>] [-WhatIf] [-Confirm]  [<CommonParameters>]    
- Install-ContainerImage [-Name] <string[]> [-MinimumVersion <version>] [-MaximumVersion <version>] [-RequiredVersion <version>] [-Force] [-Source <string>] [-WhatIf] [-Confirm] [<CommonParameters>]

More examples

#Finds the container image from an online gallery that match specified criteria. It can also search from other registered sources.
# Find the latest version of all available container images
Find-ContainerImage

# Find thethe latest version of container image with the given name
-Find-ContainerImage -Name ImageName

# Find the latest version of all available container images that do not have version less than the given version
-Find-ContainerImage -MinimumVersion Version

# Find the latest version of all available container images that do not have version more than the given version
-Find-ContainerImage -MaximumVersion Version

# Find the latest version of all available container images that have the given version
-Find-ContainerImage -RequiredVersion Version

# Find the latest version of all versions of all available container images
-Find-ContainerImage –AllVersions

#Saves a container image without installing it. Save-ContainerImage cmdlet lets you save a container image locally without installing it. This lets you inspect the container image  before you install, helping to minimize the risks of malicious code or malware on your system.

# Save the latest version of the given name to the directory that matches the wildcard Path
-Save-ContainerImage -Name ImageName -Path C:\t*p\

# Save the latest version of the given name to the directory that matches the LiteralPath
-Save-ContainerImage -Name ImageName -LiteralPath C:\temp\

# Save the latest version no less than the minimum version of the given name to the relative directory given by Path
-Save -ContainerImage -Name ImageName -MinimumVersion Version -Path .\..\

# Save the latest version no more than the maximum version of the given name to the directory that matches the LiteralPath
-Save-ContainerImage -Name ImageName -MaximumVersion Version -LiteralPath C:\temp\

# Save the given version of the given name to the directory that matches the Path
-Save-ContainerImage -Name ImageName -RequiredVersion Version -Path C:\t*p\

# Save the given version of the given name to the directory that matches the Path of the default Source
-Save-ContainerImage -Name ImageName -RequiredVersion Version -Path C:\t*p\ -Source ContainerImageGallery

# All results of the find will be saved in the given LiteralPath
-Find-ContainerImage -Name ImageName | Save-ContainerImage -LiteralPath C:\temp\

#Downloads the image from the cloud and installs them on the local computer. The Install-ContainerImage gets the container image that meets the specified cirteria from the cloud.  It saves the image locally and then installs it.

# Installing the latest version of the given name to the local machine
-Install-ContainerImage -Name ImageName

# Installing the latest version of the given name from ContainerImageGallery to the local machine
-Install-ContainerImage -Name ImageName -Source ContainerImageGallery

# Installing the latest version greater the given version of the given name to the local machine
-Install-ContainerImage -Name ImageName -MinimumVersion Version

# Installing the latest version less than or equal to the given version of the given name to the local machine
-Install-ContainerImage -Name ImageName -MaximumVersion Version

# Installing the given version of the given name to the local machine
-Install-ContainerImage -Name ImageName -RequiredVersion Version

# Install all the results of find
-Find-ContainerImage -Name ImageName | Install-ContainerImage

Version

0.6.5.0

Version History

0.5.2

Initial public release for ContainerProvider

0.5.3

Adding capacity to handle folders on share

0.6.4.0

#####Revamped the provider: ######1. Renamed to ContainerImage ######2. Abides by all OneGet Provider Rules ######3. Updated the parameter Destination to Path/LiteralPath ######4. Can handle folders on share ######5. Fixed the issue of downloading large installer on Nano and remoting via BITS ######6. This version needs the Windows Server 2016 Technical Preview 5 operating system, otherwise the commands will fail

0.6.4.1

Fixed the issue of loading System assemblies

Dependencies

This module has no dependencies

containerprovider's Issues

Unable to connect from within corporate networks

I work from behind a corporate proxy. Which eventually asks for the user authentication.

How should I use this powershell module in order to download container images through the corporate proxy?

Hint: the httpClient(s) should be initialized via an HttpClientHandler

Available memory check before downloading

Need to add a check to if there is enough space on the target drive to save the installer file.

Bits Transfer failed when using WinRM to execute Install-ContainerImage, Find-Package

Hi All,
Would you know why these commands (Find-Package, Install-ContanerImage) fail when executed via WinRM on a remote TP5 VM on Azure?

@jayshah-msft, @KrishnaV-MSFT : Any hints would greatly help us troubleshoot this. Thank you very much.

-Selvi

This is the error I see for Install-ContainerImage:

---

powershell -command "& {&'Install-ContainerImage' -Name WindowsServerCore -Version 10.0.14300.1010}"

WARNING: Cannot bind argument to parameter 'fastPackageReference' because it is an empty string.
WARNING: The property 'version' cannot be found on this object. Verify that the property exists.
WARNING: The property 'Name' cannot be found on this object. Verify that the property exists.
WARNING: Cannot find path
'C:\Users\ubuntu\AppData\Local\ContainerImage\ContainerImageGallery_ContainerImageSearchIndex.txt' because it does not
exist.
WARNING: Cannot find drive. A drive with the name 'CleanUp' does not exist.
WARNING: Save-HTTPItem: Bits Transfer failed. Job State: ExitCode = -2147023651
WARNING: Based on customer feedback, we are updating the Containers PowerShell module to better align with Docker. As
part of that some cmdlet and parameter names may change in future releases. To learn more about these changes as well
as to join in the design process or provide usage feedback please refer to http://aka.ms/windowscontainers/powershell
, stderr: PackageManagement\Save-Package : No match was found for the specified search criteria and package name
'WindowsServerCore'. Try Get-PackageSource to see all available registered package sources.
At C:\Program Files\WindowsPowerShell\Modules\ContainerImage\0.6.4.0\ContainerImage.psm1:492 char:23

• ... $downloadOutput = PackageManagement\Save-Package @PSBoundParameters

•                     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  

  • CategoryInfo : ObjectNotFound: (Microsoft.Power...ets.SavePackage:SavePackage) [Save-Package], Exceptio
    n
  • FullyQualifiedErrorId : NoMatchFoundForCriteria,Microsoft.PowerShell.PackageManagement.Cmdlets.SavePackage

The property 'Name' cannot be found on this object. Verify that the property exists.
At C:\Program Files\WindowsPowerShell\Modules\ContainerImage\0.6.4.0\ContainerImage.psm1:494 char:5

• $Destination = GenerateFullPath -Location $Location `
  

• ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  

  • CategoryInfo : NotSpecified: (:) [], PropertyNotFoundException
  • FullyQualifiedErrorId : PropertyNotFoundStrict

Install-ContainerOSImage : Cannot bind argument to parameter 'WimPath' because it is an empty string.
At C:\Program Files\WindowsPowerShell\Modules\ContainerImage\0.6.4.0\ContainerImage.psm1:502 char:39

• Install-ContainerOSImage -WimPath $Destination `
  

•                                   ~~~~~~~~~~~~
  

  • CategoryInfo : InvalidData: (:) [Install-ContainerOSImage], ParameterBindingValidationException
  • FullyQualifiedErrorId : ParameterArgumentValidationErrorEmptyStringNotAllowed,Install-ContainerOSImage

Remove-Item : Cannot bind argument to parameter 'Path' because it is null.
At C:\Program Files\WindowsPowerShell\Modules\ContainerImage\0.6.4.0\ContainerImage.psm1:512 char:8

• rm $Destination
  

•    ~~~~~~~~~~~~
  

  • CategoryInfo : InvalidData: (:) [Remove-Item], ParameterBindingValidationException
  • FullyQualifiedErrorId : ParameterArgumentValidationErrorNullNotAllowed,Microsoft.PowerShell.Commands.RemoveItemCommand

---

Error for Find-Package

powershell -command "& {&'Find-Package' –provider ContainerImage}"

WARNING: Cannot bind argument to parameter 'fastPackageReference' because it is an empty string.
WARNING: The property 'version' cannot be found on this object. Verify that the property exists.
WARNING: The property 'Name' cannot be found on this object. Verify that the property exists.
WARNING: Cannot find path
'C:\Users\ubuntu\AppData\Local\ContainerImage\ContainerImageGallery_ContainerImageSearchIndex.txt' because it does not
exist.
WARNING: Cannot find drive. A drive with the name 'CleanUp' does not exist.
WARNING: Save-HTTPItem: Bits Transfer failed. Job State: ExitCode = -2147023651

---

This provider is pretty pointless (As is)

The location it connects to has only two images with summaries that haven't been updated since pre-release and builds that are out of date even for my environment. (http://go.microsoft.com/fwlink/?LinkID=746630&clcid=0x409)

Ideally, I'd like to see how this provider could be used for Docker Hub or an internal docker registry, but either way, I think the default PackageSource is pretty useless.

ArgumentNullException in SetAclCommand running Install-ContainerOSImage

On a cleanly installed Nanoserver TP4, connected using PS Direct, Install-ContainerOSImage and Install-ContainerImage fail with the following error. Reconnecting over WinRM to the IP-address, the Install-ContainerOSImage command succeeds.

[Nano]: PS C:\Users\Administrator\Documents> Install-ContainerImage -name NanoServer -version 10.0.10586.0
Value cannot be null.
Parameter name: SafeHandle cannot be null.
    + CategoryInfo          : NotSpecified: (:) [Set-Acl], ArgumentNullException
    + FullyQualifiedErrorId : System.ArgumentNullException,Microsoft.PowerShell.Commands.SetAclCommand

I'm using ContainerProvider version 0.5.2.

The last thing it lets me read is "Virtual Hard Disk Creation" after "Formatting Volume" etc

The image has the packages matching "IIS", "DSC", "Guest", "Containers", "ReverseForwarders" installed using the New-NanoServerImage command.

Install-ContainerOSImage : The term 'Install-ContainerOSImage' is not recognized as the name of a cmdlet

I'm trying to install the base images following the instructions on msdn, but whenever I try to run :

Install-ContainerImage -Name WindowsServerCore
I'm getting the following error:

Install-ContainerOSImage : The term 'Install-ContainerOSImage' is not recognized as the name of a cmdlet,
function, script file, or operable program. Check the spelling of the name, or if a path was included, verify
that the path is correct and try again.
At line:1 char:1

• Install-ContainerOSImage

• - CategoryInfo          : ObjectNotFound: (Install-ContainerOSImage:String) [], CommandNotFoundException
  - FullyQualifiedErrorId : CommandNotFoundException
  

I just installed the ContainerImage module (v 0.6.4) so I'm not sure what I'm missing.

Install-ContainerImage -Name WindowsServerCore failled

Install-ContainerImage failed during pulling NanoServer

Environment:

• Windows Server 2016 Datacenter TP 5
• Container feature installed
• Docker Engine service is running

C:\code
$ Install-ContainerImage -Name NanoServer
Install-ContainerOSImage : The term 'Install-ContainerOSImage' is not recognized as the name of a cmdlet, function, script file, o
operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
At C:\Program Files (x86)\WindowsPowerShell\Modules\ContainerImage\0.6.4.0\ContainerImage.psm1:502 char:5
+     Install-ContainerOSImage -WimPath $Destination `
+     ~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (Install-ContainerOSImage:String) [], CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException

Save-ContainerImage -Name WindowsServerCore fails in a PowerShell Remoting session

Save-ContainerImage and Install-ContainerImage cmdlets fail to work with a WindowsServerCore container image in a PowerShell remoting session.

Problem: BITS transfer cmdlets do not work as we needed in a PowerShell remoting session. The in-built HTTP downloader has some issues downloading big files. In this case, server core container image is more than 2GB.

Import-ContainerImage doesn't work

It's installed:

PS C:\Users\mcascone\Documents> Get-PackageProvider

Name                     Version          DynamicOptions
----                     -------          --------------
ContainerImage           0.6.4.0

But doesn't work:

PS C:\Users\mcascone\Documents> find-package -provider containerimage
WARNING: Cannot bind argument to parameter 'fastPackageReference' because it is an empty string.
WARNING: The property 'version' cannot be found on this object. Verify that the property exists.
WARNING: The property 'Name' cannot be found on this object. Verify that the property exists.
WARNING: Cannot find path 'C:\Users\mcascone\AppData\Local\ContainerImage\ContainerImageGallery_ContainerImageSearchIndex.txt' because it does not exist.
WARNING: Http.GetAsync did not return successful status code. Status Code: NotFound, The specified resource does not exist.

PS C:\Users\mcascone\Documents> Import-ContainerImage ContainerImage
Import-ContainerImage : The term 'Import-ContainerImage' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name,
or if a path was included, verify that the path is correct and try again.
At line:1 char:1
+ Import-ContainerImage ContainerImage
+ ~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (Import-ContainerImage:String) [], CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException

If install-ContainerImage is interrupted, retrying will fail.

If install-containerImage is interrupted after the download has completed, but before the 'expanding' has completed, the only method I found to complete the operation successfully was to rename the directory at C:\ProgramData\Microsoft\Windows\Images[ImageName] to something else.

Could not remove the directory, and the image would not show up in get-containerImage.

I suggest a -force parameter, that will overwrite a previously existing ContainerImage(if corrupted), and a -whatif parameter to see what image(s) would be added.

Install-ContainerImage fails when missing Containers Windows Feature

It might be helpful to install the Containers Windows Feature, or at least show a warning during module installation, to avoid this (confusing to newbies) error:

PS C:\Users\Administrator> Install-ContainerImage -Name NanoServer
Install-ContainerOSImage : The term 'Install-ContainerOSImage' is not recognized as the name of a cmdlet, function,
script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is
correct and try again.
At C:\Program Files\WindowsPowerShell\Modules\ContainerImage\0.6.4.0\ContainerImage.psm1:502 char:5

• Install-ContainerOSImage -WimPath $Destination `
  

• ~~~~~~~~~~~~~~~~~~~~~~~~
  

  • CategoryInfo : ObjectNotFound: (Install-ContainerOSImage:String) [], CommandNotFoundException
  • FullyQualifiedErrorId : CommandNotFoundException

Or include this as the first step in the README.md:

Install-WindowsFeature Containers

Windows 10 Install-ContainerOSImage missing

I have Windows 10 anniversary edition (winver = version 1607 OS Build 14393.51) on my home laptop and an Azure VM running Windows Server 2016 CTP 5 - installed via the shiny blue "Deploy to Azure" button here:

• https://msdn.microsoft.com/virtualization/windowscontainers/quick_start/quick_start_windows_server)

I cannot get docker images to work on either box - but for different reasons. This issue is about the windows 10 laptop. I can't install the OS base images and I'm losing my will to keep fighting with this (I guess some people are simply not destined to run their apps in a docker container).

I've followed the "quick" start instructions for windows 10 here:

• https://msdn.microsoft.com/virtualization/windowscontainers/quick_start/quick_start_windows_10

I have container & hyper-v optional WindowsOptionalFeatures enabled and docker setup. I'm struggling to install base images on the laptop. I'm based in South Africa - network connectivity is kak. These all timeout and fail:

• docker pull microsoft/windowsservercore
• Install-ContainerImage -Name WindowsServerCore

I managed to download the .wim files directly by finding the urls in Find-ContainerImage i.e.

• https://az887518.vo.msecnd.net/pshctcontainer/WindowsServerCore-10-0-14300-1000.wim

I was hoping that I could do the offline installation as mentioned here:
https://msdn.microsoft.com/en-us/virtualization/windowscontainers/management/manage_images#offline-installation

Alas I don't have Install-ContainerOSImage as a powershell commandlet on the Win 10 laptop:

Install-ContainerOSImage : The term 'Install-ContainerOSImage' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

It appears that the Install-ContainerOSImage is available on the Windows Server 2016 box though:

PS C:\Users\ilan>  get-command Install-ContainerOSImage

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Function        Install-ContainerOSImage                           1.0.0.0    Containers

Looks like it's installed by the WindowsOptionalFeatures stuff (nb which is enabled on server and laptop but seems to have different functionality) i.e.:

Enable-WindowsOptionalFeature -Online -FeatureName containers -All

I did a file comparison on the powershell files on the server vs my laptop and indeed the server has more powershell functionality than the laptop version:

C:\Windows\System32\WindowsPowerShell\v1.0\Modules\Containers\1.0.0.0
Containers.psm1 = only on the server - and contains `Install-ContainerOSImage`

Summary

• How can I install the .wim on the laptop?
• Or is there an alternative method for offline installation? (I was considering docker save on the server and docker load on the laptop)