diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 7814ef6..31c619f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -17,7 +17,7 @@ _How to test the changes_ ### Relevant Links -Any links from your research that help explain the changes +_Any links from your research that help explain the changes_ ## Checklist diff --git a/Tests/BuildkitTools.Tests.ps1 b/Tests/BuildkitTools.Tests.ps1 index 369d3bc..187aad8 100644 --- a/Tests/BuildkitTools.Tests.ps1 +++ b/Tests/BuildkitTools.Tests.ps1 @@ -30,8 +30,13 @@ Describe "BuildkitTools.psm1" { Mock Test-ServiceRegistered -ModuleName 'BuildkitTools' -MockWith { return $true } } + BeforeEach { + Remove-Item -Path "$TestDrive" -Re -Force -ErrorAction Ignore + } + AfterEach { $ENV:PESTER = $false + Remove-Item -Path "$TestDrive" -Re -Force -ErrorAction Ignore } AfterAll { @@ -124,7 +129,11 @@ Describe "BuildkitTools.psm1" { Install-Buildkit -Setup -Force -Confirm:$false Should -Invoke Register-BuildkitdService -Times 1 -Exactly -Scope It -ModuleName 'BuildkitTools' ` - -ParameterFilter { $BuildKitPath -eq "$Env:ProgramFiles\Buildkit" -and $WinCNIPath -eq "" } + -ParameterFilter { + $BuildKitPath -eq "$Env:ProgramFiles\Buildkit" -and + $WinCNIPath -eq "$ENV:ProgramFiles\Containerd\cni" + $Start -eq $true + } } It "Should uninstall tool if it is already installed" { @@ -164,10 +173,8 @@ Describe "BuildkitTools.psm1" { Context "Register-BuildkitdService" -Tag "Register-BuildkitdService" { BeforeAll { - $MockBuildKitPath = "$TestDrive\Program Files\Buildkit" - New-Item -Path "$MockBuildKitPath\bin\buildkitd.exe" -ItemType 'File' -Force | Out-Null - New-Item -Path 'TestDrive:\Program Files\Containerd\cni\conf' -ItemType 'Directory' -Force | Out-Null - Set-Content -Path "TestDrive:\Program Files\Containerd\cni\conf\0-containerd-nat.conf" -Value 'Nat config data here' -Force + $MockBuildKitPath = "C:\Program Files\Buildkit" + $expectedExecutablePath = "$MockBuildKitPath\bin\buildkitd.exe" Mock Test-Path -ModuleName "BuildkitTools" { return $true } Mock Add-MpPreference -ModuleName "BuildkitTools" @@ -176,7 +183,7 @@ Describe "BuildkitTools.psm1" { -MockWith { return $MockBuildKitPath } ` -ParameterFilter { $Tool -eq "Buildkit" } Mock Get-DefaultInstallPath -ModuleName "BuildkitTools" ` - -MockWith { return "$TestDrive\Program Files\Containerd" } ` + -MockWith { return "C:\Program Files\Containerd" } ` -ParameterFilter { $Tool -eq "containerd" } $obj = New-MockObject -Type 'System.Diagnostics.Process' -Properties @{ ExitCode = 0 } @@ -188,36 +195,39 @@ Describe "BuildkitTools.psm1" { Mock Test-ServiceRegistered -ModuleName 'BuildkitTools' -MockWith { return $false } } - AfterAll { - Get-ChildItem -Path 'TestDrive:\' | Remove-Item -Recurse -Force - } - It "Should successfully register buildkitd service using defaults" { - $MockWinCNIPath = "$TestDrive\Program Files\Containerd\cni" - $MockCniBinDir = "$MockWinCNIPath\bin" - $MockCniConfPath = "$MockWinCNIPath\conf\0-containerd-nat.conf" - Register-BuildkitdService -Force - $expectedExecutablePath = "$TestDrive\Program Files\buildkit\bin\buildkitd.exe" - $expectedCommandArguments = "--register-service --debug --containerd-worker=true --containerd-cni-config-path=`"$MockCniConfPath`" --containerd-cni-binary-dir=`"$MockCniBinDir`" --service-name buildkitd" + # The default path for Buildkit is $Env:ProgramFiles\Buildkit. + # Since tests are run as a user (not as admin), it is not possible to create a conf file in the default path. + $expectedCommandArguments = "--register-service --debug --containerd-worker=true --service-name buildkitd" - Should -Invoke Invoke-ExecutableCommand -Times 1 -Scope It -ModuleName "BuildkitTools" ` - -ParameterFilter { ($Executable -eq $expectedExecutablePath ) -and ($Arguments -eq $expectedCommandArguments) } + Should -Invoke Invoke-ExecutableCommand -Times 1 -Scope It -ModuleName "BuildkitTools" -ParameterFilter { + ($Executable -eq $expectedExecutablePath ) -and + ($Arguments -eq $expectedCommandArguments) + } Should -Invoke Start-BuildkitdService -Times 0 -Scope It -ModuleName "BuildkitTools" } It "Should successfully register buildkitd service using custom values" { + # Create mock .conf file $MockWinCNIPath = "$TestDrive\Program Files\Containerd\cni" $MockCniBinDir = "$MockWinCNIPath\bin" - $MockCniConfPath = "$TestDrive\Program Files\Containerd\cni\conf\0-containerd-nat.conf" + $MockCniConfDir = "$MockWinCNIPath\conf" + $MockCniConfPath = "$MockCniConfDir\0-containerd-nat.conf" + New-Item -Path "$MockCniConfDir" -ItemType 'Directory' -Force | Out-Null + Set-Content -Path "$MockCniConfPath" -Value 'Nat config data here' -Force Register-BuildkitdService -WinCNIPath $MockWinCNIPath -BuildKitPath $MockBuildKitPath -Start -Force $expectedExecutablePath = "$MockBuildKitPath\bin\buildkitd.exe" $expectedCommandArguments = "--register-service --debug --containerd-worker=true --containerd-cni-config-path=`"$MockCniConfPath`" --containerd-cni-binary-dir=`"$MockCniBinDir`" --service-name buildkitd" + Write-Host "'$expectedCommandArguments'" -ForegroundColor Magenta Should -Invoke Invoke-ExecutableCommand -Times 1 -Scope It -ModuleName "BuildkitTools" ` - -ParameterFilter { ($Executable -eq $expectedExecutablePath ) -and ($Arguments -eq $expectedCommandArguments) } + -ParameterFilter { + ($Executable -eq $expectedExecutablePath ) -and + ($Arguments -eq $expectedCommandArguments) + } Should -Invoke Start-BuildkitdService -Times 1 -Scope It -ModuleName "BuildkitTools" } @@ -252,12 +262,14 @@ Describe "BuildkitTools.psm1" { Mock Test-ConfFileEmpty -ModuleName "BuildkitTools" { return $true } Mock Get-ConsentToRegisterBuildkit -ModuleName "BuildkitTools" { return $yesValue } - Register-BuildkitdService -WinCNIPath "$TestDrive\SomeOtherFolder" -Force + Register-BuildkitdService -WinCNIPath $MockWinCNIPath -BuildKitPath $MockBuildKitPath -Start -Force - $expectedExecutablePath = "$MockBuildKitPath\bin\buildkitd.exe" $expectedCommandArguments = '--register-service --debug --containerd-worker=true --service-name buildkitd' Should -Invoke Invoke-ExecutableCommand -Times 1 -Scope It -ModuleName "BuildkitTools" ` - -ParameterFilter { ($Executable -eq $expectedExecutablePath ) -and ($Arguments -eq $expectedCommandArguments) } + -ParameterFilter { + ($Executable -eq $expectedExecutablePath ) -and + ($Arguments -eq $expectedCommandArguments) + } } It "Should throw an error if user does not consent to registering buildkitd service without NAT conf file" { @@ -302,35 +314,36 @@ Describe "BuildkitTools.psm1" { } It "Should successfully uninstall Buildkit" { - Mock Uninstall-BuildkitHelper -ModuleName 'BuildkitTools' + Uninstall-Buildkit -Path 'TestDrive:\Custom\Buildkit\' -Confirm:$false -Force + + # Should stop and deregister the buildkitd service + Should -Invoke Stop-BuildkitdService -Times 1 -Scope It -ModuleName "BuildkitTools" + Should -Invoke Unregister-Buildkitd -Times 1 -Scope It -ModuleName "BuildkitTools" - Uninstall-Buildkit -Path 'TestDrive:\Program Files\Buildkit' -Confirm:$false -Force + # Should remove buildkit dir + Should -Invoke Remove-Item -Times 1 -Scope It -ModuleName "BuildkitTools" ` + -ParameterFilter { $Path -eq 'TestDrive:\Custom\Buildkit\bin' } - Should -Invoke Uninstall-BuildkitHelper -Times 1 -Scope It -ModuleName "BuildkitTools" ` - -ParameterFilter { $Path -eq 'TestDrive:\Program Files\Buildkit' } + # Should not purge program data + Should -Invoke Remove-Item -Times 0 -Scope It -ModuleName "BuildkitTools" ` + -ParameterFilter { $Path -eq 'HKLM:\SYSTEM\CurrentControlSet\Services\buildkit' } + Should -Invoke Uninstall-ProgramFiles -Times 0 -Scope It -ModuleName "BuildkitTools" ` + -ParameterFilter { $Path -eq "$ENV:ProgramData\Buildkit" } + Should -Invoke Remove-FeatureFromPath -Times 0 -Scope It -ModuleName "BuildkitTools" ` + -ParameterFilter { $Feature -eq "buildkit" } } It "Should successfully uninstall Buildkit from default path" { - Mock Uninstall-BuildkitHelper -ModuleName 'BuildkitTools' - Uninstall-Buildkit -Confirm:$false -Force - Should -Invoke Uninstall-BuildkitHelper -Times 1 -Scope It -ModuleName "BuildkitTools" ` - -ParameterFilter { $Path -eq 'TestDrive:\Program Files\Buildkit' } + Should -Invoke Remove-Item -Times 0 -Scope It -ModuleName "BuildkitTools" ` + -ParameterFilter { $Path -eq 'TestDrive:\Program Files\Buildkit\bin' } } - It "Should throw an error if user does not consent to uninstalling Buildkit" { - $ENV:PESTER = $true - { Uninstall-Buildkit -Path 'TestDrive:\Program Files\Buildkit' -Confirm:$false -Force:$false } | Should -Throw "Buildkit uninstallation cancelled." - } + It "Should successfully purge program data" { + Uninstall-Buildkit -Path 'TestDrive:\Program Files\Buildkit' -Confirm:$false -Force -Purge - It "Should successfully call uninstall Buildkit helper function" { - Uninstall-BuildkitHelper -Path 'TestDrive:\Program Files\Buildkit' - - Should -Invoke Stop-BuildkitdService -Times 1 -Scope It -ModuleName "BuildkitTools" - Should -Invoke Unregister-Buildkitd -Times 1 -Scope It -ModuleName "BuildkitTools" - Should -Invoke Remove-Item -Times 1 -Scope It -ModuleName "BuildkitTools" ` - -ParameterFilter { $Path -eq 'HKLM:\SYSTEM\CurrentControlSet\Services\buildkit' } + # Should purge program data Should -Invoke Remove-Item -Times 1 -Scope It -ModuleName "BuildkitTools" ` -ParameterFilter { $Path -eq 'TestDrive:\Program Files\Buildkit' } Should -Invoke Uninstall-ProgramFiles -Times 1 -Scope It -ModuleName "BuildkitTools" ` @@ -339,26 +352,35 @@ Describe "BuildkitTools.psm1" { -ParameterFilter { $Feature -eq "buildkit" } } + It "Should do nothing if user does not consent to uninstalling Buildkit" { + $ENV:PESTER = $true + Uninstall-Buildkit -Path 'TestDrive:\Program Files\Buildkit' -Confirm:$false -Force:$false + + # Should NOT stop and deregister the buildkit service + Should -Invoke Stop-BuildkitdService -Times 0 -Scope It -ModuleName "BuildkitTools" + Should -Invoke Unregister-Buildkitd -Times 0 -Scope It -ModuleName "BuildkitTools" + + # Should NOT remove buildkit binaries/dir + Should -Invoke Remove-Item -Times 0 -Scope It -ModuleName "BuildkitTools" + } + It "Should do nothing if buildkit is not installed at specified path" { Mock Test-EmptyDirectory -ModuleName 'BuildkitTools' -MockWith { return $true } - Uninstall-BuildkitHelper -Path 'TestDrive:\Program Files\Buildkit' + Uninstall-Buildkit -Path 'TestDrive:\Program Files\Buildkit' -Confirm:$false Should -Invoke Stop-BuildkitdService -Times 0 -Scope It -ModuleName "BuildkitTools" Should -Invoke Unregister-Buildkitd -Times 0 -Scope It -ModuleName "BuildkitTools" Should -Invoke Remove-Item -Times 0 -Scope It -ModuleName "BuildkitTools" - Should -Invoke Remove-FeatureFromPath -Times 0 -Scope It -ModuleName "BuildkitTools" - - $Error[0].Exception.Message | Should -BeExactly 'Buildkit does not exist at TestDrive:\Program Files\Buildkit or the directory is empty.' } It "Should throw an error if buildkitd service stop or unregister was unsuccessful" { Mock Stop-BuildkitdService -ModuleName 'BuildkitTools' -MockWith { Throw 'Error' } - { Uninstall-BuildkitHelper -Path 'TestDrive:\Program Files\Buildkit' } | Should -Throw "Could not stop or unregister buildkitd service.*" + { Uninstall-Buildkit -Path 'TestDrive:\Program Files\Buildkit' -Confirm:$false -Force -Purge } | Should -Throw "*Could not stop or unregister buildkitd service.*" Should -Invoke Unregister-Buildkitd -Times 0 -Scope It -ModuleName "BuildkitTools" Should -Invoke Remove-Item -Times 0 -Scope It -ModuleName "BuildkitTools" Should -Invoke Remove-FeatureFromPath -Times 0 -Scope It -ModuleName "BuildkitTools" } } -} \ No newline at end of file +} diff --git a/Tests/ContainerNetworkTools.Tests.ps1 b/Tests/ContainerNetworkTools.Tests.ps1 index df53d9e..0c728bf 100644 --- a/Tests/ContainerNetworkTools.Tests.ps1 +++ b/Tests/ContainerNetworkTools.Tests.ps1 @@ -157,6 +157,8 @@ Describe "ContainerNetworkTools.psm1" { Mock New-HNSNetwork -ModuleName 'ContainerNetworkTools' Mock Restart-Service -ModuleName 'ContainerNetworkTools' Mock Install-WinCNIPlugin -ModuleName 'ContainerNetworkTools' + Mock Set-Content -ModuleName 'ContainerNetworkTools' -ParameterFilter { + $Path -eq "$ENV:ProgramFiles\Containerd\cni\conf\0-containerd-nat.conf" } } It "Should use defaults" { @@ -169,9 +171,14 @@ Describe "ContainerNetworkTools.psm1" { $Gateway -eq '99.2.0.8' $AddressPrefix -eq '99.2.0.0/16' } + + # NOTE: Since we are running as non-admin, we are not able to write to the default path + # "C:\Program Files\Containerd\cni\conf\0-containerd-nat.conf". Instead, we test that + # Set-Content is called with the correct parameters. $MockConfFilePath = "C:\Program Files\Containerd\cni\conf\0-containerd-nat.conf" - $MockConfFilePath | Should -Exist - $MockConfFilePath | Should -FileContentMatch "`"cniVersion`": `"1.0.0`"" + Should -Invoke Set-Content -ModuleName 'ContainerNetworkTools' -ParameterFilter { + $Path -eq $MockConfFilePath + } } It "Should use user-specified values" { @@ -257,42 +264,33 @@ Describe "ContainerNetworkTools.psm1" { } It "Should successfully uninstall WinCNI plugins" { - Mock Uninstall-WinCNIPluginHelper -ModuleName 'ContainerNetworkTools' + Uninstall-WinCNIPlugin -Path 'TestDrive:\Program Files' -Confirm:$false -Force - Uninstall-WinCNIPlugin -Confirm:$false -Path 'TestDrive:\Program Files\cni' -Force - - Should -Invoke Uninstall-WinCNIPluginHelper -Times 1 -Scope It -ModuleName "ContainerNetworkTools" ` + # Should remove containerd/cni dir + Should -Invoke Remove-Item -Times 1 -Scope It -ModuleName "ContainerNetworkTools" ` -ParameterFilter { $Path -eq 'TestDrive:\Program Files\cni' } } It "Should successfully uninstall WinCNI plugins from default path" { - Mock Uninstall-WinCNIPluginHelper -ModuleName 'ContainerNetworkTools' - Uninstall-WinCNIPlugin -Confirm:$false -Force - Should -Invoke Uninstall-WinCNIPluginHelper -Times 1 -Scope It -ModuleName "ContainerNetworkTools" ` - -ParameterFilter { $Path -eq 'TestDrive:\Program Files\Containerd\cni' } + Should -Invoke Remove-Item -Times 1 -Scope It -ModuleName "ContainerNetworkTools" ` + -ParameterFilter { $Path -eq "$ENV:ProgramFiles\Containerd\cni" } } - It "Should throw an error if user does not consent to uninstalling WinCNIPlugin" { + It "Should do nothing if user does not consent to uninstalling WinCNIPlugin" { $ENV:PESTER = $true - { Uninstall-WinCNIPlugin -Confirm:$false -Path 'TestDrive:\Program Files\cni' -Force:$false } | Should -Throw "Windows CNI plugins uninstallation cancelled." - } - - It "Should successfully call uninstall WinCNIPlugin helper function" { - Uninstall-WinCNIPluginHelper -Path 'TestDrive:\TestDir\cni' + Uninstall-WinCNIPlugin -Confirm:$false -Force:$false - Should -Invoke Remove-Item -Times 1 -Scope It -ModuleName "ContainerNetworkTools" ` - -ParameterFilter { $Path -eq 'TestDrive:\TestDir\cni' } + # Should NOT remove WinCNIPlugin binaries/dir + Should -Invoke Remove-Item -Times 0 -Scope It -ModuleName "ContainerNetworkTools" } It "Should do nothing if WinCNI plugins is not installed at specified path" { Mock Test-EmptyDirectory -ModuleName 'ContainerNetworkTools' -MockWith { return $true } - Uninstall-WinCNIPluginHelper -Path 'TestDrive:\TestDir\cni' + Uninstall-WinCNIPlugin -Path 'TestDrive:\TestDir\cni' -Confirm:$false Should -Invoke Remove-Item -Times 0 -Scope It -ModuleName "ContainerNetworkTools" - - $Error[0].Exception.Message | Should -Be 'Windows CNI plugin does not exist at TestDrive:\TestDir\cni or the directory is empty.' } } } \ No newline at end of file diff --git a/Tests/ContainerdTools.Tests.ps1 b/Tests/ContainerdTools.Tests.ps1 index fd3893b..bda6c42 100644 --- a/Tests/ContainerdTools.Tests.ps1 +++ b/Tests/ContainerdTools.Tests.ps1 @@ -279,35 +279,37 @@ Describe "ContainerdTools.psm1" { } It "Should successfully uninstall Containerd" { - Mock Uninstall-ContainerdHelper -ModuleName 'ContainerdTools' + Uninstall-Containerd -Path 'TestDrive:\Custom\Containerd\' -Confirm:$false -Force - Uninstall-Containerd -Path 'TestDrive:\Program Files\Containerd' -Confirm:$false -Force + # Should stop and deregister the containerd service + Should -Invoke Stop-ContainerdService -Times 1 -Scope It -ModuleName "ContainerdTools" + Should -Invoke Unregister-Containerd -Times 1 -Scope It -ModuleName "ContainerdTools" - Should -Invoke Uninstall-ContainerdHelper -Times 1 -Scope It -ModuleName "ContainerdTools" ` - -ParameterFilter { $Path -eq 'TestDrive:\Program Files\Containerd' } + # Should remove containerd binaries only not the entire dir + # The containerd dir contains cni binaries and config.toml + Should -Invoke Remove-Item -Times 1 -Scope It -ModuleName "ContainerdTools" ` + -ParameterFilter { $Path -eq 'TestDrive:\Custom\Containerd\bin' } + + # Should not purge program data + Should -Invoke Remove-Item -Times 0 -Scope It -ModuleName "ContainerdTools" ` + -ParameterFilter { $Path -eq 'HKLM:\SYSTEM\CurrentControlSet\Services\containerd' } + Should -Invoke Uninstall-ProgramFiles -Times 0 -Scope It -ModuleName "ContainerdTools" ` + -ParameterFilter { $Path -eq "$ENV:ProgramData\Containerd" } + Should -Invoke Remove-FeatureFromPath -Times 0 -Scope It -ModuleName "ContainerdTools" ` + -ParameterFilter { $Feature -eq "containerd" } } It "Should successfully uninstall Containerd from default path" { - Mock Uninstall-ContainerdHelper -ModuleName 'ContainerdTools' - Uninstall-Containerd -Confirm:$false -Force - Should -Invoke Uninstall-ContainerdHelper -Times 1 -Scope It -ModuleName "ContainerdTools" ` - -ParameterFilter { $Path -eq 'TestDrive:\Program Files\Containerd' } - } - - It "Should throw an error if user does not consent to uninstalling Containerd" { - $ENV:PESTER = $true - { Uninstall-Containerd -Path 'TestDrive:\Program Files\Containerd' -Confirm:$false -Force:$false } | Should -Throw "Containerd uninstallation cancelled." + Should -Invoke Remove-Item -Times 1 -Scope It -ModuleName "ContainerdTools" ` + -ParameterFilter { $Path -eq "$ENV:ProgramFiles\Containerd\bin" } } - It "Should successfully call uninstall Containerd helper function" { - Uninstall-ContainerdHelper -Path 'TestDrive:\Program Files\Containerd' + It "Should successfully purge program data" { + Uninstall-Containerd -Path 'TestDrive:\Program Files\Containerd' -Confirm:$false -Force -Purge - Should -Invoke Stop-ContainerdService -Times 1 -Scope It -ModuleName "ContainerdTools" - Should -Invoke Unregister-Containerd -Times 1 -Scope It -ModuleName "ContainerdTools" - Should -Invoke Remove-Item -Times 1 -Scope It -ModuleName "ContainerdTools" ` - -ParameterFilter { $Path -eq 'HKLM:\SYSTEM\CurrentControlSet\Services\containerd' } + # Should purge program data Should -Invoke Remove-Item -Times 1 -Scope It -ModuleName "ContainerdTools" ` -ParameterFilter { $Path -eq 'TestDrive:\Program Files\Containerd' } Should -Invoke Uninstall-ProgramFiles -Times 1 -Scope It -ModuleName "ContainerdTools" ` @@ -316,23 +318,32 @@ Describe "ContainerdTools.psm1" { -ParameterFilter { $Feature -eq "containerd" } } + It "Should do nothing if user does not consent to uninstalling Containerd" { + $ENV:PESTER = $true + Uninstall-Containerd -Path 'TestDrive:\Program Files\Containerd' -Confirm:$false -Force:$false + + # Should NOT stop and deregister the containerd service + Should -Invoke Stop-ContainerdService -Times 0 -Scope It -ModuleName "ContainerdTools" + Should -Invoke Unregister-Containerd -Times 0 -Scope It -ModuleName "ContainerdTools" + + # Should NOT remove containerd binaries/dir + Should -Invoke Remove-Item -Times 0 -Scope It -ModuleName "ContainerdTools" + } + It "Should do nothing if containerd is not installed at specified path" { Mock Test-EmptyDirectory -ModuleName 'ContainerdTools' -MockWith { return $true } - Uninstall-ContainerdHelper -Path 'TestDrive:\Program Files\Containerd' + Uninstall-Containerd -Path 'TestDrive:\Program Files\Containerd' -Confirm:$false Should -Invoke Stop-ContainerdService -Times 0 -Scope It -ModuleName "ContainerdTools" Should -Invoke Unregister-Containerd -Times 0 -Scope It -ModuleName "ContainerdTools" Should -Invoke Remove-Item -Times 0 -Scope It -ModuleName "ContainerdTools" - Should -Invoke Remove-FeatureFromPath -Times 0 -Scope It -ModuleName "ContainerdTools" - - $Error[0].Exception.Message | Should -BeExactly 'Containerd does not exist at TestDrive:\Program Files\Containerd or the directory is empty.' } It "Should throw an error if containerd service stop or unregister was unsuccessful" { Mock Stop-ContainerdService -ModuleName 'ContainerdTools' -MockWith { Throw 'Error' } - { Uninstall-ContainerdHelper -Path 'TestDrive:\Program Files\Containerd' } | Should -Throw "Could not stop or unregister containerd service.*" + { Uninstall-Containerd -Path 'TestDrive:\Program Files\Containerd' -Confirm:$false -Force -Purge } | Should -Throw "*Could not stop or unregister containerd service.*" Should -Invoke Unregister-Containerd -Times 0 -Scope It -ModuleName "ContainerdTools" Should -Invoke Remove-Item -Times 0 -Scope It -ModuleName "ContainerdTools" Should -Invoke Remove-FeatureFromPath -Times 0 -Scope It -ModuleName "ContainerdTools" diff --git a/Tests/NerdctlTools.Tests.ps1 b/Tests/NerdctlTools.Tests.ps1 index 75e3f52..e203913 100644 --- a/Tests/NerdctlTools.Tests.ps1 +++ b/Tests/NerdctlTools.Tests.ps1 @@ -157,56 +157,60 @@ Describe "NerdctlTools.psm1" { Mock Remove-Item -ModuleName 'NerdctlTools' Mock Remove-FeatureFromPath -ModuleName 'NerdctlTools' Mock Uninstall-ProgramFiles -ModuleName 'NerdctlTools' + + $mockProcess = New-MockObject -Type 'System.Diagnostics.Process' -Properties @{ ExitCode = 0 } + Mock Invoke-ExecutableCommand -ModuleName "NerdctlTools" -MockWith { return $mockProcess } } It "Should successfully uninstall nerdctl" { - Mock Uninstall-NerdctlHelper -ModuleName 'NerdctlTools' + Uninstall-Nerdctl -Path 'TestDrive:\Custom\nerdctl\' -Confirm:$false -Force - Uninstall-Nerdctl -Path 'TestDrive:\Program Files\nerdctl' -Confirm:$false -Force + # Should remove nerdctl dir + Should -Invoke Remove-Item -Times 1 -Scope It -ModuleName "NerdctlTools" ` + -ParameterFilter { $Path -eq 'TestDrive:\Custom\nerdctl\' } - Should -Invoke Uninstall-NerdctlHelper -Times 1 -Scope It -ModuleName "NerdctlTools" ` - -ParameterFilter { $Path -eq 'TestDrive:\Program Files\nerdctl' } + # Should not purge program data + Should -Invoke Uninstall-ProgramFiles -Times 0 -Scope It -ModuleName "NerdctlTools" + Should -Invoke Remove-FeatureFromPath -Times 0 -Scope It -ModuleName "NerdctlTools" + Should -Invoke Invoke-ExecutableCommand -Time 0 -Scope It -ModuleName "NerdctlTools" } It "Should successfully uninstall nerdctl from default path" { - Mock Uninstall-NerdctlHelper -ModuleName 'NerdctlTools' - Uninstall-Nerdctl -Confirm:$false -Force - Should -Invoke Uninstall-NerdctlHelper -Times 1 -Scope It -ModuleName "NerdctlTools" ` - -ParameterFilter { $Path -eq 'TestDrive:\Program Files\nerdctl' } - } - - It "Should throw an error if user does not consent to uninstalling nerdctl" { - $ENV:PESTER = $true - { Uninstall-Nerdctl -Confirm:$false -Path 'TestDrive:\Program Files\nerdctl'-Force:$false } | Should -Throw 'nerdctl uninstallation cancelled.' - } - - It "Should do nothing if nerdctl is not installed at specified path" { - Mock Test-EmptyDirectory -ModuleName 'NerdctlTools' -MockWith { return $true } - - Uninstall-Nerdctl -Confirm:$false -Force - Should -Invoke Remove-Item -Times 0 -Scope It -ModuleName "NerdctlTools" - Should -Invoke Remove-FeatureFromPath -Times 0 -Scope It -ModuleName "NerdctlTools" + Should -Invoke Remove-Item -Times 1 -Scope It -ModuleName "NerdctlTools" ` + -ParameterFilter { $Path -eq "$ENV:ProgramFiles\nerdctl" } } - It "Should successfully call uninstall nerdctl helper function" { - Uninstall-NerdctlHelper -Path 'TestDrive:\Program Files\nerdctl' + It "Should successfully purge program data" { + Uninstall-Nerdctl -Path 'TestDrive:\Program Files\nerdctl' -Confirm:$false -Force -Purge + # Should purge program data Should -Invoke Remove-Item -Times 1 -Scope It -ModuleName "NerdctlTools" ` -ParameterFilter { $Path -eq 'TestDrive:\Program Files\nerdctl' } Should -Invoke Uninstall-ProgramFiles -Times 1 -Scope It -ModuleName "NerdctlTools" ` -ParameterFilter { $Path -eq "$ENV:ProgramData\nerdctl" } Should -Invoke Remove-FeatureFromPath -Times 1 -Scope It -ModuleName "NerdctlTools" ` -ParameterFilter { $Feature -eq "nerdctl" } + Should -Invoke Invoke-ExecutableCommand -Time 1 -Scope It -ModuleName "NerdctlTools" -ParameterFilter { + $executable -eq "TestDrive:\Program Files\nerdctl\nerdctl.exe" -and + $arguments -eq "system prune --all" + } } - It "Should write an error if nerdctl is not installed at specified path" { - Mock Test-EmptyDirectory -ModuleName 'NerdctlTools' -MockWith { return $true } + It "Should do nothing if user does not consent to uninstalling nerdctl" { + $ENV:PESTER = $true + Uninstall-Nerdctl -Path 'TestDrive:\Program Files\nerdctl' -Confirm:$false -Force:$false - Uninstall-NerdctlHelper -Path 'TestDrive:\Program Files\nerdctl' + # Should NOT remove nerdctl binaries/dir + Should -Invoke Remove-Item -Times 0 -Scope It -ModuleName "NerdctlTools" + } + + It "Should do nothing if nerdctl is not installed at specified path" { + Mock Test-EmptyDirectory -ModuleName 'NerdctlTools' -MockWith { return $true } - $Error[0].Exception.Message | Should -BeExactly 'nerdctl does not exist at TestDrive:\Program Files\nerdctl or the directory is empty.' + Uninstall-Nerdctl -Path 'TestDrive:\Program Files\nerdctl' -Confirm:$false + Should -Invoke Remove-Item -Times 0 -Scope It -ModuleName "NerdctlTools" } } } diff --git a/containers-toolkit/Public/BuildkitTools.psm1 b/containers-toolkit/Public/BuildkitTools.psm1 index 133b2d1..2caa245 100644 --- a/containers-toolkit/Public/BuildkitTools.psm1 +++ b/containers-toolkit/Public/BuildkitTools.psm1 @@ -40,11 +40,16 @@ function Install-Buildkit { [string]$DownloadPath = "$HOME\Downloads", [Parameter(ParameterSetName = 'Setup')] - [switch]$Setup, + [Parameter(HelpMessage = "Register the buildkitd service.")] + [Alias("Setup")] + [switch]$RegisterService, [Parameter(ParameterSetName = 'Setup')] - [string]$WinCNIPath, + [Parameter(HelpMessage = "Path to Windows CNI plugin. Defaults to `$ENV:ProgramFiles\Containerd\cni")] + [string]$WinCNIPath="$ENV:ProgramFiles\Containerd\cni", + [Parameter(ParameterSetName = 'Install')] + [Parameter(ParameterSetName = 'Setup')] [Parameter(HelpMessage = 'OS architecture to download files for. Default is $env:PROCESSOR_ARCHITECTURE')] [ValidateSet('amd64', '386', "arm", "arm64")] [string]$OSArchitecture = $env:PROCESSOR_ARCHITECTURE, @@ -59,13 +64,13 @@ function Install-Buildkit { # Check if Buildkit is alread installed $isInstalled = -not (Test-EmptyDirectory -Path $InstallPath) - $WhatIfMessage = "Buildkit will be installed at $InstallPath" + $WhatIfMessage = "Buildkit will be installed at '$InstallPath'" if ($isInstalled) { - $WhatIfMessage = "Buildkit will be uninstalled from and reinstalled at $InstallPath" + $WhatIfMessage = "Buildkit will be uninstalled from and reinstalled at '$InstallPath'" } if ($Setup) { <# Action when this condition is true #> - $WhatIfMessage = "Buildkit will be installed at $InstallPath and buildkitd service will be registered and started" + $WhatIfMessage = "Buildkit will be installed at '$InstallPath' and buildkitd service will be registered and started" } } @@ -73,7 +78,7 @@ function Install-Buildkit { if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { # Check if tool already exists at specified location if ($isInstalled) { - $errMsg = "Buildkit already exists at $InstallPath or the directory is not empty" + $errMsg = "Buildkit already exists at '$InstallPath' or the directory is not empty." Write-Warning $errMsg # Uninstall if tool exists at specified location. Requires user consent @@ -95,13 +100,13 @@ function Install-Buildkit { # Download files $downloadParams = @{ - ToolName = "Buildkit" - Repository = "$BUILDKIT_REPO" - Version = $Version - OSArchitecture = $OSArchitecture - DownloadPath = $DownloadPath + ToolName = "Buildkit" + Repository = "$BUILDKIT_REPO" + Version = $Version + OSArchitecture = $OSArchitecture + DownloadPath = $DownloadPath ChecksumSchemaFile = "$ModuleParentPath\Private\schemas\in-toto.sbom.schema.json" - FileFilterRegEx = $null + FileFilterRegEx = $null } $downloadParamsProperties = [FileDownloadParameters]::new( $downloadParams.ToolName, @@ -129,7 +134,7 @@ function Install-Buildkit { # Register Buildkitd service $showCommands = $true try { - if ($Setup) { + if ($RegisterService) { Register-BuildkitdService -BuildKitPath $InstallPath -WinCNIPath $WinCNIPath -Start -Force:$true $showCommands = $false } @@ -145,7 +150,7 @@ function Install-Buildkit { } # Show buildkit binaries help - Get-ChildItem -Path "C:\Program Files\buildkit\bin" | ForEach-Object { + (Get-command -Name "buildctl", "buildkitd" -ErrorAction SilentlyContinue) | ForEach-Object { $executable = $_.Name # Remove extension from executable $commandName = $executable -replace ".exe", "" @@ -207,11 +212,11 @@ function Register-BuildkitdService { SupportsShouldProcess = $true )] param( - [parameter(HelpMessage = "Windows CNI plugin path")] - [String]$WinCNIPath, + [parameter(HelpMessage = "Windows CNI plugin path. Defaults to `$ENV:ProgramFiles\Containerd\cni")] + [String]$WinCNIPath= "$ENV:ProgramFiles\Containerd\cni", - [parameter(HelpMessage = "Buildkit path")] - [String]$BuildKitPath, + [parameter(HelpMessage = "Buildkit path. Defaults to `$ENV:ProgramFiles\Buildkit")] + [String]$BuildKitPath= "$ENV:ProgramFiles\Buildkit", [parameter(HelpMessage = "Specify to start Buildkitd service after registration is complete")] [Switch]$Start, @@ -264,6 +269,9 @@ function Register-BuildkitdService { Write-Output "Configuring buildkitd service" $buildkitdExecutable = "$BuildKitPath\bin\buildkitd.exe" + Write-Debug "Buildkitd path: $buildkitdExecutable" + + # Add buildkitd to Windows Defender exclusion list Add-MpPreference -ExclusionProcess $buildkitdExecutable if (!$WinCNIPath) { @@ -273,9 +281,11 @@ function Register-BuildkitdService { $cniBinDir = "$WinCNIPath\bin" $cniConfPath = "$WinCNIPath\conf\0-containerd-nat.conf" + Write-Debug "CNI bin dir: $cniBinDir" + Write-Debug "CNI conf path: $cniConfPath" # Register buildkit service - $command = "buildkitd.exe --register-service --debug --containerd-worker=true --containerd-cni-config-path=`"$cniConfPath`" --containerd-cni-binary-dir=`"$cniBinDir`" --service-name buildkitd" + $command = "$buildkitdExecutable --register-service --debug --containerd-worker=true --containerd-cni-config-path=`"$cniConfPath`" --containerd-cni-binary-dir=`"$cniBinDir`" --service-name buildkitd" if (Test-ConfFileEmpty -Path $cniConfPath) { $consent = $force @@ -285,7 +295,7 @@ function Register-BuildkitdService { if ($consent) { Write-Warning "Containerd conf file not found at $cniConfPath. Buildkit service will be registered without Containerd cni configurations." - $command = "buildkitd.exe --register-service --debug --containerd-worker=true --service-name buildkitd" + $command = "$buildkitdExecutable --register-service --debug --containerd-worker=true --service-name buildkitd" } else { Write-Error "Failed to register buildkit service. Containerd conf file not found at $cniConfPath.`n`t1. Ensure that the required CNI plugins are installed or you can install them using 'Install-WinCNIPlugin'.`n`t2. Create the file to resolve this issue .`n`t3. Rerun this command 'Register-BuildkitdService'" @@ -293,7 +303,11 @@ function Register-BuildkitdService { } } - $arguments = ($command -split " " | Select-Object -Skip 1) -join " " + # remove the executable extension from the command + $escapedPath = [regex]::Escape($buildkitdExecutable) + $arguments = ($command -replace "$escapedPath", "").Trim() + + # Register the service $output = Invoke-ExecutableCommand -Executable $buildkitdExecutable -Arguments $arguments if ($output.ExitCode -ne 0) { Throw "Failed to register buildkitd service. $($output.StandardError.ReadToEnd())" @@ -339,7 +353,10 @@ function Uninstall-Buildkit { )] param( [parameter(HelpMessage = "BuildKit path")] - [String]$Path, + [String]$Path = "$ENV:ProgramFiles\Buildkit", + + [parameter(HelpMessage = "Delete all Buildkit program files and program data")] + [Switch] $Purge, [parameter(HelpMessage = "Bypass confirmation to uninstall BuildKit")] [Switch] $Force @@ -351,28 +368,42 @@ function Uninstall-Buildkit { $Path = Get-DefaultInstallPath -Tool $tool } - $WhatIfMessage = "Buildkit will be uninstalled from $path and buildkitd service will be stopped and unregistered" + # If we are not purging, we are uninstalling from the bin directory + # that contains the buildkit binaries, buildkit/bin + $path = $path.TrimEnd("\") + if (-not $Purge -and (-not $path.EndsWith("\bin"))) { + $path = $path.Trim() + "\bin" + } + + $WhatIfMessage = "Buildkit will be uninstalled from '$path' and buildkitd service will be stopped and unregistered." + if ($Purge) { + $WhatIfMessage += " Buildkit program data will also be removed." + } + else { + $WhatIfMessage += " Buildkit program data won't be removed. To remove program data, run 'Uninstall-Buildkit' command without -Purge flag." + } } process { if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { - if (Test-EmptyDirectory -Path $path) { - Write-Output "$tool does not exist at $Path or the directory is empty" + if (Test-EmptyDirectory -Path "$path") { + Write-Output "$tool does not exist at '$Path' or the directory is empty" return } $consent = $force if (!$ENV:PESTER) { - $consent = $force -or $PSCmdlet.ShouldContinue($env:COMPUTERNAME, "Are you sure you want to uninstall Buildkit from $path?") + $consent = $force -or $PSCmdlet.ShouldContinue($env:COMPUTERNAME, "Are you sure you want to uninstall Buildkit from '$path'?") } if (!$consent) { - Throw "$tool uninstallation cancelled." + Write-Warning "$tool uninstallation cancelled." + return } - Write-Warning "Uninstalling preinstalled $tool at the path $path" + Write-Warning "Uninstalling preinstalled $tool at the path '$path'.`n$WhatIfMessage" try { - Uninstall-BuildkitHelper -Path $path + Uninstall-BuildkitHelper -Path "$path" -Purge:$Purge } catch { Throw "Could not uninstall $tool. $_" @@ -389,35 +420,45 @@ function Uninstall-Buildkit { function Uninstall-BuildkitHelper { param( [parameter(Mandatory = $true, HelpMessage = "Buildkit path")] - [String]$Path + [String]$Path, + + [parameter(HelpMessage = "Remove all program data for Buildkit")] + [Switch] $Purge ) - if (Test-EmptyDirectory -Path $Path) { - Write-Error "Buildkit does not exist at $Path or the directory is empty." + if (Test-EmptyDirectory -Path "$Path") { + Write-Error "Buildkit does not exist at '$Path' or the directory is empty." return } try { if (Test-ServiceRegistered -Service 'Buildkitd') { Stop-BuildkitdService - Unregister-Buildkitd -BuildkitPath $Path + Unregister-Buildkitd -BuildkitPath "$Path" } } catch { Throw "Could not stop or unregister buildkitd service. $_" } - # Delete the buildkit key - Remove-Item -Path "HKLM:\SYSTEM\CurrentControlSet\Services\buildkit" -Recurse -Force -ErrorAction Ignore - # Remove the folder where buildkit is installed and related folders - Remove-Item -Path $Path -Recurse -Force + Remove-Item -Path "$Path" -Recurse -Force + + if ($Purge) { + Write-Output "Purging Buildkit program data" - # Delete Buildkit programdata - Uninstall-ProgramFiles "$ENV:ProgramData\Buildkit" + # Delete the buildkit key + Write-Warning "Removing Buildkit registry key" + Remove-Item -Path "HKLM:\SYSTEM\CurrentControlSet\Services\buildkit" -Recurse -Force -ErrorAction Ignore - # Remove from env path - Remove-FeatureFromPath -Feature "buildkit" + # Delete Buildkit programdata + Write-Warning "Removing Buildkit program data" + Uninstall-ProgramFiles "$ENV:ProgramData\Buildkit" + + # Remove from env path + Write-Warning "Removing Buildkit from env path" + Remove-FeatureFromPath -Feature "buildkit" + } Write-Output "Successfully uninstalled buildkit." } diff --git a/containers-toolkit/Public/ContainerNetworkTools.psm1 b/containers-toolkit/Public/ContainerNetworkTools.psm1 index 1946b53..f3a6a60 100644 --- a/containers-toolkit/Public/ContainerNetworkTools.psm1 +++ b/containers-toolkit/Public/ContainerNetworkTools.psm1 @@ -14,6 +14,9 @@ Import-Module -Name "$ModuleParentPath\Private\CommonToolUtilities.psm1" -Force function Get-WinCNILatestVersion { param ( + [parameter(HelpMessage = "Source of the Windows CNI plugins. Accepted values are 'microsoft/windows-container-networking' and 'containernetworking/plugins'. Defaults to 'microsoft/windows-container-networking'")] + [ValidateSet("microsoft/windows-container-networking", "containernetworking/plugins")] + [Alias("SourceRepo", "Repository")] [String]$repo = "microsoft/windows-container-networking" ) $tool = switch ($repo.ToLower()) { @@ -56,16 +59,16 @@ function Install-WinCNIPlugin { $containerdPath = Get-DefaultInstallPath -Tool "containerd" $WinCNIPath = "$containerdPath\cni" } - $WinCNIPath = $WinCNIPath -replace '(\\bin)$', '' + $WinCNIPath = "$WinCNIPath" -replace '(\\bin)$', '' - # Check if WinCNI plugins are installed - $isInstalled = -not (Test-EmptyDirectory -Path $WinCNIPath) + # Check if the CNI plugins are already installed + $isInstalled = -not (Test-EmptyDirectory -Path "$WinCNIPath") $plugin = "Windows CNI plugins" - $WhatIfMessage = "$plugin will be installed at $WINCNIPath" + $WhatIfMessage = "$plugin will be installed at '$WINCNIPath'" if ($isInstalled) { - $WhatIfMessage = "$plugin will be uninstalled from and reinstalled at $WINCNIPath" + $WhatIfMessage = "$plugin will be uninstalled from and reinstalled at '$WINCNIPath'" } } @@ -73,7 +76,7 @@ function Install-WinCNIPlugin { if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { # Check if tool already exists at specified location if ($isInstalled) { - $errMsg = "Windows CNI plugins already exists at $WinCNIPath or the directory is not empty" + $errMsg = "Windows CNI plugins already exists at '$WinCNIPath' or the directory is not empty." Write-Warning $errMsg # Uninstall if tool exists at specified location. Requires user consent @@ -184,7 +187,7 @@ function Initialize-NatNetwork { # Check if WinCNI plugins is already installed $isInstalled = -not (Test-EmptyDirectory -Path "$WinCNIPath\bin") - $WhatIfMessage = "Initialises a NAT network using Windows CNI plugins installed" + $WhatIfMessage = "Initializes a NAT network using Windows CNI plugins installed" if (!$isInstalled) { $WhatIfMessage = "`n`t1. Import `"HostNetworkingService`" or `"HNS`" module,`n`t2. Install Windows CNI plugins, and 3. Initialize a NAT network using Windows CNI plugins installed`n" } @@ -194,7 +197,7 @@ function Initialize-NatNetwork { if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { if (!$force) { if (!$ENV:PESTER) { - if (-not $PSCmdlet.ShouldContinue('', "Are you sure you want to initialises a NAT network?`n`t`tHNS module will be imported and missing dependencies (Windows CNI Plugins) will be installed if missing.")) { + if (-not $PSCmdlet.ShouldContinue('', "Are you sure you want to initialize a NAT network?`n`t`tHNS module will be imported and missing dependencies (Windows CNI Plugins) will be installed if missing.")) { Write-Error "NAT network initialisation cancelled." return } @@ -237,7 +240,7 @@ function Initialize-NatNetwork { Throw "`"New-HNSNetwork`" command does not exist. Ensure the HNS module is installed. To resolve this issue, see`n`thttps://github.com/microsoft/containers-toolkit/blob/main/docs/FAQs.md#2-new-hnsnetwork-command-does-not-exist" } - # Set default gateway if gateway us null and generate subnet mash=k from Gateway + # Set default gateway and generate subnet mask from Gateway if (!$gateway) { $gateway = (Get-NetRoute -DestinationPrefix "0.0.0.0/0").NextHop } @@ -291,7 +294,7 @@ function Uninstall-WinCNIPlugin { )] param( [parameter(HelpMessage = "Windows CNI plugin path")] - [String]$Path, + [String]$Path="$ENV:ProgramFiles\Containerd\cni", [parameter(HelpMessage = "Bypass confirmation to uninstall Windows CNI plugins")] [Switch] $Force @@ -300,12 +303,15 @@ function Uninstall-WinCNIPlugin { begin { $tool = 'WinCNIPlugin' + # Get the default path if (!$Path) { - $ContainerdPath = Get-DefaultInstallPath -Tool "containerd" - $Path = "$ContainerdPath\cni" + $path = Get-DefaultInstallPath -Tool "containerd" } - $Path = $Path -replace '(\\bin\\?)$', '' + # Only delete the /cni dir + if (-not $path.EndsWith("\cni")) { + $path = Join-Path -Path "$path" -ChildPath "cni" + } $WhatIfMessage = "Windows CNI plugins will be uninstalled from $path" } @@ -324,7 +330,8 @@ function Uninstall-WinCNIPlugin { } if (!$consent) { - Throw "Windows CNI plugins uninstallation cancelled." + Write-Warning "$tool uninstallation cancelled." + return } Write-Warning "Uninstalling preinstalled Windows CNI plugin at the path $path" @@ -357,7 +364,7 @@ function Uninstall-WinCNIPluginHelper { } # Remove the folder where WinCNI plugins are installed - Remove-Item $Path -Recurse -Force -ErrorAction Ignore + Remove-Item $Path -Recurse -Force -ErrorAction Continue Write-Output "Successfully uninstalled Windows CNI plugin." } @@ -423,7 +430,7 @@ function Set-DefaultCNIConfig { } } "@ - $CNIConfig | Set-Content "$cniConfDir\0-containerd-nat.conf" -Force + $CNIConfig | Set-Content -Path "$cniConfDir\0-containerd-nat.conf" -Force } else { # Code that should be processed if doing a WhatIf operation diff --git a/containers-toolkit/Public/ContainerdTools.psm1 b/containers-toolkit/Public/ContainerdTools.psm1 index 85bdc89..2476038 100644 --- a/containers-toolkit/Public/ContainerdTools.psm1 +++ b/containers-toolkit/Public/ContainerdTools.psm1 @@ -33,7 +33,8 @@ function Install-Containerd { [string]$DownloadPath = "$HOME\Downloads", [Parameter(HelpMessage = "Register and start Containerd Service")] - [switch]$Setup, + [Alias("Setup")] + [switch]$RegisterService, [Parameter(HelpMessage = 'OS architecture to download files for. Default is $env:PROCESSOR_ARCHITECTURE')] [ValidateSet('amd64', '386', "arm", "arm64")] @@ -45,16 +46,16 @@ function Install-Containerd { ) begin { - # Check if Containerd is alread installed - $isInstalled = -not (Test-EmptyDirectory -Path $InstallPath) + # Check if Containerd is already installed + $isInstalled = -not (Test-EmptyDirectory -Path "$InstallPath\bin") - $WhatIfMessage = "Containerd will be installed at $InstallPath" + $WhatIfMessage = "Containerd will be installed at '$InstallPath'" if ($isInstalled) { - $WhatIfMessage = "Containerd will be uninstalled from and reinstalled at $InstallPath" + $WhatIfMessage = "Containerd will be uninstalled from and reinstalled at '$InstallPath'" } if ($Setup) { <# Action when this condition is true #> - $WhatIfMessage = "Containerd will be installed at $InstallPath and containerd service will be registered and started" + $WhatIfMessage = "Containerd will be installed at '$InstallPath' and containerd service will be registered and started" } } @@ -62,7 +63,7 @@ function Install-Containerd { if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { # Check if tool already exists at specified location if ($isInstalled) { - $errMsg = "Containerd already exists at $InstallPath or the directory is not empty" + $errMsg = "Containerd already exists at '$InstallPath' or the directory is not empty." Write-Warning $errMsg # Uninstall if tool exists at specified location. Requires user consent @@ -120,7 +121,7 @@ function Install-Containerd { $showCommands = $true try { - if ($Setup) { + if ($RegisterService) { Register-ContainerdService -ContainerdPath $InstallPath -Start -Force:$true $showCommands = $false } @@ -297,7 +298,10 @@ function Uninstall-Containerd { )] param( [parameter(HelpMessage = "Containerd path")] - [String]$Path, + [String]$Path = "$ENV:ProgramFiles\Containerd", + + [parameter(HelpMessage = "Delete all Containerd program files and program data")] + [Switch] $Purge, [parameter(HelpMessage = "Bypass confirmation to uninstall Containerd")] [Switch] $Force @@ -309,7 +313,20 @@ function Uninstall-Containerd { $Path = Get-DefaultInstallPath -Tool $tool } - $WhatIfMessage = "Containerd will be uninstalled from $path and containerd service will be stopped and unregistered" + # If we are not purging, we are uninstalling from the bin directory + # that contains the containerd binaries, containerd/bin + $path = $path.TrimEnd("\") + if (-not $Purge -and (-not $path.EndsWith("\bin"))) { + $path = $path.Trim() + "\bin" + } + + $WhatIfMessage = "Containerd will be uninstalled from '$path' and containerd service will be stopped and unregistered." + if ($Purge) { + $WhatIfMessage += " Containerd program data will also be removed." + } + else { + $WhatIfMessage += " Containerd program data won't be removed. To remove program data, run 'Uninstall-Containerd' command without -Purge flag." + } } process { @@ -325,12 +342,13 @@ function Uninstall-Containerd { } if (!$consent) { - Throw "$tool uninstallation cancelled." + Write-Warning "$tool uninstallation cancelled." + return } - Write-Warning "Uninstalling preinstalled $tool at the path $path" + Write-Warning "Uninstalling preinstalled $tool at the path '$path'.`n$WhatIfMessage" try { - Uninstall-ContainerdHelper -Path $path + Uninstall-ContainerdHelper -Path "$path" -Purge:$Purge } catch { Throw "Could not uninstall $tool. $_" @@ -348,10 +366,13 @@ function Uninstall-ContainerdHelper { param( [ValidateNotNullOrEmpty()] [parameter(Mandatory = $true, HelpMessage = "Containerd path")] - [String]$Path + [String]$Path, + + [parameter(HelpMessage = "Remove all program data for Containerd")] + [Switch] $Purge ) - if (Test-EmptyDirectory -Path $Path) { + if (Test-EmptyDirectory -Path "$Path") { Write-Error "Containerd does not exist at $Path or the directory is empty." return } @@ -359,24 +380,31 @@ function Uninstall-ContainerdHelper { try { if (Test-ServiceRegistered -Service 'containerd') { Stop-ContainerdService - Unregister-Containerd -ContainerdPath $Path + Unregister-Containerd -ContainerdPath "$Path" } } catch { Throw "Could not stop or unregister containerd service. $_" } - # Delete the containerd key - Remove-Item -Path "HKLM:\SYSTEM\CurrentControlSet\Services\containerd" -Recurse -Force -ErrorAction Ignore - # Remove the folder where containerd is installed and related folders - Remove-Item -Path $Path -Recurse -Force + Remove-Item -Path "$Path" -Recurse -Force - # Delete containerd programdata - Uninstall-ProgramFiles "$ENV:ProgramData\Containerd" + if ($Purge) { + Write-Output "Purging Containerd program data" - # Remove from env path - Remove-FeatureFromPath -Feature "containerd" + # Delete the containerd key + Write-Warning "Removing Containerd registry key" + Remove-Item -Path "HKLM:\SYSTEM\CurrentControlSet\Services\containerd" -Recurse -Force -ErrorAction Ignore + + # Delete containerd programdata + Write-Warning "Removing Containerd program data" + Uninstall-ProgramFiles "$ENV:ProgramData\Containerd" + + # Remove from env path + Write-Warning "Removing Containerd from env path" + Remove-FeatureFromPath -Feature "containerd" + } Write-Output "Successfully uninstalled Containerd." } @@ -388,7 +416,7 @@ function Unregister-Containerd ($containerdPath) { } # Unregister containerd service - $containerdExecutable = "$ContainerdPath\bin\containerd.exe" + $containerdExecutable = (Get-ChildItem -Path "$ContainerdPath" -Recurse -Filter "containerd.exe").FullName | Select-Object -First 1 $output = Invoke-ExecutableCommand -Executable $containerdExecutable -Arguments "--unregister-service" if ($output.ExitCode -ne 0) { Throw "Could not unregister containerd service. $($output.StandardError.ReadToEnd())" diff --git a/containers-toolkit/Public/NerdctlTools.psm1 b/containers-toolkit/Public/NerdctlTools.psm1 index 48c95d4..8e46a32 100644 --- a/containers-toolkit/Public/NerdctlTools.psm1 +++ b/containers-toolkit/Public/NerdctlTools.psm1 @@ -86,8 +86,9 @@ function Install-Nerdctl { ) begin { - # Check if nerdctl is already installed - $isInstalled = -not (Test-EmptyDirectory -Path $InstallPath) + # Check if Containerd is alread installed + $isInstalled = -not (Test-EmptyDirectory -Path "$InstallPath") + $toInstall = @("nerdctl") $dependencies = Get-NerdctlDependencies -Dependencies $dependencies @@ -95,9 +96,9 @@ function Install-Nerdctl { $toInstall += $dependencies } - $WhatIfMessage = "nerdctl will be installed at $installPath" + $WhatIfMessage = "nerdctl will be installed at '$installPath'" if ($isInstalled) { - $WhatIfMessage = "nerdctl will be uninstalled and reinstalled at $InstallPath" + $WhatIfMessage = "nerdctl will be uninstalled and reinstalled at '$InstallPath'" } if ($dependencies) { $WhatIfMessage = "nerdctl and its dependencies (Containerd, Buildkit, WinCNIPlugin) will be installed" @@ -108,7 +109,7 @@ function Install-Nerdctl { if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { # Check if nerdctl already exists at specified location if ($isInstalled) { - $errMsg = "nerdctl already exists at $InstallPath or the directory is not empty" + $errMsg = "nerdctl already exists at '$InstallPath' or the directory is not empty." Write-Warning $errMsg # Uninstall if tool exists at specified location. Requires user consent @@ -197,7 +198,10 @@ function Uninstall-Nerdctl { )] param( [parameter(HelpMessage = "nerdctl path")] - [String]$Path, + [String]$Path = "$Env:ProgramFiles\nerdctl", + + [parameter(HelpMessage = "Delete all nerdctl program files and program data")] + [Switch] $Purge, [parameter(HelpMessage = "Bypass confirmation to uninstall nerdctl")] [Switch] $Force @@ -209,13 +213,19 @@ function Uninstall-Nerdctl { $Path = Get-DefaultInstallPath -Tool "nerdctl" } - $WhatIfMessage = "nerdctl will be uninstalled from $Path" + $WhatIfMessage = "nerdctl will be uninstalled from '$Path'." + if ($Purge) { + $WhatIfMessage += " nerdctl program data will also be removed." + } + else { + $WhatIfMessage += " nerdctl program data won't be removed. To remove program data, run 'Uninstall-Nerdctl' command without -Purge flag." + } } process { if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { - if (Test-EmptyDirectory -Path $path) { - Write-Output "$tool does not exist at $Path or the directory is empty" + if (Test-EmptyDirectory -Path "$path") { + Write-Output "$tool does not exist at '$Path' or the directory is empty" return } @@ -225,12 +235,22 @@ function Uninstall-Nerdctl { } if (!$consent) { - Throw "$tool uninstallation cancelled." + Write-Warning "$tool uninstallation cancelled." + return } - Write-Warning "Uninstalling preinstalled $tool at the path $path" + Write-Warning "Uninstalling preinstalled $tool at the path '$path'.`n$WhatIfMessage" try { - Uninstall-NerdctlHelper -Path $path + if ($Purge) { + # Remove all unused images, not just dangling ones + $cmdOutput = Invoke-ExecutableCommand -Executable "$path\nerdctl.exe" -Arguments "system prune --all" + if ($cmdOutput.ExitCode -ne 0) { + Write-Warning "Couldn't prune images. $($cmdOutput.StandardError.ReadToEnd())" + } + } + + # Uninstall nerdctl + Uninstall-NerdctlHelper -Path "$path" -Purge:$Purge } catch { Throw "Could not uninstall $tool. $_" @@ -248,22 +268,31 @@ function Uninstall-NerdctlHelper { param( [ValidateNotNullOrEmpty()] [parameter(Mandatory = $true, HelpMessage = "nerdctl path")] - [String]$Path + [String]$Path, + + [parameter(HelpMessage = "Remove all program data for Containerd")] + [Switch] $Purge ) - if (Test-EmptyDirectory -Path $Path) { - Write-Error "nerdctl does not exist at $Path or the directory is empty." + if (Test-EmptyDirectory -Path "$Path") { + Write-Error "nerdctl does not exist at '$Path' or the directory is empty." return } # Remove the folder where nerdctl is installed and related folders - Remove-Item -Path $Path -Recurse -Force + Remove-Item -Path "$Path" -Recurse -Force + + if ($Purge) { + Write-Output "Purging nerdctl program data" - # Remove ProgramData files - Uninstall-ProgramFiles "$ENV:ProgramData\nerdctl" + # Remove ProgramData files + Write-Warning "Removing nerdctl program data" + Uninstall-ProgramFiles "$ENV:ProgramData\nerdctl" - # Remove from env path - Remove-FeatureFromPath -Feature "nerdctl" + # Remove from env path + Write-Warning "Removing nerdctl from env path" + Remove-FeatureFromPath -Feature "nerdctl" + } Write-Output "Successfully uninstalled nerdctl." } diff --git a/containers-toolkit/en-US/about_containers-toolkit.help.txt b/containers-toolkit/en-US/about_containers-toolkit.help.txt index 13ab6e1..9ec12e3 100644 --- a/containers-toolkit/en-US/about_containers-toolkit.help.txt +++ b/containers-toolkit/en-US/about_containers-toolkit.help.txt @@ -1,4 +1,4 @@ -TOPIC +TOPIC about_containerstoolkit Containers-Toolkit contains PowerShell functions that allow you to download, @@ -28,6 +28,6 @@ KEYWORDS - Containerd - BuildKit - nerdctl - - Windows CNI + - CNI - Windows Containers - Microsoft Windows diff --git a/containers-toolkit/en-US/containers-toolkit-help.xml b/containers-toolkit/en-US/containers-toolkit-help.xml index 333ee95..17cef24 100644 --- a/containers-toolkit/en-US/containers-toolkit-help.xml +++ b/containers-toolkit/en-US/containers-toolkit-help.xml @@ -200,8 +200,35 @@ Get-WinCNILatestVersion + + repo + + Source of the Windows CNI plugins. Accepted values are 'microsoft/windows-container-networking' and 'containernetworking/plugins'. Defaults to 'microsoft/windows-container-networking' + + String + + String + + + microsoft/windows-container-networking + + + + repo + + Source of the Windows CNI plugins. Accepted values are 'microsoft/windows-container-networking' and 'containernetworking/plugins'. Defaults to 'microsoft/windows-container-networking' + + String + + String + + + microsoft/windows-container-networking + + + @@ -317,6 +344,28 @@ Path where containerd is installed or $Env:ProgramFiles\Containerd\cni + Force + + Bypass confirmation to install any missing dependencies (Windows CNI plugins and HNS module) + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -342,6 +391,18 @@ 16 + + Force + + Bypass confirmation to install any missing dependencies (Windows CNI plugins and HNS module) + + SwitchParameter + + SwitchParameter + + + False + Gateway @@ -390,7 +451,19 @@ Latest version - + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -405,14 +478,10 @@ - The version provided needs to match the installed version. To avoid any issues, it is safer to install the latest version. - If Windows CNI plugins are not installed at the default or provided path, the user is prompted to install the missing plugins. - - Windows CNI plugins have not been installed. Do you want to install the Windows CNI plugins? [Y] Yes [N] No [?] Help (default is "N"): - - - - If a user enters `Y`, the user to consents to the download and installation of the missing plugins. - - If a user enters `N` (default), execution terminates with an error. + The specified version must match the installed version. To avoid compatibility issues, it is recommended to install the latest version. + If the CNI plugins are not found at the default or specified path, the user will be prompted to install them —unless `-Confirm` + is explicitly set to `$false`, in which case the plugins will be installed automatically without prompting. + If the user declines the installation, the NAT network setup operation will be terminated with a warning. @@ -447,7 +516,7 @@ - + - Downloads BuildKit files from Containerd releases (https://github.com/moby/buildkit/releases)and installs it the provided path. Once installation is complete, the downloaded files are deleted to save on disk space. - Once Buildkit is installed and added to the environment path, we can get the path where it is installed using: - - ((Get-Command -Name "build*.exe" | Where-Object {$_.Source -like " buildkit*"} | Select-Object -Unique).Source | Split-Path -Parent).TrimEnd("\bin") - + Downloads BuildKit files from Containerd releases (https://github.com/moby/buildkit/releases) and installs it the provided path. + After installation is complete, the downloaded files are deleted to save on disk space. + We can get the path where Buildkit is installed using: + ((Get-Command -Name "buildkitd.exe").Source | Split-Path -Parent).TrimEnd("\bin") - Install-BuildKit - - Confirm - - Prompts for confirmation before running the cmdlet. For more information, see the following articles: - - about_Preference_Variables - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference - - - about_Functions_CmdletBindingAttribute - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact - - - - SwitchParameter - - - False - + Install-Buildkit DownloadPath @@ -516,7 +565,7 @@ InstallPath - Path to install BuildKit. Defaults to `$ENV:ProramFiles\BuildKit` + Path to install BuildKit. Defaults to `$ENV:ProgramFiles\BuildKit` String @@ -551,7 +600,7 @@ Version - Buildkit version to use. Defaults to latest version + Buildkit version to install. Defaults to latest version String @@ -572,7 +621,18 @@ $ENV:ProgramFiles\Containerd\cni - + + Confirm + + Prompts for confirmation before running the cmdlet. For more information, see the following articles: + + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -586,26 +646,6 @@ - - Confirm - - Prompts for confirmation before running the cmdlet. For more information, see the following articles: - - about_Preference_Variables - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference - - - about_Functions_CmdletBindingAttribute - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact - - - SwitchParameter - - SwitchParameter - - - False - DownloadPath @@ -633,7 +673,7 @@ InstallPath - Path to install BuildKit. Defaults to `$ENV:ProramFiles\BuildKit` + Path to install BuildKit. Defaults to `$ENV:ProgramFiles\BuildKit` String @@ -690,7 +730,19 @@ $ENV:ProgramFiles\Containerd\cni - + + Confirm + + Prompts for confirmation before running the cmdlet. For more information, see the following articles: + + SwitchParameter + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -742,7 +794,7 @@ - + - Downloads Containerd files from containerd releases (https://github.com/containerd/containerd/releases)and installs it the provided path. Once installation is complete, the downloaded files are deleted to save on disk space. - Once Containerd is installed and added to the environment path, we can get the path where it is installed using: - - ((Get-Command -Name containerd.exe).Source | Split-Path -Parent).TrimEnd("\bin") - + Downloads Containerd files from containerd releases (https://github.com/containerd/containerd/releases)and installs it the provided path. After installation is complete, the downloaded files are deleted to save on disk space. + We can get the path where it is installed using: + ((Get-Command -Name containerd.exe).Source | Split-Path -Parent).TrimEnd("\bin") @@ -781,14 +831,14 @@ InstallPath - Path to install Containerd. Defaults to Defaults to `$ENV:ProramFiles\containerd` + Path to install Containerd. Defaults to Defaults to `$ENV:ProgramFiles\containerd` String String - $ENV:ProramFiles\containerd + $ENV:ProgramFiles\containerd DownloadPath @@ -802,25 +852,6 @@ $HOME\Downloads - - Confirm - - Prompts for confirmation before running the cmdlet. For more information, see the following articles: - - about_Preference_Variables - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference - - - about_Functions_CmdletBindingAttribute - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact - - - - SwitchParameter - - - False - Force @@ -855,7 +886,18 @@ False - + + Confirm + + Prompts for confirmation before running the cmdlet. For more information, see the following articles: + + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -869,26 +911,6 @@ - - Confirm - - Prompts for confirmation before running the cmdlet. For more information, see the following articles: - - about_Preference_Variables - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference - - - about_Functions_CmdletBindingAttribute - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact - - - SwitchParameter - - SwitchParameter - - - False - DownloadPath @@ -916,14 +938,14 @@ InstallPath - Path to install Containerd. Defaults to Defaults to `$ENV:ProramFiles\containerd` + Path to install Containerd. Defaults to Defaults to `$ENV:ProgramFiles\containerd` String String - $ENV:ProramFiles\containerd + $ENV:ProgramFiles\containerd OSArchitecture @@ -960,7 +982,20 @@ Latest version - + + + Confirm + + Prompts for confirmation before running the cmdlet. For more information, see the following articles: + + SwitchParameter + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -1092,25 +1127,6 @@ $HOME\Downloads - - Confirm - - Prompts for confirmation before running the cmdlet. For more information, see the following articles: - - about_Preference_Variables - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference - - - about_Functions_CmdletBindingAttribute - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact - - - - SwitchParameter - - - False - Force @@ -1133,19 +1149,18 @@ False - - OSArchitecture + + Confirm - OS architecture to download files for. Default is `$env:PROCESSOR_ARCHITECTURE` + Prompts for confirmation before running the cmdlet. For more information, see the following articles: - String - String + SwitchParameter - $env:PROCESSOR_ARCHITECTURE + False - + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -1171,26 +1186,6 @@ Latest version - - Confirm - - Prompts for confirmation before running the cmdlet. For more information, see the following articles: - - about_Preference_Variables - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference - - - about_Functions_CmdletBindingAttribute - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact - - - SwitchParameter - - SwitchParameter - - - False - ContainerDVersion @@ -1227,18 +1222,6 @@ False - - RegisterServices - - Register and Start Containerd and Buildkitd services and set up NAT network. - - SwitchParameter - - SwitchParameter - - - False - InstallPath @@ -1264,18 +1247,30 @@ Latest version - OSArchitecture + RegisterServices - OS architecture to download files for. Default is `$env:PROCESSOR_ARCHITECTURE` + Register and Start Containerd and Buildkitd services and set up NAT network. - String + SwitchParameter - String + SwitchParameter - $env:PROCESSOR_ARCHITECTURE + False - + + Confirm + + Prompts for confirmation before running the cmdlet. For more information, see the following articles: + + SwitchParameter + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -1361,14 +1356,14 @@ InstallPath - Path to install nerdctl. Defaults to `$ENV:ProramFiles\nerdctl` + Path to install nerdctl. Defaults to `$ENV:ProgramFiles\nerdctl` String String - $ENV:ProramFiles\nerdctl` + $ENV:ProgramFiles\nerdctl` DownloadPath @@ -1394,25 +1389,6 @@ None - - Confirm - - Prompts for confirmation before running the cmdlet. For more information, see the following articles: - - about_Preference_Variables - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference - - - about_Functions_CmdletBindingAttribute - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact - - - - SwitchParameter - - - False - Force @@ -1436,7 +1412,18 @@ $env:PROCESSOR_ARCHITECTURE - + + Confirm + + Prompts for confirmation before running the cmdlet. For more information, see the following articles: + + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -1450,26 +1437,6 @@ - - Confirm - - Prompts for confirmation before running the cmdlet. For more information, see the following articles: - - about_Preference_Variables - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference - - - about_Functions_CmdletBindingAttribute - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact - - - SwitchParameter - - SwitchParameter - - - False - Dependencies @@ -1509,14 +1476,14 @@ InstallPath - Path to install nerdctl. Defaults to `$ENV:ProramFiles\nerdctl` + Path to install nerdctl. Defaults to `$ENV:ProgramFiles\nerdctl` String String - $ENV:ProramFiles\nerdctl` + $ENV:ProgramFiles\nerdctl` OSArchitecture @@ -1542,7 +1509,19 @@ Latest version - + + Confirm + + Prompts for confirmation before running the cmdlet. For more information, see the following articles: + + SwitchParameter + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -1597,83 +1576,74 @@ - Downloads Windows CNI plugin from windows-container-networking (https://github.com/microsoft/windows-container-networking/releases)and installs it in the specified location. + Downloads Windows CNI plugin and installs it in the specified location. Install-WinCNIPlugin - - OSArchitecture + + WinCNIVersion - OS architecture to download files for. Default is `$env:PROCESSOR_ARCHITECTURE` + Windows CNI plugin version to use. Defaults to latest version. String String - $env:PROCESSOR_ARCHITECTURE + Latest version - - SourceRepo + + WinCNIPath - Source of the Windows CNI plugins. Defaults to - 'microsoft/windows-container-networking' + Location to install Windows CNI. String String - "microsoft/windows-container-networking" + Path where containerd is installed or `$Env:ProgramFiles\Containerd` - - WinCNIVersion + + Force - Windows CNI plugin version to use. Defaults to latest version. + Force Windows CNI plugins uninstallation (if it exists) without any confirmation prompts - String - String + SwitchParameter - Latest version + False - - WinCNIPath + + OSArchitecture - Location to install Windows CNI. + OS architecture to download files for. Default is `$env:PROCESSOR_ARCHITECTURE` String String - Path where containerd is installed or `$Env:ProgramFiles\Containerd` + $env:PROCESSOR_ARCHITECTURE - Confirm + SourceRepo - Prompts for confirmation before running the cmdlet. For more information, see the following articles: - - about_Preference_Variables - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference - - - about_Functions_CmdletBindingAttribute - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact - + Source of the Windows CNI plugins. Defaults to 'microsoft/windows-container-networking' + String - SwitchParameter + String - False + "microsoft/windows-container-networking" - - Force + + Confirm - Force Windows CNI plugins uninstallation (if it exists) without any confirmation prompts + Prompts for confirmation before running the cmdlet. For more information, see the following articles: SwitchParameter @@ -1681,7 +1651,7 @@ False - + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -1695,26 +1665,6 @@ - - Confirm - - Prompts for confirmation before running the cmdlet. For more information, see the following articles: - - about_Preference_Variables - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference - - - about_Functions_CmdletBindingAttribute - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact - - - SwitchParameter - - SwitchParameter - - - False - Force @@ -1742,8 +1692,7 @@ SourceRepo - Source of the Windows CNI plugins. Defaults to - 'microsoft/windows-container-networking' + Source of the Windows CNI plugins. Defaults to 'microsoft/windows-container-networking' String @@ -1752,8 +1701,7 @@ "microsoft/windows-container-networking" - + WinCNIPath Location to install Windows CNI. @@ -1777,7 +1725,19 @@ Latest version - + + Confirm + + Prompts for confirmation before running the cmdlet. For more information, see the following articles: + + SwitchParameter + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -1837,12 +1797,10 @@ Register-BuildkitdService - + BuildKitPath - Path where Buildkit is installed. If not provided, it defaults to Buildkit - path in the environment path variable or `$Env:ProgramFiles\Buildkit` + Path where Buildkit is installed. If not provided, it defaults to Buildkit path in the environment path variable or `$Env:ProgramFiles\Buildkit` String @@ -1851,8 +1809,7 @@ Buildkit path in the environment path variable or $Env:ProgramFiles\Buildkit - + WinCNIPath Path where Windows CNI plugin is installed. If not provided, it defaults to Containerd path in the environment path variable or `$Env:ProgramFiles\Containerd` @@ -1864,6 +1821,17 @@ Containerd path in the environment path variable or $Env:ProgramFiles\Containerd + + Force + + Bypass confirmation to register buildkitd service + + + SwitchParameter + + + False + Start @@ -1875,7 +1843,18 @@ False - + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -1901,8 +1880,31 @@ Buildkit path in the environment path variable or $Env:ProgramFiles\Buildkit - + + Force + + Bypass confirmation to register buildkitd service + + SwitchParameter + + SwitchParameter + + + False + + + Start + + Specify to start Buildkitd service after registration is complete + + SwitchParameter + + SwitchParameter + + + False + + WinCNIPath Path where Windows CNI plugin is installed. If not provided, it defaults to Containerd path in the environment path variable or `$Env:ProgramFiles\Containerd` @@ -1914,10 +1916,10 @@ Containerd path in the environment path variable or $Env:ProgramFiles\Containerd - - Start + + Confirm - Specify to start Buildkitd service after registration is complete + Prompts you for confirmation before running the cmdlet. SwitchParameter @@ -1926,7 +1928,7 @@ False - + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -1942,11 +1944,7 @@ When the `0-containerd-nat.conf` does not exist, the user is prompted to register buildkitd service with or without this file. - - - Buildkit conf file not found at ~\cni\conf\0-containerd-nat.conf. Do you want to register buildkit service without containerd cni configuration? [Y] Yes [N] No [?] Help (default is "Y"): - - + Buildkit conf file not found at ~\cni\conf\0-containerd-nat.conf. Do you want to register buildkit service without containerd cni configuration? [Y] Yes [N] No [?] Help (default is "Y"): - If a user enters `Y` (default), the user consents to register buildkitd service without the default containerd NAT configuration file. - If a user enters `N`, buildkitd service is not registered and the user has to register the service themselves. @@ -2010,8 +2008,7 @@ Register-ContainerdService - + ContainerdPath Path where Containerd is installed. @@ -2023,6 +2020,17 @@ The containerd path in the environment path variable or $Env:ProgramFiles\containerd + + Force + + Bypass confirmation to register containerd service + + + SwitchParameter + + + False + Start @@ -2034,7 +2042,18 @@ False - + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -2060,6 +2079,18 @@ The containerd path in the environment path variable or $Env:ProgramFiles\containerd + + Force + + Bypass confirmation to register containerd service + + SwitchParameter + + SwitchParameter + + + False + Start @@ -2072,7 +2103,19 @@ False - + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -2144,8 +2187,7 @@ Show-ContainerTools - + Latest Show latest release version @@ -2156,14 +2198,14 @@ False - + ToolName - Tool to show the version of. + Displays the version of a specified tool. If no tool is specified, it returns the versions of containerd, buildkit, and nerdctl. + String[] - String + String[] null @@ -2171,8 +2213,7 @@ - + Latest Show latest release version @@ -2184,25 +2225,24 @@ False - + ToolName - Tool to show the version of. + Displays the version of a specified tool. If no tool is specified, it returns the versions of containerd, buildkit, and nerdctl. - String + String[] - String + String[] - null (When null, it returns the version of containerd, buildkit, and nerdctl) + null + - - [System.Array](https://learn.microsoft.com/en-us/dotnet/api/system.array?view=net-7.0) + [System.Array](https://learn.microsoft.com/en-us/dotnet/api/system.array?view=net-7.0) @@ -2269,8 +2309,56 @@ Start-BuildkitdService + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + -------------------------- Example 1 -------------------------- @@ -2283,8 +2371,7 @@ Start-Service - - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/start-service?view=powershell-7.3 + https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/start-service?view=powershell-7.3 Get-BuildkitLatestVersion @@ -2328,8 +2415,56 @@ Start-ContainerdService + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + -------------------------- Example 1 -------------------------- @@ -2342,8 +2477,7 @@ Start-Service - - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/start-service?view=powershell-7.3 + https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/start-service?view=powershell-7.3 Get-ContainerdLatestVersion @@ -2387,8 +2521,56 @@ Stop-BuildkitdService + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + -------------------------- Example 1 -------------------------- @@ -2401,8 +2583,7 @@ Stop-Service - - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/stop-service?view=powershell-7.3 + https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/stop-service?view=powershell-7.3 Get-BuildkitLatestVersion @@ -2446,8 +2627,56 @@ Stop-ContainerdService + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + -------------------------- Example 1 -------------------------- @@ -2460,8 +2689,7 @@ Stop-Service - - https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/stop-service?view=powershell-7.3 + https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/stop-service?view=powershell-7.3 Get-ContainerdLatestVersion @@ -2528,8 +2756,29 @@ False - + + Purge + + Delete all Buildkit program files and program data. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -2567,8 +2816,31 @@ The Buildkit path in the environment path variable or `$Env:ProgramFiles\Buildkit` - + + Purge + + Delete all Buildkit program files and program data. + + SwitchParameter + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -2656,8 +2928,29 @@ False - + + Purge + + Delete all Containerd program files and program data. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -2695,8 +2988,31 @@ The Containerd path in the environment path variable or `$Env:ProgramFiles\Containerd` - + + Purge + + Delete all Containerd program files and program data. + + SwitchParameter + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -2784,8 +3100,29 @@ False - + + Purge + + Delete all nerdctl program files and program data. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -2823,8 +3160,31 @@ The nerdctl path in the environment path variable or $Env:ProgramFiles\nerdctl - + + Purge + + Delete all nerdctl program files and program data. + + SwitchParameter + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -2837,11 +3197,6 @@ False - - - - - -------------------------- Example 1 -------------------------- @@ -2862,9 +3217,12 @@ - + - + Uninstall-WinCNIPlugin Uninstall @@ -2902,8 +3260,18 @@ False - + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -2941,8 +3309,19 @@ $ENV:ProgramFiles\Containerd\cni - + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + WhatIf Shows what would happen if the cmdlet runs. The cmdlet isn't run. @@ -2955,11 +3334,6 @@ False - - - - - -------------------------- Example 1 -------------------------- diff --git a/docs/About/Get-BuildkitLatestVersion.md b/docs/About/Get-BuildkitLatestVersion.md index 55e5fc4..07e5c6e 100644 --- a/docs/About/Get-BuildkitLatestVersion.md +++ b/docs/About/Get-BuildkitLatestVersion.md @@ -29,10 +29,8 @@ This returns a string of the latest release version of BuildKit, e.g., v1.2.0. ```powershell PS C:\> Get-BuildkitLatestVersion -``` -```Output -v1.2.0 + v1.2.0 ``` ## PARAMETERS diff --git a/docs/About/Get-ContainerdLatestVersion.md b/docs/About/Get-ContainerdLatestVersion.md index cc36f4a..9f4f8ad 100644 --- a/docs/About/Get-ContainerdLatestVersion.md +++ b/docs/About/Get-ContainerdLatestVersion.md @@ -29,10 +29,8 @@ This returns a string of the latest release version of Containerd, e.g., v1.2.0. ```powershell PS C:\> Get-ContainerdLatestVersion -``` -```Output -v1.2.0 + v1.2.0 ``` ## PARAMETERS diff --git a/docs/About/Get-NerdctlLatestVersion.md b/docs/About/Get-NerdctlLatestVersion.md index 0aee88f..b17112f 100644 --- a/docs/About/Get-NerdctlLatestVersion.md +++ b/docs/About/Get-NerdctlLatestVersion.md @@ -29,10 +29,8 @@ This returns a string of the latest release version of nerdctl, e.g., v1.2.0. ```powershell PS C:\> Get-NerdctlLatestVersion -``` -```Output -v1.2.0 + v1.2.0 ``` ## PARAMETERS diff --git a/docs/About/Get-WinCNILatestVersion.md b/docs/About/Get-WinCNILatestVersion.md index f903d08..f07c81f 100644 --- a/docs/About/Get-WinCNILatestVersion.md +++ b/docs/About/Get-WinCNILatestVersion.md @@ -1,4 +1,4 @@ ---- +--- external help file: Containers-Toolkit-help.xml Module Name: Containers-Toolkit online version: @@ -13,13 +13,13 @@ Gets the latest Windows CNI version number. ## SYNTAX -``` -Get-WinCNILatestVersion +```Text +Get-WinCNILatestVersion [-Repo ] ``` ## DESCRIPTION -Uses GitHub API to get the latest Windows CNI plugin release version from the microsoft/windows-container-networking repository. +Uses GitHub API to get the latest Windows CNI plugin release version from the [_microsoft/windows-container-networking_](https://github.com/microsoft/windows-container-networking) repository or [_containernetworking/plugins_](https://github.com/containernetworking/plugins) repository. ## EXAMPLES @@ -29,15 +29,33 @@ This returns a string of the latest release version of Windows CNI, e.g., v1.2.0 ```powershell PS C:\> Get-WinCNILatestVersion + + v1.2.0 ``` -```Output -v1.2.0 +## PARAMETERS + +### -Repo + +Source repository for the CNI plugins. Accepted values are 'microsoft/windows-container-networking' and 'containernetworking/plugins'. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: SourceRepo, Repository + +Required: False +Position: Named +Default value: microsoft/windows-container-networking +Accept pipeline input: False +Accept wildcard characters: False ``` +## OUTPUTS + ### String -This is a string of the latest Windows CNI version release version. +This is a string of the latest CNI plugins release version. ## RELATED LINKS diff --git a/docs/About/Initialize-NatNetwork.md b/docs/About/Initialize-NatNetwork.md index 5c7c7d9..d2d9a1a 100644 --- a/docs/About/Initialize-NatNetwork.md +++ b/docs/About/Initialize-NatNetwork.md @@ -14,8 +14,8 @@ Initializes a NAT network. ## SYNTAX ``` -Initialize-NatNetwork [[-NetworkName] ] [[-Gateway] ] [[-CIDR] ] [-WhatIf] - [[-WinCNIVersion] ] [[-WinCNIPath] ] [] +Initialize-NatNetwork [[-NetworkName] ] [[-Gateway] ] [[-CIDR] ] + [[-WinCNIVersion] ] [[-WinCNIPath] ] [-Force] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -58,6 +58,22 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Force + +Bypass confirmation to install any missing dependencies (Windows CNI plugins and HNS module) + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -Gateway Gateway IP address. Defaults to default gateway address. @@ -69,14 +85,14 @@ Aliases: Required: False Position: 1 -Default value: Default gateway address +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -NetworkName -Name of the new network. Defaults to 'nat' +Name of the new network. Defaults to 'nat'. ```yaml Type: String @@ -85,14 +101,14 @@ Aliases: Required: False Position: 0 -Default value: 'nat' +Default value: nat Accept pipeline input: False Accept wildcard characters: False ``` ### -WinCNIPath -Absolute path to cni folder. +Absolute path to cni folder, e.g. ~\cni (not ~\cni\bin). ```yaml Type: String @@ -101,15 +117,14 @@ Aliases: Required: False Position: 4 -Default value: Path where containerd is installed or $Env:ProgramFiles\Containerd\cni +Default value: $env:ProgramFiles\containerd\cni Accept pipeline input: False Accept wildcard characters: False ``` ### -WinCNIVersion -Windows CNI plugin version to use. -Defaults to latest version. +Windows CNI plugins version to use. Defaults to latest version. ```yaml Type: String @@ -118,19 +133,19 @@ Aliases: Required: False Position: 3 -Default value: Latest version +Default value: latest Accept pipeline input: False Accept wildcard characters: False ``` -### -WhatIf +### -Confirm -Shows what would happen if the cmdlet runs. The cmdlet isn't run. +Prompts you for confirmation before running the cmdlet. ```yaml Type: SwitchParameter -Parameter Sets: Setup -Aliases: +Parameter Sets: (All) +Aliases: cf Required: False Position: Named @@ -139,20 +154,34 @@ Accept pipeline input: False Accept wildcard characters: False ``` -## NOTES +### -WhatIf -The version provided needs to match the installed version. To avoid any issues, it is safer to install the latest version. +Shows what would happen if the cmdlet runs. The cmdlet is not run. -If Windows CNI plugins are not installed at the default or provided path, the user is prompted to install the missing plugins. +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi -```Output -Windows CNI plugins have not been installed. -Do you want to install the Windows CNI plugins? -[Y] Yes [N] No [?] Help (default is "N"): +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False ``` -- If a user enters `Y`, the user to consents to the download and installation of the missing plugins. -- If a user enters `N` (default), execution terminates with an error. +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## NOTES + +The specified version must match the installed version. To avoid compatibility issues, it is recommended to install the latest version. + +If the CNI plugins are not found at the default or specified path, the user will be prompted to install them —unless `-Confirm` +is explicitly set to `$false`, in which case the plugins will be installed automatically without prompting. + +If the user declines the installation, the NAT network setup operation will be terminated with a warning. ## RELATED LINKS diff --git a/docs/About/Install-Buildkit.md b/docs/About/Install-Buildkit.md index c96bb3f..9d19ee8 100644 --- a/docs/About/Install-Buildkit.md +++ b/docs/About/Install-Buildkit.md @@ -15,28 +15,28 @@ Downloads and installs BuildKit. ### Install (Default) -```PowerShell -Install-Buildkit [-Version ] [-InstallPath ] [-DownloadPath ] [-OSArchitecture ] [-Force] [-WhatIf] [-Confirm] [] +``` +Install-Buildkit [-Version ] [-InstallPath ] [-DownloadPath ] [-OSArchitecture ] + [-Force] [-WhatIf] [-Confirm] [] ``` ### Setup -```PowerShell -Install-Buildkit [-Version ] [-InstallPath ] [-DownloadPath ] [-Setup] - [-WinCNIPath ] [-OSArchitecture ] [-Force] [-Confirm] [-WhatIf] [] +``` +Install-Buildkit [-Version ] [-InstallPath ] [-DownloadPath ] [-RegisterService] + [-WinCNIPath ] [-OSArchitecture ] [-Force] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -Downloads BuildKit files from [Containerd releases](https://github.com/moby/buildkit/releases) and installs it the provided path. Once installation is complete, the downloaded files are deleted to save on disk space. - -Once BuildKit is installed and added to the environment path, we can get the path where it is installed using: +Downloads BuildKit files from [Containerd releases](https://github.com/moby/buildkit/releases) and installs it the provided path. After installation is complete, the downloaded files are deleted to save on disk space. +We can get the path where Buildkit is installed using: ```PowerShell -((Get-Command -Name "build*.exe" | Where-Object {$_.Source -like "*buildkit*"} | Select-Object -Unique).Source | Split-Path -Parent).TrimEnd("\bin") +((Get-Command -Name "buildkitd.exe").Source | Split-Path -Parent).TrimEnd("\bin") ``` -**NOTE:** If BuildKit already exists at the specified install path, it will be uninstalled and the specified version will be installed. +**NOTE:** If `-Force` is specified and BuildKit is already present at the specified install path, it will be uninstalled and replaced with the specified version. Otherwise, the installation will be skipped. ## EXAMPLES @@ -58,28 +58,9 @@ PS C:\> Install-BuildKit -Version "0.12.2" -InstallPath 'C:\Test\Path\buildkit' ## PARAMETERS -### -Confirm - -Prompts for confirmation before running the cmdlet. For more information, see the following articles: - -- [about_Preference_Variables](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference) -- [about_Functions_CmdletBindingAttribute](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact) - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -DownloadPath -Path to download files. Defaults to user's Downloads folder +Path to download files. Defaults to `$HOME\Downloads` ```yaml Type: String @@ -111,7 +92,7 @@ Accept wildcard characters: False ### -InstallPath -Path to install BuildKit. Defaults to `$ENV:ProramFiles\BuildKit` +Path to install BuildKit. Defaults to `$ENV:ProgramFiles\BuildKit` ```yaml Type: String @@ -132,35 +113,35 @@ Default is `$env:PROCESSOR_ARCHITECTURE` ```yaml Type: String -Parameter Sets: Setup +Parameter Sets: (All) Aliases: Required: False Position: Named -Default value: $env:PROCESSOR_ARCHITECTURE +Default value: $env:PROCESSOR_ARCHITECTURE Accept pipeline input: False Accept wildcard characters: False ``` -### -Setup +### -RegisterService -Register and start buildkitd Service once BuildKit installation is done. +Register and start the buildkitd Service. ```yaml Type: SwitchParameter -Parameter Sets: Setup -Aliases: +Parameter Sets: (All) +Aliases: Setup Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Version -Buildkit version to install. Defaults to latest version +Buildkit version to use. Defaults to latest version. ```yaml Type: String @@ -169,7 +150,7 @@ Aliases: Required: False Position: Named -Default value: Latest version +Default value: latest Accept pipeline input: False Accept wildcard characters: False ``` @@ -190,14 +171,30 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet isn't run. +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter -Parameter Sets: Setup -Aliases: +Parameter Sets: (All) +Aliases: wi Required: False Position: Named @@ -206,6 +203,10 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + ## RELATED LINKS - [Get-BuildkitLatestVersion](Get-BuildkitLatestVersion.md) diff --git a/docs/About/Install-ContainerTools.md b/docs/About/Install-ContainerTools.md index 9f41456..a84d403 100644 --- a/docs/About/Install-ContainerTools.md +++ b/docs/About/Install-ContainerTools.md @@ -15,7 +15,8 @@ Downloads and installs container tool (Containerd, BuildKit, and nerdctl). ``` Install-ContainerTools [[-ContainerDVersion] ] [[-BuildKitVersion] ] - [[-NerdCTLVersion] ] [[-InstallPath] ] [[-DownloadPath] ] [-RegisterServices] [-OSArchitecture ] [-Force] [-Confirm] [-WhatIf] [] + [[-NerdCTLVersion] ] [[-InstallPath] ] [[-DownloadPath] ] [-RegisterServices] + [-Force] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -66,25 +67,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -Confirm - -Prompts for confirmation before running the cmdlet. For more information, see the following articles: - -- [about_Preference_Variables](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference) -- [about_Functions_CmdletBindingAttribute](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact) - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -ContainerDVersion Containerd version to install @@ -103,7 +85,8 @@ Accept wildcard characters: False ### -DownloadPath -Path to download files. Defaults to user's Downloads folder, `$HOME\Downloads` +Path to download files. +Defaults to user's Downloads folder, `$HOME\Downloads` ```yaml Type: String @@ -119,7 +102,7 @@ Accept wildcard characters: False ### -Force -Force install the tools even if they already exists at the specified path. +Force container tools uninstallation (if it exists) without any confirmation prompts ```yaml Type: SwitchParameter @@ -133,25 +116,26 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -RegisterServices +### -InstallPath -Register and Start Containerd and Buildkitd services and set up NAT network. +Path to Install files. +Defaults to Program Files, \`$Env:ProgramFiles\` ```yaml -Type: SwitchParameter +Type: String Parameter Sets: (All) Aliases: Required: False -Position: Named -Default value: False +Position: 3 +Default value: $Env:ProgramFiles Accept pipeline input: False Accept wildcard characters: False ``` -### -InstallPath +### -NerdCTLVersion -Path to Install files. Defaults to Program Files, `$Env:ProgramFiles` +nerdctl version to install ```yaml Type: String @@ -159,53 +143,54 @@ Parameter Sets: (All) Aliases: Required: False -Position: 3 -Default value: $Env:ProgramFiles +Position: 2 +Default value: Latest version Accept pipeline input: False Accept wildcard characters: False ``` -### -NerdCTLVersion +### -RegisterServices -nerdctl version to install +Register and Start Containerd and Buildkitd services and set up NAT network. ```yaml -Type: String +Type: SwitchParameter Parameter Sets: (All) Aliases: Required: False -Position: 2 -Default value: Latest version +Position: Named +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` -### -OSArchitecture +### -Confirm -OS architecture to download files for. -Default is `$env:PROCESSOR_ARCHITECTURE` +Prompts for confirmation before running the cmdlet. +For more information, see the following articles: ```yaml -Type: String -Parameter Sets: Setup -Aliases: +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf Required: False Position: Named -Default value: $env:PROCESSOR_ARCHITECTURE +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet isn't run. +Shows what would happen if the cmdlet runs. +The cmdlet isn't run. ```yaml Type: SwitchParameter -Parameter Sets: Setup -Aliases: +Parameter Sets: (All) +Aliases: wi Required: False Position: Named @@ -214,6 +199,10 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + ## RELATED LINKS - [Install-Containerd](Install-Containerd.md) diff --git a/docs/About/Install-Containerd.md b/docs/About/Install-Containerd.md index 3714724..1c28a2a 100644 --- a/docs/About/Install-Containerd.md +++ b/docs/About/Install-Containerd.md @@ -14,21 +14,20 @@ Downloads and installs Containerd. ## SYNTAX ``` -Install-Containerd [[-Version] ] [[-InstallPath] ] [[-DownloadPath] ] [-Setup] [-OSArchitecture ] [-Force] - [-WhatIf] [-Confirm] [] +Install-Containerd [[-Version] ] [[-InstallPath] ] [[-DownloadPath] ] + [-RegisterService] [-OSArchitecture ] [-Force] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -Downloads Containerd files from [Containerd releases](https://github.com/containerd/containerd/releases) and installs it the provided path. Once installation is complete, the downloaded files are deleted to save on disk space. - -Once Containerd is installed and added to the environment path, we can get the path where it is installed using: +Downloads Containerd files from [Containerd releases](https://github.com/containerd/containerd/releases) and installs it the provided path. After installation is complete, the downloaded files are deleted to save on disk space. +We can get the path where it is installed using: ```PowerShell ((Get-Command -Name containerd.exe).Source | Split-Path -Parent).TrimEnd("\bin") ``` -**NOTE:** If Containerd already exists at the specified install path, it will be uninstalled and the specified version will be installed. +**NOTE:** If `-Force` is specified and Containerd is already present at the specified install path, it will be uninstalled and replaced with the specified version. Otherwise, the installation will be skipped. ## EXAMPLES @@ -46,32 +45,12 @@ Installs Containerd version 1.7.7 at 'C:\Test\Path\containerd' and adds 'C:\Test ```powershell PS C:\> Install-Containerd -Version "1.7.7" -InstallPath 'C:\Test\Path\Containerd' -``` ## PARAMETERS -### -Confirm - -Prompts for confirmation before running the cmdlet. For more information, see the following articles: - -- [about_Preference_Variables](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference) -- [about_Functions_CmdletBindingAttribute](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact) - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -DownloadPath -Path to download files. Defaults to user's Downloads folder +Path to download files. Defaults to `$HOME\Downloads` ```yaml Type: String @@ -96,14 +75,14 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -InstallPath -Path to install Containerd. Defaults to Defaults to `$ENV:ProramFiles\containerd` +Path to install Containerd. Defaults to Defaults to `$ENV:ProgramFiles\containerd` ```yaml Type: String @@ -112,36 +91,35 @@ Aliases: Required: False Position: 1 -Default value: $ENV:ProramFiles\containerd +Default value: $ENV:ProgramFiles\containerd Accept pipeline input: False Accept wildcard characters: False ``` ### -OSArchitecture -OS architecture to download files for. -Default is `$env:PROCESSOR_ARCHITECTURE` +OS architecture to download files for. Default is `$env:PROCESSOR_ARCHITECTURE` ```yaml Type: String -Parameter Sets: Setup +Parameter Sets: (All) Aliases: Required: False Position: Named -Default value: $env:PROCESSOR_ARCHITECTURE +Default value: $env:PROCESSOR_ARCHITECTURE Accept pipeline input: False Accept wildcard characters: False ``` -### -Setup +### -RegisterService -Register and start Containerd Service once Containerd installation is done +Register and start the Containerd Service. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Setup Required: False Position: Named @@ -152,7 +130,7 @@ Accept wildcard characters: False ### -Version -Containerd version to install. Defaults to latest version +ContainerD version to use. Defaults to latest version ```yaml Type: String @@ -161,19 +139,19 @@ Aliases: Required: False Position: 0 -Default value: Latest version +Default value: latest Accept pipeline input: False Accept wildcard characters: False ``` -### -WhatIf +### -Confirm -Shows what would happen if the cmdlet runs. The cmdlet isn't run. +Prompts you for confirmation before running the cmdlet. ```yaml Type: SwitchParameter -Parameter Sets: Setup -Aliases: +Parameter Sets: (All) +Aliases: cf Required: False Position: Named @@ -182,6 +160,26 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + ## RELATED LINKS - [Get-ContainerdLatestVersion](Get-ContainerdLatestVersion.md) diff --git a/docs/About/Install-Nerdctl.md b/docs/About/Install-Nerdctl.md index 299d5db..c5a1e99 100644 --- a/docs/About/Install-Nerdctl.md +++ b/docs/About/Install-Nerdctl.md @@ -15,12 +15,12 @@ Downloads and installs nerdctl. ``` Install-Nerdctl [[-Version] ] [[-InstallPath] ] [[-DownloadPath] ] - [[-Dependencies] ] [-OSArchitecture ] [-Force] [-Confirm] [-WhatIf] [] + [[-Dependencies] ] [-OSArchitecture ] [-Force] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -Downloads Containerd files from [nerdctl releases](https://github.com/containerd/nerdctl/releases) and installs it the provided path. Once installation is complete, the downloaded files are deleted to save on disk space. +Downloads Containerd files from [nerdctl releases](https://github.com/containerd/nerdctl/releases) and installs it the provided path. After installation is complete, the downloaded files are deleted to save on disk space. ## EXAMPLES @@ -42,28 +42,9 @@ PS C:\> Install-Nerdctl -Version "1.6.1" -InstallPath 'C:\Test\Path\nerdctl' ## PARAMETERS -### -Confirm - -Prompts for confirmation before running the cmdlet. For more information, see the following articles: - -- [about_Preference_Variables](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference) -- [about_Functions_CmdletBindingAttribute](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact) - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -Dependencies -Specify the nerdctl dependencies (All, Containerd, Buildkit, WinCNIPlugin) to install. Input type: array +Specify the nerdctl dependencies (All, Containerd, Buildkit, WinCNIPlugin) to install. ```yaml Type: String[] @@ -79,7 +60,7 @@ Accept wildcard characters: False ### -DownloadPath -Path to download files. Defaults to user's Downloads folder +Path to download files. Defaults to user's Downloads folder, `$HOME\Downloads` ```yaml Type: String @@ -95,7 +76,7 @@ Accept wildcard characters: False ### -Force -Installs nerdctl (and its dependecies if specified) even if the tool already exists at the specified path. +Force nerdctl (and its dependecies if specified) uninstallation (if it exists) without any confirmation prompts ```yaml Type: SwitchParameter @@ -111,7 +92,8 @@ Accept wildcard characters: False ### -InstallPath -Path to install nerdctl. Defaults to `$ENV:ProramFiles\nerdctl` +Path to install nerdctl. +Defaults to `$ENV:ProgramFiles\nerdctl` ```yaml Type: String @@ -120,7 +102,7 @@ Aliases: Required: False Position: 1 -Default value: $ENV:ProramFiles\nerdctl` +Default value: $ENV:ProgramFiles\nerdctl` Accept pipeline input: False Accept wildcard characters: False ``` @@ -132,19 +114,20 @@ Default is `$env:PROCESSOR_ARCHITECTURE` ```yaml Type: String -Parameter Sets: Setup +Parameter Sets: (All) Aliases: Required: False Position: Named -Default value: $env:PROCESSOR_ARCHITECTURE +Default value: $env:PROCESSOR_ARCHITECTURE Accept pipeline input: False Accept wildcard characters: False ``` ### -Version -nerdctl version to install. Defaults to latest version. +nerdctl version to install. +Defaults to latest version. ```yaml Type: String @@ -153,19 +136,36 @@ Aliases: Required: False Position: 0 -Default value: Latest version +Default value: latest +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet isn't run. +Shows what would happen if the cmdlet runs. +The cmdlet is not run. ```yaml Type: SwitchParameter -Parameter Sets: Setup -Aliases: +Parameter Sets: (All) +Aliases: wi Required: False Position: Named @@ -174,6 +174,10 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + ## RELATED LINKS - [Get-NerdctlLatestVersion](Get-NerdctlLatestVersion.md) diff --git a/docs/About/Install-WinCNIPlugin.md b/docs/About/Install-WinCNIPlugin.md index 262ac0b..6b52576 100644 --- a/docs/About/Install-WinCNIPlugin.md +++ b/docs/About/Install-WinCNIPlugin.md @@ -9,18 +9,18 @@ schema: 2.0.0 ## SYNOPSIS -Downloads and installs Windows CNI plugin. +Downloads and installs CNI plugin. ## SYNTAX ``` -Install-WinCNIPlugin [[-WinCNIVersion] ] [[-WinCNIPath] ] [-OSArchitecture ] [-SourceRepo ] [-Force] [-Confirm] [-WhatIf] - [] +Install-WinCNIPlugin [[-WinCNIVersion] ] [[-WinCNIPath] ] [-SourceRepo ] + [-OSArchitecture ] [-Force] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -Downloads Windows CNI plugin from [windows-container-networking](https://github.com/microsoft/windows-container-networking/releases) and installs it in the specified location. +Downloads CNI plugin from [microsoft/windows-container-networking](https://github.com/microsoft/windows-container-networking/releases) or [containernetworking/plugin](https://github.com/containernetworking/plugins) and installs it in the specified location. ## EXAMPLES @@ -42,28 +42,9 @@ PS C:\> Install-WinCNIPlugin -WinCNIVersion "0.2.0" ## PARAMETERS -### -Confirm - -Prompts for confirmation before running the cmdlet. For more information, see the following articles: - -- [about_Preference_Variables](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference) -- [about_Functions_CmdletBindingAttribute](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact) - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -Force -Installs Windows CNI plugins even if the tool already exists at the specified path. +Force CNI plugins uninstallation (if it exists) without any confirmation prompts. ```yaml Type: SwitchParameter @@ -84,12 +65,12 @@ Default is `$env:PROCESSOR_ARCHITECTURE` ```yaml Type: String -Parameter Sets: Setup +Parameter Sets: (All) Aliases: Required: False Position: Named -Default value: $env:PROCESSOR_ARCHITECTURE +Default value: $env:PROCESSOR_ARCHITECTURE Accept pipeline input: False Accept wildcard characters: False ``` @@ -101,7 +82,7 @@ Defaults to 'microsoft/windows-container-networking' ```yaml Type: String -Parameter Sets: "microsoft/windows-container-networking", "containernetworking/plugins" +Parameter Sets: (All) Aliases: Required: False @@ -122,14 +103,15 @@ Aliases: Required: False Position: 1 -Default value: Path where containerd is installed or `$Env:ProgramFiles\Containerd` +Default value: $Env:ProgramFiles\Containerd Accept pipeline input: False Accept wildcard characters: False ``` ### -WinCNIVersion -Windows CNI plugin version to use. Defaults to latest version. +Windows CNI plugin version to use. +Defaults to latest version. ```yaml Type: String @@ -138,19 +120,36 @@ Aliases: Required: False Position: 0 -Default value: Latest version +Default value: latest +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet isn't run. +Shows what would happen if the cmdlet runs. +The cmdlet is not run. ```yaml Type: SwitchParameter -Parameter Sets: Setup -Aliases: +Parameter Sets: (All) +Aliases: wi Required: False Position: Named @@ -159,6 +158,10 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + ## RELATED LINKS - [Get-WinCNILatestVersion](Get-WinCNILatestVersion.md) diff --git a/docs/About/Register-BuildkitdService.md b/docs/About/Register-BuildkitdService.md index b2a4ba9..231f0c1 100644 --- a/docs/About/Register-BuildkitdService.md +++ b/docs/About/Register-BuildkitdService.md @@ -52,8 +52,24 @@ Parameter Sets: (All) Aliases: Required: False -Position: 0 -Default value: Buildkit path in the environment path variable or $Env:ProgramFiles\Buildkit +Position: 1 +Default value: $Env:ProgramFiles\Buildkit +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Bypass confirmation to register buildkitd service + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` @@ -77,7 +93,7 @@ Accept wildcard characters: False ### -WinCNIPath Path where Windows CNI plugin is installed. -If not provided, it defaults to Containerd path in the environment path variable or \`$Env:ProgramFiles\Containerd\` +If not provided, it defaults to Containerd path in the environment path variable or `$Env:ProgramFiles\Containerd` ```yaml Type: String @@ -85,20 +101,37 @@ Parameter Sets: (All) Aliases: Required: False -Position: 1 -Default value: Containerd path in the environment path variable or $Env:ProgramFiles\Containerd +Position: 0 +Default value: $Env:ProgramFiles\Containerd +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet isn't run. +Shows what would happen if the cmdlet runs. +The cmdlet is not run. ```yaml Type: SwitchParameter -Parameter Sets: Setup -Aliases: +Parameter Sets: (All) +Aliases: wi Required: False Position: Named @@ -107,6 +140,10 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + ## NOTES When the `0-containerd-nat.conf` does not exist, the user is prompted to register buildkitd service with or without this file. diff --git a/docs/About/Register-ContainerdService.md b/docs/About/Register-ContainerdService.md index 274296f..1550451 100644 --- a/docs/About/Register-ContainerdService.md +++ b/docs/About/Register-ContainerdService.md @@ -1,4 +1,4 @@ ---- +--- external help file: Containers-Toolkit-help.xml Module Name: Containers-Toolkit online version: @@ -52,7 +52,23 @@ Aliases: Required: False Position: 0 -Default value: The containerd path in the environment path variable or $Env:ProgramFiles\containerd +Default value: $Env:ProgramFiles\containerd +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Bypass confirmation to register containerd service + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` @@ -68,11 +84,48 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + ## RELATED LINKS - [Get-ContainerdLatestVersion](Get-ContainerdLatestVersion.md) diff --git a/docs/About/Show-ContainerTools.md b/docs/About/Show-ContainerTools.md index ca10538..cf43ce1 100644 --- a/docs/About/Show-ContainerTools.md +++ b/docs/About/Show-ContainerTools.md @@ -1,4 +1,4 @@ ---- +--- external help file: Containers-Toolkit-help.xml Module Name: Containers-Toolkit online version: @@ -13,8 +13,8 @@ List container tools (Containerd, BuildKit, and nerdctl) install status. ## SYNTAX -```PowerShell -Show-ContainerTools [-Latest] [-ToolName ] [] +``` +Show-ContainerTools [-Latest] [-ToolName ] [] ``` ## DESCRIPTION @@ -27,14 +27,12 @@ List container tools (Containerd, BuildKit, nerdctl) and shows if the tool is in ```powershell PS C:\> Show-ContainerTools -Latest -``` -```Output -Tool Installed Version LatestVersion ----- --------- ------- ------------- -containerd True v1.7.7 v1.7.7 -buildkit True v0.12.2 v0.12.2 -nerdctl True unknown v1.6.1 + Tool Installed Version LatestVersion + ------ ------ ------ ------ + containerd True v1.7.7 v1.7.7 + buildkit False - v0.12.2 + nerdctl True unknown v1.6.1 ``` ## PARAMETERS @@ -50,11 +48,32 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` +### -ToolName + +Displays the version of a specified tool. +If no tool is specified, it returns the versions of containerd, buildkit, and nerdctl. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: Null +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + ## OUTPUTS ### [System.Array](https://learn.microsoft.com/en-us/dotnet/api/system.array?view=net-7.0) @@ -73,7 +92,8 @@ Returns an array of [PSCustomObject](https://learn.microsoft.com/en-us/dotnet/ap ## NOTES 1. This information may not be accurate if a tool's paths has not been added to environment path. -2. A daemon's status could be unavailable if it has not been installed +2. A daemon's status could be unavailable if the service has not been registered or started. +3. The latest version is fetched from the GitHub releases page of the tool. ## RELATED LINKS diff --git a/docs/About/Start-BuildkitdService.md b/docs/About/Start-BuildkitdService.md index 4fec310..5c1c277 100644 --- a/docs/About/Start-BuildkitdService.md +++ b/docs/About/Start-BuildkitdService.md @@ -1,4 +1,4 @@ ---- +--- external help file: Containers-Toolkit-help.xml Module Name: Containers-Toolkit online version: @@ -14,7 +14,7 @@ Starts buildkitd service. ## SYNTAX ``` -Start-BuildkitdService +Start-BuildkitdService [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -31,6 +31,45 @@ Start buildkitd Service. PS C:\> Start-BuildkitdService ``` +## PARAMETERS + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + ## RELATED LINKS - [Start-Service](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/start-service?view=powershell-7.3) diff --git a/docs/About/Start-ContainerdService.md b/docs/About/Start-ContainerdService.md index 84f920f..853df79 100644 --- a/docs/About/Start-ContainerdService.md +++ b/docs/About/Start-ContainerdService.md @@ -1,4 +1,4 @@ ---- +--- external help file: Containers-Toolkit-help.xml Module Name: Containers-Toolkit online version: @@ -14,7 +14,7 @@ Starts Containerd service. ## SYNTAX ``` -Start-ContainerdService +Start-ContainerdService [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -31,6 +31,45 @@ Start Containerd Service. PS C:\> Start-ContainerdService ``` +## PARAMETERS + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + ## RELATED LINKS - [Start-Service](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/start-service?view=powershell-7.3) diff --git a/docs/About/Stop-BuildkitdService.md b/docs/About/Stop-BuildkitdService.md index 3cf3057..4c9eacc 100644 --- a/docs/About/Stop-BuildkitdService.md +++ b/docs/About/Stop-BuildkitdService.md @@ -1,4 +1,4 @@ ---- +--- external help file: Containers-Toolkit-help.xml Module Name: Containers-Toolkit online version: @@ -14,7 +14,7 @@ Stops buildkitd service. ## SYNTAX ``` -Stop-BuildkitdService +Stop-BuildkitdService [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -31,6 +31,42 @@ Start buildkitd Service. PS C:\> Stop-BuildkitdService ``` +## PARAMETERS + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + ## RELATED LINKS - [Stop-Service](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/stop-service?view=powershell-7.3) diff --git a/docs/About/Stop-ContainerdService.md b/docs/About/Stop-ContainerdService.md index 5e8a96a..b82f4d7 100644 --- a/docs/About/Stop-ContainerdService.md +++ b/docs/About/Stop-ContainerdService.md @@ -1,4 +1,4 @@ ---- +--- external help file: Containers-Toolkit-help.xml Module Name: Containers-Toolkit online version: @@ -14,7 +14,7 @@ Stops Containerd service. ## SYNTAX ``` -Stop-ContainerdService +Stop-ContainerdService [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -31,6 +31,45 @@ Stop Containerd Service. PS C:\> Stop-ContainerdService ``` +## PARAMETERS + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + ## RELATED LINKS - [Stop-Service](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/stop-service?view=powershell-7.3) diff --git a/docs/About/Uninstall-Buildkit.md b/docs/About/Uninstall-Buildkit.md index b8240c9..5e0a7cb 100644 --- a/docs/About/Uninstall-Buildkit.md +++ b/docs/About/Uninstall-Buildkit.md @@ -15,12 +15,13 @@ Uninstalls BuildKit. ## SYNTAX ``` -Uninstall-Buildkit [[-Path] ] [-Force] [-WhatIf] [] +Uninstall-Buildkit [[-Path] ] [-Purge] [-Force] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -To uninstall BuildKit, this command stops buildkitd service and unregisters buildkitd service. The BuildKit directory is then deleted and BuildKit is removed from the environment path. +To uninstall BuildKit, this command stops buildkitd service and unregisters buildkitd service. +The BuildKit directory is then deleted and BuildKit is removed from the environment path. ## EXAMPLES @@ -66,13 +67,13 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -WhatIf +### -Purge -Shows what would happen if the cmdlet runs. The cmdlet isn't run. +Delete all Buildkit program files and program data. ```yaml Type: SwitchParameter -Parameter Sets: Setup +Parameter Sets: (All) Aliases: Required: False @@ -82,6 +83,43 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + ## RELATED LINKS - [Get-BuildkitLatestVersion](Get-BuildkitLatestVersion.md) diff --git a/docs/About/Uninstall-Containerd.md b/docs/About/Uninstall-Containerd.md index dde5bf2..140f0eb 100644 --- a/docs/About/Uninstall-Containerd.md +++ b/docs/About/Uninstall-Containerd.md @@ -1,4 +1,4 @@ ---- +--- external help file: containers-toolkit-help.xml Module Name: containers-toolkit online version: @@ -14,12 +14,13 @@ Uninstalls Containerd. ## SYNTAX ``` -Uninstall-Containerd [[-Path] ] [-Force] [-WhatIf] [] +Uninstall-Containerd [[-Path] ] [-Purge] [-Force] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -To uninstall Containerd, this function first stops Containerd service and unregisters Containerd service. The Containerd directory is then deleted and Containerd is removed from the environment path. +To uninstall Containerd, this function first stops Containerd service and unregisters Containerd service. +The Containerd directory is then deleted and Containerd is removed from the environment path. ## EXAMPLES @@ -44,7 +45,7 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` @@ -60,18 +61,18 @@ Aliases: Required: False Position: 0 -Default value: The Containerd path in the environment path variable or `$Env:ProgramFiles\Containerd` +Default value: $Env:ProgramFiles\Containerd Accept pipeline input: False Accept wildcard characters: False ``` -### -WhatIf +### -Purge -Shows what would happen if the cmdlet runs. The cmdlet isn't run. +Delete all Containerd program files and program data. ```yaml Type: SwitchParameter -Parameter Sets: Setup +Parameter Sets: (All) Aliases: Required: False @@ -81,6 +82,44 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + + ## RELATED LINKS - [Get-ContainerdLatestVersion](Get-ContainerdLatestVersion.md) diff --git a/docs/About/Uninstall-Nerdctl.md b/docs/About/Uninstall-Nerdctl.md index 230e20e..f85ada8 100644 --- a/docs/About/Uninstall-Nerdctl.md +++ b/docs/About/Uninstall-Nerdctl.md @@ -14,7 +14,7 @@ Uninstalls nerdctl. ## SYNTAX ``` -Uninstall-Nerdctl [[-Path] ] [-Force] [-WhatIf] [] +Uninstall-Nerdctl [[-Path] ] [-Purge] [-Force] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -60,18 +60,18 @@ Aliases: Required: False Position: 0 -Default value: The nerdctl path in the environment path variable or $Env:ProgramFiles\nerdctl +Default value: $Env:ProgramFiles\nerdctl Accept pipeline input: False Accept wildcard characters: False ``` -### -WhatIf +### -Purge -Shows what would happen if the cmdlet runs. The cmdlet isn't run. +Delete all nerdctl program files and program data. ```yaml Type: SwitchParameter -Parameter Sets: Setup +Parameter Sets: (All) Aliases: Required: False @@ -81,6 +81,43 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + ## RELATED LINKS - [Get-NerdctlLatestVersion](Get-NerdctlLatestVersion.md) diff --git a/docs/About/Uninstall-WinCNIPlugin.md b/docs/About/Uninstall-WinCNIPlugin.md index 031ece9..2dbace0 100644 --- a/docs/About/Uninstall-WinCNIPlugin.md +++ b/docs/About/Uninstall-WinCNIPlugin.md @@ -14,7 +14,7 @@ Uninstall Windows CNI plugins. ## SYNTAX ``` -Uninstall-WinCNIPlugin [[-Path] ] [-Force] [-WhatIf] [] +Uninstall-WinCNIPlugin [[-Path] ] [-Force] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -65,14 +65,31 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet isn't run. +Shows what would happen if the cmdlet runs. +The cmdlet is not run. ```yaml Type: SwitchParameter -Parameter Sets: Setup -Aliases: +Parameter Sets: (All) +Aliases: wi Required: False Position: Named @@ -81,6 +98,10 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + ## RELATED LINKS - [Get-WinCNILatestVersion](Get-WinCNILatestVersion.md) diff --git a/docs/command-reference.md b/docs/command-reference.md deleted file mode 100644 index 7ac3807..0000000 --- a/docs/command-reference.md +++ /dev/null @@ -1,409 +0,0 @@ -# Command Reference - -## Table of Contents - -- [General](#general) - - [Show-ContainerTools](#show-containertools) - - [Install-ContainerTools](#install-containertools) -- [Containerd](#containerd) - - [Get-ContainerdLatestVersion](#get-containerdlatestversion) - - [Install-Containerd](#install-containerd) - - [Register-ContainerdService](#register-containerdservice) - - [Start-ContainerdService](#start-containerdservice) - - [Stop-ContainerdService](#stop-containerdservice) - - [Uninstall-Containerd](#uninstall-containerd) -- [BuildKit](#buildkit) - - [Get-BuildkitLatestVersion](#get-buildkitlatestversion) - - [Install-BuildKit](#install-buildkit) - - [Register-BuildkitdService](#register-buildkitdservice) - - [Start-BuildkitdService](#start-buildkitdservice) - - [Stop-BuildkitdService](#stop-buildkitdservice) - - [Uninstall-BuildKit](#uninstall-buildkit) -- [nerdctl](#nerdctl) - - [Get-NerdctlLatestVersion](#get-nerdctllatestversion) - - [Install-Nerdctl](#install-nerdctl) - - [Uninstall-Nerdctl](#uninstall-nerdctl) -- [Container Networking](#container-networking) - - [Get-WinCNILatestVersion](#get-wincnilatestversion) - - [Install-WinCNIPlugin](#install-wincniplugin) - - [Initialize-NatNetwork](#initialize-natnetwork) - - [Uninstall-WinCNIPlugin](#uninstall-wincniplugin) - -### General - -#### Show-ContainerTools - -List container tools (Containerd, BuildKit, nerdctl) and shows if the tool is installed, the installed version and the latest available version. - -**Parameters** - -| Name | Type | Description | Default | -|------------|--------|-----------------------------|--------------------------------------------------------------------------------| -| Latest | Switch | Show latest release version. | False | -| ToolName | String | Tool to show the version of.| When not provided, it returns the version of containerd, buildkit, and nerdctl | - -**Output** - -| Name | Type | Description | -|-----------------|----------|----------------------------------------------------------------------| -| Tool | String | Name of the container tool. Either Containerd, Buildkit, or nerdctl. | -| Installed | Boolean | Specifies whether the tool is installed or not. | -| Version | String | Installed version. | -| LatestVersion | String | Latest available version. | -| Path | String | Path to the binary. | -| BuildctlPath | String | Path to the buildctl binary. | -| Daemon | String | containerd or buildkitd. | -| DaemonStatus | String | Status of the tool service. | - -#### Install-ContainerTools - -Downloads container tool (Containerd, BuildKit, nerdctl) asynchronously and installs them at the specified location - -**Parameters** - -| Name | Type | Description | Default | -| -------- | ------- | ------- | ------- | -| ContainerdVersion | String | Containerd version to install | Latest version | -| BuildKitVersion | String | BuildKit version to install | Latest version | -| nerdctlVersion | String | nerdctl version to install | Latest version | -| InstallPath | String | Path to install container tools | `$Env:ProgramFiles` | -| DownloadPath | String | Path to download container tools | `$HOME\Downloads` | -| RegisterServices | Switch | Register and Start Containerd and Buildkitd services and set up NAT network | | -| OSArchitecture | String | OS architecture. Accepts: 'amd64', '386', 'arm', 'arm64' | $env:PROCESSOR_ARCHITECTURE | -| Force | Switch | Force install the tools even if they already exists at the specified path | | -| Confirm | Switch | Prompts for confirmation before running the cmdlet. For more information, see the following articles: [about_Preference_Variables](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference) and [about_Functions_CmdletBindingAttribute](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact) | | -| WhatIf | Switch | Shows what would happen if the cmdlet runs. The cmdlet isn't run. | | - -**Output** - -None - -### Containerd - -#### Get-ContainerdLatestVersion - -Returns the latest Containerd version number. - -**Parameters** - -None - -**Output** - -String - -#### Install-Containerd - -Downloads Containerd files from [Containerd releases](https://github.com/containerd/containerd/releases) and installs them at the provided path. After the installation is complete, the downloaded files are deleted to save disk space. - -Once Containerd is installed and added to the environment path, we can get the path where it is installed using: - -```PowerShell -((Get-Command -Name containerd.exe).Source | Split-Path -Parent).TrimEnd("\bin") -``` - -**NOTE:** If Containerd already exists at the specified install path, it will be uninstalled and the specified version will be installed. - -**Parameters** - -| Name | Type | Description | Default | -| -------- | ------- | ------- | ------- | -| Version | String | Containerd version to install | Latest version | -| InstallPath | String | Path to install Containerd | `$Env:ProgramFiles\containerd` | -| DownloadPath | String | Path to download Containerd | `$HOME\Downloads` | -| Setup | Switch | Register and start Containerd Service once Containerd installation is done | | -| OSArchitecture | String | OS architecture. Accepts: 'amd64', '386', 'arm', 'arm64' | $env:PROCESSOR_ARCHITECTURE | -| Force | Switch | Installs Containerd even if the tool already exists at the specified path | | -| Confirm | Switch | Prompts for confirmation before running the cmdlet. For more information, see the following articles: [about_Preference_Variables](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference) and [about_Functions_CmdletBindingAttribute](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact) | | -| WhatIf | Switch | Shows what would happen if the cmdlet runs. The cmdlet isn't run. | | - -**Output** - -None - -#### Register-ContainerdService - -Create a default Containerd configuration file called `config.toml` at the Containerd path and registers the Containerd service. - -**Parameters** - -| Name | Type | Description | Default | -| -------- | ------- | ------- | ------- | -| ContainerdPath | String | Path where Containerd is installed | The Containerd path in the environment path variable or `$Env:ProgramFiles\containerd` | -| Start | Switch | Start Containerd service after registration is complete | | -| WhatIf | Switch | Shows what would happen if the cmdlet runs. The cmdlet isn't run. | | - -**Output** - -None - -#### Start-ContainerdService - -Starts Containerd service - -**Parameters** - -None - -**Output** - -None - -#### Stop-ContainerdService - -Stops Containerd service - -**Parameters** - -None - -**Output** - -None - -#### Uninstall-Containerd - -Does the following: - -1. Stops Containerd service -2. Unregisters Containerd service -3. Deletes Containerd directory -4. Removes Containerd from the environment path - -**Parameters** - -| Name | Type | Description | Default | -| -------- | ------- | ------- | ------- | -| Path | String | Path where Containerd is installed | The Containerd path in the environment path variable or `$Env:ProgramFiles\containerd` | -| Force | Switch | Bypass confirmation to uninstall Containerd | | -| WhatIf | Switch | Shows what would happen if the cmdlet runs. The cmdlet isn't run. | | - -**Output** - -None - -### BuildKit - -#### Get-BuildkitLatestVersion - -Returns the latest BuildKit version number. - -**Parameters** - -None - -**Output** - -String - -#### Install-BuildKit - -Downloads BuildKit files from [Containerd releases](https://github.com/moby/buildkit/releases) and installs them at the provided path. After the installation is complete, the downloaded files are deleted to save disk space. - -Once BuildKit is installed and added to the environment path, we can get the path where it is installed using: - -```PowerShell -((Get-Command -Name buildctl.exe).Source | Split-Path -Parent).TrimEnd("\bin") -``` - -**NOTE:** If BuildKit already exists at the specified install path, it will be uninstalled and the specified version will be installed. - -**Parameters** - -| Name | Type | Description | Default | -| -------- | ------- | ------- | ------- | -| Version | String | BuildKit version to install | Latest version | -|InstallPath | String | Path to install BuildKit | `$Env:ProgramFiles\BuildKit` | -|DownloadPath | String | Path to download BuildKit | $HOME\Downloads | -| Setup | Switch | Register and start buildkitd Service once Containerd installation is done | | -| OSArchitecture | String | OS architecture. Accepts: 'amd64', '386', 'arm', 'arm64' | $env:PROCESSOR_ARCHITECTURE | -| Force | Switch | Installs Buildkit even if the tool already exists at the specified path | | -| Confirm | Switch | Prompts for confirmation before running the cmdlet. For more information, see the following articles: [about_Preference_Variables](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference) and [about_Functions_CmdletBindingAttribute](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact) | | -| WhatIf | Switch | Shows what would happen if the cmdlet runs. The cmdlet isn't run. | | - -**Output** - -None - -#### Register-BuildkitdService - -Registers the buildkitd service with a prompt to either register with the Containerd CNI configurations (0-containerd-nat.conf) or not. - -**Parameters** - -| Name | Type | Description | Default | -| -------- | ------- | ------- | ------- | -| BuildkitPath | String | Path where BuildKit is installed | The BuildKit path in the environment path variable or `$Env:ProgramFiles\BuildKit` | -| WinCNIPath | String | Path to Windows CNI plugin | The Containerd path in the environment path variable or `$Env:ProgramFiles\Containerd` | -| Start | Switch | Start buildkitd service after registration is complete | | -| WhatIf | Switch | Shows what would happen if the cmdlet runs. The cmdlet isn't run. | | - -**Output** - -None - -#### Start-BuildkitdService - -Starts BuildKit service and waits for 30 seconds for the service to start. If the service does not start within this time, execution terminates with an error. - -**Parameters** - -None - -**Output** - -None - -#### Stop-BuildkitdService - -Stops BuildKit service -**Parameters** - -None - -**Output** - -None - -#### Uninstall-BuildKit - -Does the following: - -1. Stops buildkitd service -2. Unregisters buildkitd service -3. Deletes BuildKit directory -4. Removes BuildKit from the environment path - -**Parameters** - -| Name | Type | Description | Default | -| -------- | ------- | ------- | ------- | -| Path | String | Path where BuildKit is installed | The BuildKit path in the environment path variable or `$Env:ProgramFiles\BuildKit` | -| Force | Switch | Bypass confirmation to uninstall BuildKit | | -| WhatIf | Switch | Shows what would happen if the cmdlet runs. The cmdlet isn't run. | | - -**Output** - -None - -### nerdctl - -#### Get-NerdctlLatestVersion - -Returns the latest nerdctl version number. - -**Parameters** - -None - -**Output** - -String - -#### Install-Nerdctl - -Downloads Containerd files from [nerdctl releases](https://github.com/containerd/nerdctl/releases) and installs them at the provided path. After the installation is complete, the downloaded files are deleted to save disk space. - -**Parameters** - -| Name | Type | Description | Default | -| -------- | ------- | ------- | ------- | -| Version | String | nerdctl version to install | Latest version | -| InstallPath | String | Path to install nerdctl | $Env:ProgramFiles\nerdctl | -| DownloadPath | String | Path to download nerdctl | $HOME\Downloads | -| Dependencies | String[] | Specify the nerdctl dependencies (All, Containerd, Buildkit, WinCNIPlugin) to install. | | -| OSArchitecture | String | OS architecture. Accepts: 'amd64', '386', 'arm', 'arm64' | $env:PROCESSOR_ARCHITECTURE | -| Force | Switch | Installs nerdctl even if the tool already exists at the specified path | | -| Confirm | Switch | Prompts for confirmation before running the cmdlet. For more information, see the following articles: [about_Preference_Variables](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference) and [about_Functions_CmdletBindingAttribute](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact) | | -| WhatIf | Switch | Shows what would happen if the cmdlet runs. The cmdlet isn't run. | | - -**Output** - -None - -#### Uninstall-Nerdctl - -Deletes the nerdctl directory and removes it from the environment variables. - -**Parameters** - -| Name | Type | Description | Default | -| -------- | ------- | ------- | ------- | -| Path | String | Path where nerdctl is installed | The nerdctl path in the environment path variable or `$Env:ProgramFiles\BuildKit` | -| Force | Switch | Bypass confirmation to uninstall nerdctl | | -| WhatIf | Switch | Shows what would happen if the cmdlet runs. The cmdlet isn't run. | | - -**Output** - -None - -### Container Networking - -#### Get-WinCNILatestVersion - -Returns the latest Windows CNI version number. - -**Parameters** - -None - -**Output** - -String - -#### Install-WinCNIPlugin - -Downloads Windows CNI plugin from [windows-container-networking](https://github.com/microsoft/windows-container-networking/releases) and installs it in the specified location. - -**Parameters** - -| Name | Type | Description | Default | -| -------- | ------- | ------- | ------- | -| WinCNIVersion | String | Windows CNI version to install | Latest version | -| WinCNIPath | String | Location to install Windows CNI | Path where Containerd is installed or `$Env:ProgramFiles\Containerd`| -| OSArchitecture | String | OS architecture. Accepts: 'amd64', '386', 'arm', 'arm64' | $env:PROCESSOR_ARCHITECTURE | -| SourceRepo | String | OS architecture. Accepts: "microsoft/windows-container-networking", "containernetworking/plugins" | "microsoft/windows-container-networking" | -| Force | Switch | Installs Windows CNI plugins even if the tool already exists at the specified path | | -| Confirm | Switch | Prompts for confirmation before running the cmdlet. For more information, see the following articles: [about_Preference_Variables](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4#confirmpreference) and [about_Functions_CmdletBindingAttribute](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.4#confirmimpact) | | -| WhatIf | Switch | Shows what would happen if the cmdlet runs. The cmdlet isn't run. | | - -**Output** - -None - -#### Initialize-NatNetwork - -Initializes a NAT network. - -**NOTE**: This function installs the [HNS module](https://www.powershellgallery.com/packages/HNS/0.2.4). - -**Parameters** - -| Name | Type | Description | Default | -| -------- | ------- | ------- | ------- | -| NetworkName | String | Name of the network. If a network with a similar name exists, the function terminates with an error message | Default: `nat` | -| Gateway | String | Gateway IP address | Default gateway address | -| CIDR | Int | Size of the subnet mask | 16 | -| WinCNIVersion | String | Windows CNI version to use | Latest version | -| WinCNIPath | String | Absolute path to cni directory ~\cni. Not ~\cni\bin | Path where Containerd is installed or `$Env:ProgramFiles\Containerd\cni` | -| WhatIf | Switch | Shows what would happen if the cmdlet runs. The cmdlet isn't run. | | - -**Output** - -None - -#### Uninstall-WinCNIPlugin - -Uninstalls Windows CNI plugins. - -**Parameters** - -| Name | Type | Description | Default | -| -------- | ------- | ------- | ------- | -| Path | String | Path where Windows CNI plugins is installed | `$Env:ProgramFiles\containerd\cni` | -| Force | Switch | Bypass confirmation to uninstall Windows CNI plugins | | -| WhatIf | Switch | Shows what would happen if the cmdlet runs. The cmdlet isn't run. | | - -**Output** - -None