├── .github ├── CODEOWNERS ├── ISSUE_TEMPLATE │ ├── bug_report.md │ └── feature_request.md ├── pull_request_template.md └── workflows │ ├── ci-build.yaml │ ├── markdown-lint.yml │ └── sdl-compliance.yaml ├── .gitignore ├── .textlintrc.json ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── SECURITY.md ├── Tests ├── AllToolsUtilities.Tests.ps1 ├── BuildkitTools.Tests.ps1 ├── CommonToolUtilities.Tests.ps1 ├── ContainerNetworkTools.Tests.ps1 ├── ContainerdTools.Tests.ps1 ├── NerdctlTools.Tests.ps1 ├── TestData │ ├── MockClasses.psm1 │ ├── latestVersion.json │ ├── release-assets.json │ ├── release-tags.json │ └── test-schema.json └── UpdateEnvironmentPath.Tests.ps1 ├── assets └── child-object-permission.png ├── build ├── hacks │ ├── link-check-config.json │ └── release-notes-template.md └── scripts │ ├── generate-ref.ps1 │ ├── run-tests.ps1 │ ├── script-analyzer.ps1 │ └── update-ctkmanifest.ps1 ├── containers-toolkit ├── Private │ ├── CommonToolUtilities.psm1 │ ├── UpdateEnvironmentPath.psm1 │ └── schemas │ │ └── in-toto.sbom.schema.json ├── Public │ ├── AllToolsUtilities.psm1 │ ├── BuildkitTools.psm1 │ ├── ContainerNetworkTools.psm1 │ ├── ContainerdTools.psm1 │ └── NerdctlTools.psm1 ├── containers-toolkit.psd1 └── en-US │ ├── about_containers-toolkit.help.txt │ └── containers-toolkit-help.xml ├── docs ├── About │ ├── Get-BuildkitLatestVersion.md │ ├── Get-ContainerdLatestVersion.md │ ├── Get-NerdctlLatestVersion.md │ ├── Get-WinCNILatestVersion.md │ ├── Initialize-NatNetwork.md │ ├── Install-Buildkit.md │ ├── Install-ContainerTools.md │ ├── Install-Containerd.md │ ├── Install-Nerdctl.md │ ├── Install-WinCNIPlugin.md │ ├── Register-BuildkitdService.md │ ├── Register-ContainerdService.md │ ├── Show-ContainerTools.md │ ├── Start-BuildkitdService.md │ ├── Start-ContainerdService.md │ ├── Stop-BuildkitdService.md │ ├── Stop-ContainerdService.md │ ├── Uninstall-Buildkit.md │ ├── Uninstall-Containerd.md │ ├── Uninstall-Nerdctl.md │ └── Uninstall-WinCNIPlugin.md └── FAQs.md ├── package-lock.json └── package.json /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | # 2 | 3 | # Area: Documentation 4 | docs/ @tinamor 5 | 6 | # Area: Test 7 | *.Tests.ps1 @tinamor 8 | 9 | 10 | # Tools 11 | containers-toolkit//Public/BuildkitTools.psm1 @profnandaa @billywr @danielGithinji 12 | containers-toolkit/Public/ContainerdTools.psm1 @charitykathure 13 | containers-toolkit/Public/ContainerNetworkTools.psm1 @iankingori 14 | containers-toolkit/Public/NerdctlTools.psm1 @tinamor 15 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a report to help improve Containers Toolkit PowerShell module 4 | title: "[BUG] [CTK v1.0.0] Summary of the issue" 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Describe the bug** 11 | 12 | Please file a single issue per bug instead of enumerating multiple items. 13 | 14 | **To Reproduce** 15 | 16 | Detailed steps to reproduce the behavior: 17 | 1. 18 | 2. 19 | 3. ... 20 | 21 | The more information you can provide, the more likely someone will be successful at triaging and reproducing the issue and finding a fix. 22 | 23 | **Expected behavior** 24 | 25 | A clear and concise description of what you expected to happen. 26 | 27 | **Actual behavior** 28 | 29 | A clear and concise description of what you expected to happen. 30 | 31 | **Screenshots** 32 | 33 | If applicable, add screenshots to help explain your problem. 34 | 35 | **System information** 36 | 37 | - Windows build and Version 38 | - PowerShell 39 | 40 | ```PowerShell 41 | systeminfo | findstr /B /C:"OS Name" /C:"OS Version" /C:"System Type" 42 | ``` 43 | 44 | - PowerShell version 45 | - Package version for which the problem occurs 46 | - Container tool versions: 47 | - Containerd 48 | - Buildkit 49 | - Nerdctl 50 | - Win CNI plugin: 51 | - Plugin: [Windows Container Networking CNI](https://github.com/microsoft/windows-container-networking) or [CNI network plugins](https://github.com/containernetworking/plugins) 52 | - Version 53 | - For issues with extensions, the version of the IDE for which the problem occurs 54 | 55 | **Additional context** 56 | 57 | Add any other context about the problem here. 58 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea for Containers Toolkit PowerShell module 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Is your feature request related to a problem? Please describe.** 11 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] 12 | 13 | **Describe the solution you'd like** 14 | A clear and concise description of what you want to happen. 15 | 16 | **Describe alternatives you've considered** 17 | A clear and concise description of any alternative solutions or features you've considered. 18 | 19 | **Additional context** 20 | Add any other context or screenshots about the feature request here. 21 | -------------------------------------------------------------------------------- /.github/pull_request_template.md: -------------------------------------------------------------------------------- 1 | 2 | ## PR Description 3 | 4 | _What does this PR achieve or fix?_ 5 | 6 | - _Related isuue/discussion(s): Link to the issue or discussion that this PR addresses._ 7 | - _Background information: From the reviewer's perspective, what context do they need to understand this PR?_ 8 | _Additional information: What does this PR achieve/fix._ 9 | 10 | ### TODOs Not Included in This PR 11 | 12 | _What issues will/should be addressed in follow-up PRs? Link any existing related issues._ 13 | 14 | ### Testing Information 15 | 16 | _How to test the changes_ 17 | 18 | ### Relevant Links 19 | 20 | _Any links from your research that help explain the changes_ 21 | 22 | ## Checklist 23 | 24 | As part of our commitment to engineering excellence, **before** submitting this PR, please ensure: 25 | 26 | - [ ] You have tested this code in both Desktop and Server environments, as well as AMD64 and ARM64 environments (**functional testing**). 27 | - [ ] You have added **unit tests** for new code. 28 | - [ ] You have added or updated documentation in the [cmdlet docs](../docs/About/), [command-reference.md](../docs/command-reference.md), and the [modules help files](../containers-toolkit/en-US/containers-toolkit-help.xml). 29 | - [ ] You have reviewed the PR/code best practices defined in the [CONTRIBUTING.md](../CONTRIBUTING.md). 30 | 31 | In addition, **after** this PR has been reviewed, please ensure: 32 | 33 | - [ ] If you make changes while addressing review comments, you test the _final_ version again in both AMD64 and ARM64 environments. 34 | - [ ] You validate that your changes have not introduced any regressions. 35 | -------------------------------------------------------------------------------- /.github/workflows/ci-build.yaml: -------------------------------------------------------------------------------- 1 | ########################################################################### 2 | # # 3 | # Copyright (c) Microsoft Corporation. All rights reserved. # 4 | # # 5 | # This code is licensed under the MIT License (MIT). # 6 | # # 7 | ########################################################################### 8 | 9 | name: CI Build 10 | 11 | on: 12 | workflow_dispatch: 13 | inputs: 14 | runner: 15 | description: "Windows runner image" 16 | required: false 17 | default: windows-2022 18 | type: choice 19 | options: 20 | - windows-latest 21 | - windows-2022 22 | - windows-2019 23 | 24 | pull_request: 25 | branches: ["main", "releases/**"] 26 | paths-ignore: 27 | - "docs/**" 28 | - "*.md" 29 | - "en-US/**" 30 | - "package.json" 31 | - "package-lock.json" 32 | 33 | env: 34 | MODULE_DIR: .\Containers-Toolkit 35 | BUILD_SCRIPTS_DIR: .\build\scripts 36 | PESTER_RESULTS_DIR: .\TestResults 37 | MODULE_ARTIFACT: CTK.Module.Scripts 38 | REPO_ARTIFACT: CTK.Scripts 39 | 40 | jobs: 41 | lint: 42 | runs-on: ${{ github.event.inputs.RUNNER || 'windows-2022' }} 43 | steps: 44 | - name: Checkout code 45 | uses: actions/checkout@v4 46 | 47 | # FIXME: Fix cache not working 48 | - name: Setup PowerShell module cache 49 | id: cacher 50 | uses: actions/cache@v3 51 | with: 52 | path: "C:\\program files\\powershell\\7\\Modules" 53 | key: ${{ runner.os }}-CTK 54 | 55 | - name: Install required PowerShell modules 56 | if: steps.cacher.outputs.cache-hit != 'true' 57 | shell: pwsh 58 | run: | 59 | Set-PSRepository PSGallery -InstallationPolicy Trusted 60 | $ModuleName = 'PSScriptAnalyzer' 61 | if (-not (Get-Module -ListAvailable -Name $ModuleName)) { 62 | Write-Output "Modules to install: '$ModuleName'" 63 | Install-Module $ModuleName -ErrorAction Stop -AllowClobber -SkipPublisherCheck -Force 64 | } 65 | 66 | - name: Run code analysis with PSScriptAnalyzer 67 | id: code_analysis 68 | shell: pwsh 69 | run: | 70 | ${{ env.BUILD_SCRIPTS_DIR }}\script-analyzer.ps1 | Out-File -FilePath lintsummary.md -Encoding utf8 -Force 71 | cat lintsummary.md >> $env:GITHUB_STEP_SUMMARY 72 | 73 | $fileExists = Test-Path ./psscriptanalysis.xml 74 | echo "LINTSUMMARY_EXISTS=$fileExists" >> $env:GITHUB_OUTPUT 75 | 76 | - name: Publish PSScriptAnalyzer results file 77 | if: steps.code_analysis.outputs.LINTSUMMARY_EXISTS == 'true' 78 | uses: actions/upload-artifact@v4 79 | with: 80 | name: PSScriptAnalyzer.Results 81 | path: psscriptanalysis.xml 82 | if-no-files-found: error 83 | overwrite: true 84 | 85 | pester: 86 | # TODO: Add Windows ARM64 support 87 | runs-on: ${{ github.event.inputs.RUNNER || 'windows-2022' }} 88 | steps: 89 | - name: Checkout code 90 | uses: actions/checkout@v4 91 | 92 | # FIXME: Fix cache not working 93 | - name: Setup PowerShell module cache 94 | id: cacher 95 | uses: actions/cache@v3 96 | with: 97 | path: "C:\\program files\\powershell\\7\\Modules" 98 | key: ${{ runner.os }}-CTK 99 | 100 | - name: Install required PowerShell modules 101 | if: steps.cacher.outputs.cache-hit != 'true' 102 | shell: pwsh 103 | run: | 104 | Set-PSRepository PSGallery -InstallationPolicy Trusted 105 | $requiredModules = @('Pester') 106 | $missingModules = $requiredModules | Where-Object { -not (Get-Module -ListAvailable -Name $_) } 107 | 108 | if ($missingModules) { 109 | Write-Output "Modules to install: $($missingModules -join ', ')" 110 | Install-Module $missingModules -ErrorAction Stop -AllowClobber -SkipPublisherCheck -Force 111 | } 112 | 113 | - name: Run Pester tests 114 | shell: pwsh 115 | run: | 116 | $ErrorActionPreference = 'Continue' 117 | ${{ env.BUILD_SCRIPTS_DIR }}\run-tests.ps1 118 | 119 | # Get failed tests 120 | Write-Host "Getting failed tests from ${{ env.PESTER_RESULTS_DIR }}\Test-Results.xml" 121 | $results = (Select-Xml -Path "${{ env.PESTER_RESULTS_DIR }}\Test-Results.xml" -XPath "//test-case").Node 122 | $failedTests = $results | Where-Object { ($_.success -eq $false) -and ($_.result -ne "Ignored") } 123 | if ($failedTests.Count -gt 0) { 124 | $failedTestsName = ($failedTests | ForEach-Object { $_.name }) -join "`n" 125 | Write-Host "Failed tests:`n$failedTestsName" -Foregroundcolor Red 126 | echo "$failedTestsName" >> $env:GITHUB_STEP_SUMMARY 127 | } 128 | - name: Publish Pester results 129 | uses: actions/upload-artifact@v4 130 | with: 131 | name: CTK.Pester.Results 132 | path: ${{ env.PESTER_RESULTS_DIR }}\Test-Results.xml 133 | if-no-files-found: error 134 | overwrite: true 135 | 136 | - name: Publish code coverage results 137 | uses: actions/upload-artifact@v4 138 | with: 139 | name: CTK.Coverage.Summary 140 | path: ${{ env.PESTER_RESULTS_DIR }}\coverage.xml 141 | if-no-files-found: error 142 | overwrite: true 143 | 144 | test-coverage: 145 | needs: pester 146 | runs-on: ubuntu-latest 147 | continue-on-error: true 148 | steps: 149 | - name: Download coverage results artifact 150 | uses: actions/download-artifact@v4 151 | with: 152 | name: CTK.Coverage.Summary 153 | 154 | - name: Setup .NET Core # Required to execute ReportGenerator 155 | uses: actions/setup-dotnet@v3 156 | with: 157 | dotnet-version: 8.x 158 | dotnet-quality: "ga" 159 | 160 | - name: ReportGenerator 161 | uses: danielpalme/ReportGenerator-GitHub-Action@5.2.4 162 | with: 163 | reports: coverage.xml 164 | targetdir: coveragereport 165 | reporttypes: HtmlInline;MarkdownSummaryGithub;Badges 166 | historydir: coveragehistory 167 | 168 | - name: Upload coverage report artifact 169 | uses: actions/upload-artifact@v4 170 | with: 171 | name: coveragereport # Artifact name 172 | path: coveragereport # Directory containing files to upload 173 | 174 | - name: Post results 175 | run: | 176 | cat coveragereport/SummaryGithub.md >> $env:GITHUB_STEP_SUMMARY -------------------------------------------------------------------------------- /.github/workflows/markdown-lint.yml: -------------------------------------------------------------------------------- 1 | ########################################################################### 2 | # # 3 | # Copyright (c) Microsoft Corporation. All rights reserved. # 4 | # # 5 | # This code is licensed under the MIT License (MIT). # 6 | # # 7 | ########################################################################### 8 | 9 | name: Markdown Lint 10 | 11 | on: 12 | pull_request: 13 | branches: 14 | - main 15 | - "releases/**" 16 | paths: 17 | - "docs/**" 18 | - "README.md" 19 | - "en-US/**" 20 | - "**/markdown-lint.yml" 21 | 22 | permissions: 23 | contents: read 24 | 25 | jobs: 26 | markdown-check: 27 | runs-on: windows-latest 28 | steps: 29 | - uses: actions/checkout@v4 30 | 31 | - uses: actions/setup-node@v4 32 | with: 33 | node-version: '18' 34 | check-latest: true 35 | 36 | - name: Install npm dependencies 37 | run: npm install markdown-link-check textlint textlint-rule-spelling dictionary-en textlint-filter-rule-comments --save-dev 38 | 39 | - name: Markdown link check 40 | id: link-check 41 | continue-on-error: true 42 | shell: pwsh 43 | run: | 44 | $mlc_error_file = "link-errors.txt" 45 | Remove-Item -Path $mlc_error_file -Force -ErrorAction SilentlyContinue 46 | 47 | # Get markdown files to validate the links 48 | # We split the two commands because `-Recurse` check for "README.md" in the entire directory tree, 49 | # which includes node_modules, and we want to exclude that. 50 | $mdFiles = (Get-ChildItem -Path ".\docs\" -Recurse -Filter "*.md") + (Get-ChildItem -Path ".\README.md" -Filter "*.md") 51 | 52 | # Run markdown-link-check on all markdown files in the repository 53 | $CONFIG_FILE = ".\build\hacks\link-check-config.json" 54 | $mdFiles | ForEach-Object { 55 | Write-Host "Validating links in $($_.FullName)" -ForegroundColor Cyan 56 | npx markdown-link-check $_.FullName -q -c "$CONFIG_FILE" 2>>$mlc_error_file 57 | } 58 | 59 | # Check if the error file exists 60 | if (-not (Test-Path "$mlc_error_file")) { 61 | echo "Markdown link check file not found" >> $env:GITHUB_OUTPUT 62 | exit 0 63 | } 64 | 65 | # Check if the error file file contains errors 66 | $hasErrors = Select-String -Path "$mlc_error_file" -Pattern "ERROR: " -Quiet 67 | 68 | # No errors found 69 | if (-not $hasErrors) { 70 | echo ":white_check_mark: [Markdown Link Check] All links are valid." >> $env:GITHUB_STEP_SUMMARY 71 | exit 0 72 | } 73 | 74 | # Errors found 75 | $errorMessage = "Broken links found." 76 | echo ":exclamation: [Markdown Link Check] $errorMessage" >> $env:GITHUB_STEP_SUMMARY 77 | echo $((Get-Content $mlc_error_file -Raw) -replace "`r", "" -replace "`n", "`n`t") >> $env:GITHUB_STEP_SUMMARY 78 | 79 | throw "$errorMessage" 80 | 81 | - name: Markdown spell check 82 | id: spell-check 83 | continue-on-error: true 84 | shell: pwsh 85 | run: | 86 | # Run spell check on all markdown files in the repository 87 | $sc_error_file = "sc-errors.txt" 88 | Remove-Item -Path $sc_error_file -Force -ErrorAction SilentlyContinue 89 | 90 | # Run textlint on markdown files in the repository 91 | npx textlint "README.md" "docs/**/*.md" >> $sc_error_file 92 | 93 | if (-not (Test-Path "$sc_error_file")) { 94 | exit 0 95 | } 96 | 97 | # Check if the error file file contains errors. If the file is empty, it means no errors were found. 98 | $isFileEmpty = ([string]::IsNullOrWhiteSpace((Get-Content -Path $sc_error_file))) 99 | 100 | # No errors found 101 | if ($isFileEmpty) { 102 | echo ":white_check_mark: [Markdown Spell Check] No spelling errors found." >> $env:GITHUB_STEP_SUMMARY 103 | exit 0 104 | } 105 | 106 | # Errors found 107 | $errorMessage = "Spelling errors found." 108 | echo ":exclamation: [Markdown Spell Check] $errorMessage">> $env:GITHUB_STEP_SUMMARY 109 | echo $((Get-Content $sc_error_file -Raw) -replace "`r", "" -replace "`n", "`n`t") >> $env:GITHUB_STEP_SUMMARY 110 | throw "$errorMessage" 111 | 112 | - name: Check if validation failed 113 | if: always() 114 | shell: bash 115 | run: | 116 | link_status="${{ steps.link-check.outcome }}" 117 | spell_status="${{ steps.spell-check.outcome }}" 118 | 119 | if [[ "$link_status" == "success" && "$spell_status" == "success" ]]; then 120 | echo ":white_check_mark: Markdown validation passed." >> "$GITHUB_STEP_SUMMARY" 121 | exit 0 122 | fi 123 | 124 | error_message="Markdown validation failed" 125 | echo ":x: $error_message. Please check the output for more information." >> "$GITHUB_STEP_SUMMARY" 126 | exit 1 -------------------------------------------------------------------------------- /.github/workflows/sdl-compliance.yaml: -------------------------------------------------------------------------------- 1 | ########################################################################### 2 | # # 3 | # Copyright (c) Microsoft Corporation. All rights reserved. # 4 | # # 5 | # This code is licensed under the MIT License (MIT). # 6 | # # 7 | ########################################################################### 8 | 9 | name: SDL Compliance 10 | 11 | on: 12 | push: 13 | branches: ["main", "releases/**"] 14 | pull_request: 15 | branches: ["main", "releases/**"] 16 | 17 | jobs: 18 | devskim: 19 | name: DevSkim 20 | runs-on: ubuntu-latest 21 | permissions: 22 | actions: read 23 | contents: read 24 | security-events: write 25 | steps: 26 | - name: Checkout code 27 | uses: actions/checkout@v4 28 | 29 | - name: Run DevSkim scanner 30 | uses: microsoft/DevSkim-Action@v1 31 | with: 32 | # Relative path in $GITHUB_WORKSPACE for DevSkim to Scan 33 | directory-to-scan: containers-toolkit/ 34 | ignore-globs: "en-US/**" 35 | 36 | - name: Upload DevSkim scan results to GitHub Security tab 37 | uses: github/codeql-action/upload-sarif@v3 38 | with: 39 | sarif_file: devskim-results.sarif 40 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # IDEs and editors 2 | /.vs 3 | /.vscode 4 | 5 | # Tests 6 | /TestResults 7 | 8 | # Node modules 9 | /node_modules -------------------------------------------------------------------------------- /.textlintrc.json: -------------------------------------------------------------------------------- 1 | { 2 | "plugins": {}, 3 | "filters": { 4 | "comments": true 5 | }, 6 | "rules": { 7 | "spelling": { 8 | "language": "en", 9 | "skipPatterns": [ 10 | "/[0-9]+/g", // numbers 11 | "/\\bhttp(s)?:\\/\\/[^\\s)>]+/", // URL 12 | // "/\\b[a-z\\d]{7,40}\\b/", // commit hash 13 | "/\\([^)]+?\\)/", // inside parentheses 14 | // "/\"[^\"]+?\"/", // inside quotation marks 15 | // "/`[^`]+?`/", // inside backticks 16 | "/\\b(?:[A-Z]){2,}\\b/g", // acronyms 17 | "/\\b(?:[a-zA-Z]+-[a-zA-Z]+)\\b/g", // hyphenated words/ function names 18 | // "/\\b\\S*\\.\\S{2,4}/g", // filenames 19 | "/\\$[\\w]+(:\\w)?/g", // PowerShell variables 20 | "/-\\w+\\b/g", // FIXME: PowerShell Cmdlets/function parameter names 21 | "/\\b\\w+[./]\\w+\\b/g", // paths // FIXME: (Note: Does not work for \ in paths) 22 | "about_CommonParameters", 23 | "about_Preference_Variables", 24 | "CIDR", 25 | "Containers[\\s\\.\\-]ToolKit/gi", 26 | "CommonParameters", 27 | "/Cmdlet/gi", 28 | "cni", 29 | "/Containerd/gi", 30 | "/buildctl/gi", 31 | "/BuildctlPath/gi", 32 | "/BuildKit/gi", 33 | "/buildkitd/gi", 34 | "/DaemonStatus/gi", 35 | "/H(ost)?N(etworking)?S(ervice)?/g", 36 | "/Hyper[\\s-]?V/g", 37 | "/moby/gi", 38 | "/nat/gi", 39 | "NatNetwork", 40 | "nerdctl", 41 | "PowerShell", 42 | "/PSCustomObject/gi", 43 | "subnet", 44 | "/uninstall.*/gi", 45 | "/unregisters/gi", 46 | "WinCNIPlugin", 47 | "ToolName", 48 | "DownloadPath", 49 | "InstallPath", 50 | "LatestVersion", 51 | "NetworkName", 52 | "OSArchitecture", 53 | "RegisterServices", 54 | "SourceRepo", 55 | "WhatIf", 56 | "WinCNIPath", 57 | "WinCNIVersion" 58 | ] 59 | } 60 | } 61 | } -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | ## 1.0.0 2 | 3 | * Initial release 4 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Microsoft Open Source Code of Conduct 2 | 3 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). 4 | 5 | Resources: 6 | 7 | - [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) 8 | - [Microsoft Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) 9 | - Contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with questions or concerns 10 | - Employees can reach out at [aka.ms/opensource/moderation-support](https://aka.ms/opensource/moderation-support) 11 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) Microsoft Corporation. 2 | 3 | MIT License 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # CONTAINERS TOOLKIT POWERSHELL MODULE 2 | 3 | [![CI Build][ci-build-image]][ci-build-site] 4 | [![DevSkim][devskim-image]][devskim-site] 5 | [![cf-image][]][cf-site] 6 | 7 | [ci-build-image]: https://github.com/microsoft/containers-toolkit/actions/workflows/ci-build.yaml/badge.svg 8 | [ci-build-site]: https://github.com/microsoft/containers-toolkit/actions/workflows/ci-build.yaml 9 | [devskim-image]: https://github.com/microsoft/containers-toolkit/actions/workflows/sdl-compliance.yaml/badge.svg 10 | [devskim-site]: https://github.com/microsoft/containers-toolkit/actions/workflows/sdl-compliance.yaml 11 | [cf-image]: https://www.codefactor.io/repository/github/microsoft/containers-toolkit/badge/main 12 | [cf-site]: https://www.codefactor.io/repository/github/microsoft/containers-toolkit/overview/main 13 | 14 | ## Table of contents 15 | 16 | 1. [Introduction](#introduction) 17 | 1. [Prerequisites](#prerequisites) 18 | 1. [Installation and Setup](#installation-and-setup) 19 | 1. [Usage](#usage) 20 | 1. [Important Notes](#important-notes) 21 | 1. [FAQs](#faqs) 22 | 1. [Contribution](#contribution) 23 | 24 | ## Introduction 25 | 26 | Containers-Toolkit is a Windows PowerShell module for downloading, installing, and configuring Containerd, Buildkit, nerdctl, and Windows CNI plugins for container networks. It also allows you to get a list of the container tools and their installation statuses. 27 | 28 | Configurations done with these functions are default configurations that allow you to get started with interacting with the tools. Further configurations may be necessary. 29 | You can find documentation for these functions here: [Containers-Toolkit Documentation](https://github.com/microsoft/containers-toolkit/tree/main/docs/command-reference.md) 30 | 31 | ## Prerequisites 32 | 33 | 1. PowerShell: Minimum Version 7 34 | 35 | 1. `HNS` module 36 | 37 | To install the HNS module, follow the [instructions here](./docs/FAQs.md#2-new-hnsnetwork-command-does-not-exist) 38 | 39 | **Reference:** 40 | - [HostNetworkingService](https://docs.microsoft.com/en-us/powershell/module/hostnetworkingservice/?view=windowsserver2022-ps) 41 | - [Container Network Management with Host Network Service (HNS)](https://learn.microsoft.com/en-us/virtualization/windowscontainers/container-networking/architecture#container-network-management-with-host-network-service) 42 | 43 | ## Installation and Setup 44 | 45 | ### Install Containers-Toolkit module from PowerShell Gallery 46 | 47 | > COMING SOON: We are currently working on publishing this module to PS Gallery to make it easier to import the module 48 | 49 | ### Download signed source files 50 | 51 | > Coming soon 52 | 53 | ### Downloading the source code from Containers-Toolkit repository 54 | 55 | To use the module, fork/clone the repository to your local machine and [setup your development environment](./CONTRIBUTING.md#setup-development-environment) 56 | 57 | ## Usage 58 | 59 | ### Get the module details 60 | 61 | ```PowerShell 62 | Get-Help containers-toolkit 63 | ``` 64 | 65 | ```PowerShell 66 | Get-Module -Name containers-toolkit -ListAvailable 67 | ``` 68 | 69 | ### Command reference 70 | 71 | 1. List of all available commands can be found in the [Command reference](./docs/command-reference.md) section 72 | 1. Detailed command reference for each cmdlet can be found in the [About](./docs/About/) section 73 | 74 | #### List of available commands 75 | 76 | ```PowerShell 77 | Get-Command -Module containers-toolkit 78 | ``` 79 | 80 | ### Examples 81 | 82 | 1. Get help for Install-Containerd command 83 | 84 | ```PowerShell 85 | Get-Help Install-Containerd 86 | ``` 87 | 88 | 2. List container tools (Containerd, BuildKit, and nerdctl) install status 89 | 90 | ```PowerShell 91 | Show-ContainerTools 92 | ``` 93 | 94 | 3. Installs Containerd version 1.7.7 at 'C:\Test\Path\containerd' and adds 'C:\Test\Path\containerd' in the environment path. 95 | 96 | ```powershell 97 | Install-Containerd -Version "1.7.7" -InstallPath 'C:\Test\Path\Containerd' 98 | ``` 99 | 100 | ## Important Notes 101 | 102 | 1. Requires elevated PowerShell to run some commands. 103 | 104 | 1. To use these tools (Containerd, BuildKit, and nerdctl), ensure that Containers and HyperV Windows features are enabled. 105 | 106 | To get the features to enable, use: 107 | 108 | ```PowerShell 109 | Get-WindowsOptionalFeature -Online | ` 110 | Where-Object { $_.FeatureName -like 'containers' -or $_.FeatureName -match "Microsoft-Hyper-V(-All)?$" } | ` 111 | Select-Object FeatureName, Possible, State, RestartNeeded 112 | ``` 113 | 114 | To enable a feature: 115 | 116 | ```PowerShell 117 | Enable-WindowsOptionalFeature -Online -FeatureName '' -All -NoRestart 118 | ``` 119 | 120 | 1. Requires PowerShell modules [HNS](https://raw.githubusercontent.com/microsoft/SDN/master/Kubernetes/windows/hns.v2.psm1) 121 | 122 | ## FAQs 123 | 124 | Please visit the [FAQs.md](./docs/FAQs.md) to see the how to resolve common issues. 125 | 126 | ## Contribution 127 | 128 | Please look into the [Contribution Guide](./CONTRIBUTING.md) to know how to develop and contribute. 129 | 130 | ## Legal and Licensing 131 | 132 | PowerShell is licensed under the [MIT license](./LICENSE). 133 | 134 | ## Code of Conduct 135 | 136 | Please see our [Code of Conduct](./CODE_OF_CONDUCT.md) before participating in this project. 137 | 138 | ## Security Policy 139 | 140 | For any security issues, please see our [Security Policy](./SECURITY.md). 141 | 142 | ## Attributions 143 | 144 | This project builds on the work of others to create a PowerShell module. 145 | 146 | Credits (in alphabetic order): 147 | 148 | 149 | 150 | | Author/Repository | Link | 151 | |------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 152 | | Anthony Nandaa (@profnandaa) | [cni-setup-legacy.ps1](https://gist.github.com/profnandaa/33d65d85964181a42539bfd0b4f9561a) | 153 | | Gabriel Samfira (@gabriel-samfira) | [setup_buildkitd_on_windows.ps1](https://gist.github.com/gabriel-samfira/6e56238ad11c24f490ac109bdd378471) | 154 | | James Sturtevant (@jsturtevant) | [Windows Containers on Windows 10 without Docker (using Containerd)](https://www.jamessturtevant.com/posts/Windows-Containers-on-Windows-10-without-Docker-using-Containerd/) | 155 | | kubernetes-sigs/sig-windows-tools | [Install-Containerd.ps1](https://github.com/kubernetes-sigs/sig-windows-tools/blob/master/hostprocess/Install-Containerd.ps1) | 156 | | Marat Radchenko (@slonopotamus) | [Stevedore](https://github.com/slonopotamus/stevedore) | 157 | | Markus Lippert (@lippertmarkus) | [containerd-installer](https://github.com/lippertmarkus/containerd-installer) | 158 | | microsoft/Windows-Containers | [install-containerd-runtime.ps1](https://github.com/microsoft/Windows-Containers/blob/Main/helpful_tools/Install-ContainerdRuntime/install-containerd-runtime.ps1) | 159 | | Mirantis | [Install MCR on Windows Servers](https://docs.mirantis.com/mcr/20.10/install/mcr-windows.html) | 160 | 161 | 162 | 163 | ## Container tools installed with this module 164 | 165 | - [Containerd](https://github.com/containerd/containerd) 166 | - [BuildKit](https://github.com/moby/buildkit) 167 | - [nerdctl](https://github.com/containerd/nerdctl) 168 | - [Container networking plugins for Windows containers](https://github.com/microsoft/windows-container-networking) 169 | - [Container Network Interface - networking for Linux containers](https://github.com/containernetworking/cni) 170 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Security 4 | 5 | Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet) and [Xamarin](https://github.com/xamarin). 6 | 7 | If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/security.md/definition), please report it to us as described below. 8 | 9 | ## Reporting Security Issues 10 | 11 | **Please do not report security vulnerabilities through public GitHub issues.** 12 | 13 | Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/security.md/msrc/create-report). 14 | 15 | If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/security.md/msrc/pgp). 16 | 17 | You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc). 18 | 19 | Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: 20 | 21 | * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) 22 | * Full paths of source file(s) related to the manifestation of the issue 23 | * The location of the affected source code (tag/branch/commit or direct URL) 24 | * Any special configuration required to reproduce the issue 25 | * Step-by-step instructions to reproduce the issue 26 | * Proof-of-concept or exploit code (if possible) 27 | * Impact of the issue, including how an attacker might exploit the issue 28 | 29 | This information will help us triage your report more quickly. 30 | 31 | If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/security.md/msrc/bounty) page for more details about our active programs. 32 | 33 | ## Preferred Languages 34 | 35 | We prefer all communications to be in English. 36 | 37 | ## Policy 38 | 39 | Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/security.md/cvd). 40 | 41 | 42 | -------------------------------------------------------------------------------- /Tests/AllToolsUtilities.Tests.ps1: -------------------------------------------------------------------------------- 1 | ########################################################################### 2 | # # 3 | # Copyright (c) Microsoft Corporation. All rights reserved. # 4 | # # 5 | # This code is licensed under the MIT License (MIT). # 6 | # # 7 | ########################################################################### 8 | 9 | 10 | Describe "AllToolsUtilities.psm1" { 11 | BeforeAll { 12 | $RootPath = Split-Path -Parent $PSScriptRoot 13 | $ModuleParentPath = Join-Path -Path $RootPath -ChildPath 'Containers-Toolkit' 14 | Import-Module -Name "$ModuleParentPath\Private\CommonToolUtilities.psm1" -Force 15 | Import-Module -Name "$ModuleParentPath\Public\ContainerdTools.psm1" -Force 16 | Import-Module -Name "$ModuleParentPath\Public\BuildkitTools.psm1" -Force 17 | Import-Module -Name "$ModuleParentPath\Public\NerdctlTools.psm1" -Force 18 | Import-Module -Name "$ModuleParentPath\Public\ContainerNetworkTools.psm1" -Force 19 | Import-Module -Name "$ModuleParentPath\Public\AllToolsUtilities.psm1" -Force 20 | } 21 | 22 | AfterAll { 23 | Remove-Module -Name "$ModuleParentPath\Private\CommonToolUtilities.psm1" -Force -ErrorAction Ignore 24 | Remove-Module -Name "$ModuleParentPath\Public\AllToolsUtilities.psm1" -Force -ErrorAction Ignore 25 | Remove-Module -Name "$ModuleParentPath\Public\ContainerdTools.psm1" -Force -ErrorAction Ignore 26 | Remove-Module -Name "$ModuleParentPath\Public\BuildkitTools.psm1" -Force -ErrorAction Ignore 27 | Remove-Module -Name "$ModuleParentPath\Public\NerdctlTools.psm1" -Force -ErrorAction Ignore 28 | Remove-Module -Name "$ModuleParentPath\Public\ContainerNetworkTools.psm1" -Force -ErrorAction Ignore 29 | } 30 | 31 | Context "Show-ContainerTools" -Tag "Show-ContainerTools" { 32 | BeforeAll { 33 | # Mock get version 34 | $mockConfigStdOut = New-MockObject -Type 'System.IO.StreamReader' -Methods @{ ReadToEnd = { return "tool version v1.0.1" } } 35 | $mockConfigProcess = New-MockObject -Type 'System.Diagnostics.Process' -Properties @{ 36 | ExitCode = 0 37 | StandardOutput = $mockConfigStdOut 38 | } 39 | Mock Invoke-ExecutableCommand -ModuleName "AllToolsUtilities" ` 40 | -ParameterFilter { $Arguments -eq "--version" } ` 41 | -MockWith { return $mockConfigProcess } 42 | } 43 | 44 | It "Should get containerd version" { 45 | $executablePath = "TestDrive:\Program Files\Containerd\bin\containerd.exe" 46 | Mock Get-Command -ModuleName 'AllToolsUtilities' -MockWith { @{ Name = 'containerd.exe'; Source = $executablePath } } 47 | Mock Get-Service -ModuleName 'AllToolsUtilities' 48 | 49 | $containerdVersion = Show-ContainerTools -ToolName 'containerd' 50 | 51 | # Check the output 52 | $expectedOutput = [PSCustomObject]@{ 53 | Tool = 'containerd' 54 | Path = $executablePath 55 | Installed = $true 56 | Version = 'v1.0.1' 57 | Daemon = 'containerd' 58 | DaemonStatus = 'Unregistered' 59 | } 60 | # $containerdVersion | Should -Be $expectedOutput 61 | # HACK: Should -Be does not work with PSCustomObject in PSv5. 62 | # However PSv6 has support for this. To be investigated further. 63 | foreach ($key in $expectedOutput.Keys) { 64 | $expectedValue = $expectedOutput[$key] 65 | $actualValue = $containerdVersion.$key 66 | $actualValue | Should -Be $expectedValue 67 | } 68 | 69 | # Check the invocation 70 | Should -Invoke Get-Command -ModuleName 'AllToolsUtilities' ` 71 | -Times 1 -Exactly -Scope It -ParameterFilter { $Name -eq 'containerd.exe' } 72 | } 73 | 74 | It "Should get buildkit version" { 75 | $executablePath = "TestDrive:\Program Files\Buildkit\bin\buildkitd.exe" 76 | $buildctlPath = "TestDrive:\Program Files\Buildkit\bin\buildctl.exe" 77 | 78 | Mock Get-Service -ModuleName 'AllToolsUtilities' -MockWith { @{ Status = "Running" } } 79 | Mock Get-Command -ModuleName 'AllToolsUtilities' -MockWith { @( 80 | @{ Name = 'buildkitd.exe'; Source = $executablePath } 81 | @{ Name = 'buildctl.exe'; Source = $buildctlPath } 82 | ) } 83 | 84 | $buildkitVersion = Show-ContainerTools -ToolName 'buildkit' 85 | 86 | # Check the output 87 | $expectedOutput = [PSCustomObject]@{ 88 | Tool = 'buildkit' 89 | Path = $executablePath 90 | Installed = $true 91 | Version = 'v1.0.1' 92 | Daemon = 'buildkitd' 93 | DaemonStatus = 'Running' 94 | BuildctlPath = $buildctlPath 95 | } 96 | foreach ($key in $expectedOutput.Keys) { 97 | $expectedValue = $expectedOutput[$key] 98 | $actualValue = $buildkitVersion.$key 99 | $actualValue | Should -Be $expectedValue 100 | } 101 | 102 | # Check the invocation 103 | Should -Invoke Get-Command -ModuleName 'AllToolsUtilities' ` 104 | -Times 1 -Exactly -Scope It -ParameterFilter { $Name -eq "build*.exe" } 105 | } 106 | 107 | It "Should return basic info if the tool is not installed" { 108 | Mock Get-Command -ModuleName 'AllToolsUtilities' 109 | 110 | $toolInfo = Show-ContainerTools 111 | 112 | # Check the output 113 | $expectedOutput = @( 114 | [PSCustomObject]@{ Tool = 'containerd'; Installed = $false; Daemon = 'containerd'; DaemonStatus = 'Unregistered' } 115 | [PSCustomObject]@{ Tool = 'buildkit'; Installed = $false; Daemon = 'buildkitd'; DaemonStatus = 'Unregistered' } 116 | [PSCustomObject]@{ Tool = 'nerdctl'; Installed = $false } 117 | ) 118 | $expectedOutput | ForEach-Object { 119 | $tool = $_.Tool 120 | $actualOutput = $toolInfo | Where-Object { $_.Tool -eq $tool } 121 | foreach ($key in $_.Keys) { 122 | $expectedValue = $_[$key] 123 | $actualValue = $actualOutput.$key 124 | $actualValue | Should -Be $expectedValue 125 | } 126 | } 127 | } 128 | 129 | It "Should return latest version if Latest flag is specified" { 130 | Mock Get-Command -ModuleName 'AllToolsUtilities' 131 | 132 | $toolInfo = Show-ContainerTools -Latest 133 | 134 | # Check the output 135 | $expectedOutput = @( 136 | [PSCustomObject]@{ Tool = 'containerd'; Installed = $false; Daemon = 'buildkitd'; DaemonStatus = 'Unregistered'; LatestVersion = 'v1.0.1' } 137 | [PSCustomObject]@{ Tool = 'buildkit'; Installed = $false; Daemon = 'buildkitd'; DaemonStatus = 'Unregistered'; LatestVersion = 'v1.0.1' } 138 | [PSCustomObject]@{ Tool = 'nerdctl'; Installed = $false; LatestVersion = 'v1.0.1' } 139 | ) 140 | $expectedOutput | ForEach-Object { 141 | $tool = $_.Tool 142 | $actualOutput = $toolInfo | Where-Object { $_.Tool -eq $tool } 143 | foreach ($key in $_.Keys) { 144 | $expectedValue = $_[$key] 145 | $actualValue = $actualOutput.$key 146 | $actualValue | Should -Be $expectedValue 147 | } 148 | } 149 | } 150 | } 151 | 152 | Context "Install-ContainerTools" -Tag "Install-ContainerTools" { 153 | BeforeAll { 154 | Mock Install-Containerd -ModuleName 'AllToolsUtilities' 155 | Mock Install-Buildkit -ModuleName 'AllToolsUtilities' 156 | Mock Install-Nerdctl -ModuleName 'AllToolsUtilities' 157 | Mock Initialize-NatNetwork -ModuleName 'AllToolsUtilities' 158 | } 159 | 160 | It 'Should not process on implicit request for validation (WhatIfPreference)' { 161 | Mock Install-ContainerTools -ModuleName "AllToolsUtilities" 162 | { 163 | $WhatIfPreference = $true 164 | Install-ContainerTools 165 | } 166 | Should -Invoke -CommandName Install-ContainerTools -ModuleName 'AllToolsUtilities' -Exactly -Times 0 -Scope It 167 | } 168 | 169 | It 'Should not process on explicit request for validation (-WhatIf)' { 170 | Mock Install-ContainerTools -ModuleName "AllToolsUtilities" 171 | 172 | { Install-ContainerTools -WhatIf } 173 | Should -Invoke -CommandName Install-ContainerTools -ModuleName 'AllToolsUtilities' -Exactly -Times 0 -Scope It 174 | } 175 | 176 | It "Should use defaults" { 177 | Install-ContainerTools -Confirm:$false 178 | 179 | Should -Invoke Install-Containerd -ModuleName 'AllToolsUtilities' ` 180 | -ParameterFilter { 181 | $Version -eq 'latest' -and 182 | $InstallPath -eq "$Env:ProgramFiles\Containerd" -and 183 | $DownloadPath -eq "$HOME\Downloads" -and 184 | $Setup -eq $false 185 | } 186 | 187 | Should -Invoke Install-Buildkit -ModuleName 'AllToolsUtilities' ` 188 | -ParameterFilter { 189 | $Version -eq 'latest' -and 190 | $InstallPath -eq "$Env:ProgramFiles\BuildKit" -and 191 | $DownloadPath -eq "$HOME\Downloads" -and 192 | $Setup -eq $false 193 | } 194 | 195 | Should -Invoke Install-Nerdctl -ModuleName 'AllToolsUtilities' ` 196 | -ParameterFilter { 197 | $Version -eq 'latest' -and 198 | $InstallPath -eq "$Env:ProgramFiles\nerdctl" -and 199 | $DownloadPath -eq "$HOME\Downloads" 200 | } 201 | 202 | Should -Invoke Initialize-NatNetwork -ModuleName 'AllToolsUtilities' -Times 0 203 | } 204 | 205 | It "Should use user-specified values" { 206 | Install-ContainerTools ` 207 | -ContainerDVersion '7.8.9' ` 208 | -BuildKitVersion '4.5.6' ` 209 | -NerdCTLVersion '3.2.1' ` 210 | -InstallPath 'TestDrive:\Install Directory' ` 211 | -DownloadPath 'TestDrive:\Download Directory' ` 212 | -Force -Confirm:$false 213 | 214 | 215 | Should -Invoke Install-Containerd -ModuleName 'AllToolsUtilities' -Times 1 -Exactly -Scope It ` 216 | -ParameterFilter { 217 | $Version -eq '7.8.9' -and 218 | $InstallPath -eq "TestDrive:\Install Directory\Containerd" -and 219 | $DownloadPath -eq "TestDrive:\Download Directory" -and 220 | $Setup -eq $false 221 | } 222 | 223 | Should -Invoke Install-Buildkit -ModuleName 'AllToolsUtilities' -Times 1 -Exactly -Scope It ` 224 | -ParameterFilter { 225 | $Version -eq '4.5.6' -and 226 | $InstallPath -eq "TestDrive:\Install Directory\BuildKit" -and 227 | $DownloadPath -eq "TestDrive:\Download Directory" -and 228 | $Setup -eq $false 229 | } 230 | 231 | Should -Invoke Install-Nerdctl -ModuleName 'AllToolsUtilities' -Times 1 -Exactly -Scope It ` 232 | -ParameterFilter { 233 | $Version -eq '3.2.1' -and 234 | $InstallPath -eq "TestDrive:\Install Directory\nerdctl" -and 235 | $DownloadPath -eq "TestDrive:\Download Directory" 236 | } 237 | 238 | Should -Invoke Initialize-NatNetwork -ModuleName 'AllToolsUtilities' -Times 0 239 | } 240 | 241 | It "Should continue installation of other tools on failure" { 242 | Mock Install-Containerd -ModuleName 'AllToolsUtilities' -MockWith { Throw 'Error message' } 243 | 244 | Install-ContainerTools -Force -Confirm:$false 245 | 246 | $Error[0].Exception.Message | Should -Be 'Containerd Installation failed. Error message' 247 | 248 | foreach ($tool in @('buildkit', 'nerdctl')) { 249 | Should -Invoke "Install-$tool" -ModuleName 'AllToolsUtilities' -Times 1 -Exactly -Scope It 250 | } 251 | } 252 | 253 | It "Should register services and initialize NAT network when argument '-RegisterServices' is passed" { 254 | Install-ContainerTools ` 255 | -InstallPath 'TestDrive:\Install Directory' ` 256 | -Force -Confirm:$false ` 257 | -RegisterServices 258 | 259 | Should -Invoke Install-Containerd -ModuleName 'AllToolsUtilities' -Scope It -ParameterFilter { $Setup -eq $true } 260 | Should -Invoke Install-Buildkit -ModuleName 'AllToolsUtilities' -Scope It -ParameterFilter { $Setup -eq $true } 261 | Should -Invoke Initialize-NatNetwork -ModuleName 'AllToolsUtilities' -Times 1 262 | } 263 | 264 | It "Should not throw an error if initializing NAT network fails" { 265 | Mock Initialize-NatNetwork -ModuleName 'AllToolsUtilities' -MockWith { throw 'Error message' } 266 | 267 | { Install-ContainerTools -InstallPath 'TestDrive:\Install Directory' -Force -Confirm:$false -RegisterServices } | Should -Not -Throw 268 | $Error[0].Exception.Message | Should -Be 'Failed to initialize NAT network. Error message' 269 | } 270 | } 271 | } -------------------------------------------------------------------------------- /Tests/ContainerNetworkTools.Tests.ps1: -------------------------------------------------------------------------------- 1 | ########################################################################### 2 | # # 3 | # Copyright (c) Microsoft Corporation. All rights reserved. # 4 | # # 5 | # This code is licensed under the MIT License (MIT). # 6 | # # 7 | ########################################################################### 8 | 9 | 10 | using module "..\containers-toolkit\Private\CommonToolUtilities.psm1" 11 | 12 | Describe "ContainerNetworkTools.psm1" { 13 | BeforeAll { 14 | $RootPath = Split-Path -Parent $PSScriptRoot 15 | $ModuleParentPath = Join-Path -Path $RootPath -ChildPath 'Containers-Toolkit' 16 | 17 | Import-Module -Name "$ModuleParentPath\Private\CommonToolUtilities.psm1" -Force 18 | Import-Module -Name "$ModuleParentPath\Public\ContainerNetworkTools.psm1" -Force 19 | Import-Module -Name "$RootPath\Tests\TestData\MockClasses.psm1" -Force 20 | } 21 | 22 | AfterEach { 23 | $ENV:PESTER = $false 24 | } 25 | 26 | AfterAll { 27 | Get-ChildItem -Path 'TestDrive:\' | Remove-Item -Recurse -Force 28 | 29 | Remove-Module -Name "$ModuleParentPath\Private\CommonToolUtilities.psm1" -Force -ErrorAction Ignore 30 | Remove-Module -Name "$ModuleParentPath\Public\ContainerNetworkTools.psm1" -Force -ErrorAction Ignore 31 | Remove-Module -Name "$RootPath\Tests\TestData\MockClasses.psm1" -Force -ErrorAction Ignore 32 | } 33 | 34 | Context "Get-WinCNILatestVersion" -Tag "Get-WinCNILatestVersion" { 35 | BeforeEach { 36 | Mock Get-LatestToolVersion -ModuleName 'ContainerNetworkTools' 37 | } 38 | 39 | It "Should return the latest version of Windows CNI plugin" { 40 | Get-WinCNILatestVersion 41 | Should -Invoke Get-LatestToolVersion -Times 1 -Scope It -ModuleName 'ContainerNetworkTools' -ParameterFilter { $Tool -eq 'wincniplugin' } 42 | } 43 | 44 | It "Should return the latest version of Cloud Native CNI plugin" { 45 | Get-WinCNILatestVersion -Repo 'containernetworking/plugins' 46 | Should -Invoke Get-LatestToolVersion -Times 1 -Scope It -ModuleName 'ContainerNetworkTools' -ParameterFilter { $Tool -eq 'cloudnativecni' } 47 | } 48 | } 49 | 50 | Context "Install-WinCNIPlugin" -Tag "Install-WinCNIPlugin" { 51 | BeforeAll { 52 | $Script:ToolName = 'WinCNIPlugin' 53 | $Script:WinCNIRepo = 'https://github.com/microsoft/windows-container-networking/releases/download' 54 | $Script:MockZipFileName = "windows-container-networking-cni-amd64-v1.0.0.zip" 55 | $Script:TestDownloadPath = "$HOME\Downloads\$Script:MockZipFileName" 56 | 57 | Mock Get-WinCNILatestVersion { return '1.0.0' } -ModuleName 'ContainerNetworkTools' 58 | Mock Uninstall-WinCNIPlugin -ModuleName "ContainerNetworkTools" 59 | Mock New-Item -ModuleName 'ContainerNetworkTools' 60 | Mock Get-Item -ModuleName 'ContainerNetworkTools' -MockWith { @{ Path = $Script:TestDownloadPath } } -ParameterFilter { $Path -eq $Script:TestDownloadPath } 61 | Mock Get-InstallationFile -ModuleName 'ContainerNetworkTools' -MockWith { $Script:TestDownloadPath } 62 | Mock Expand-Archive -ModuleName 'ContainerNetworkTools' 63 | Mock Remove-Item -ModuleName 'ContainerNetworkTools' 64 | Mock Test-EmptyDirectory -ModuleName 'ContainerNetworkTools' -MockWith { return $true } 65 | Mock Install-WinCNIPlugin -ModuleName 'ContainerNetworkTools' 66 | Mock Test-Path -ModuleName 'ContainerNetworkTools' -MockWith { return $true } 67 | Mock Install-RequiredFeature -ModuleName 'ContainerNetworkTools' 68 | } 69 | 70 | It 'Should not process on implicit request for validation (WhatIfPreference)' { 71 | { 72 | $WhatIfPreference = $true 73 | Install-WinCNIPlugin 74 | } 75 | Should -Invoke -CommandName Install-WinCNIPlugin -ModuleName 'ContainerNetworkTools' -Exactly -Times 0 -Scope It 76 | } 77 | 78 | It 'Should not process on explicit request for validation (-WhatIf)' { 79 | { Install-WinCNIPlugin -WhatIf } 80 | Should -Invoke -CommandName Install-WinCNIPlugin -ModuleName 'ContainerNetworkTools' -Exactly -Times 0 -Scope It 81 | } 82 | 83 | It "Should use defaults" { 84 | Install-WinCNIPlugin -Force -Confirm:$false 85 | 86 | Should -Invoke Uninstall-WinCNIPlugin -ModuleName 'ContainerNetworkTools' -Times 0 -Exactly -Scope It 87 | Should -Invoke Get-InstallationFile -ModuleName 'ContainerNetworkTools' -ParameterFilter { 88 | $fileParameters[0].Feature -eq "$Script:ToolName" -and 89 | $fileParameters[0].Repo -eq "microsoft/windows-container-networking" -and 90 | $fileParameters[0].Version -eq 'latest' -and 91 | $fileParameters[0].DownloadPath -eq "$HOME\Downloads" 92 | [string]::IsNullOrWhiteSpace($fileParameters.ChecksumSchemaFile) -and 93 | $fileParameters[0].FileFilterRegEx -eq $null 94 | } 95 | Should -Invoke Install-RequiredFeature -ModuleName 'ContainerNetworkTools' -ParameterFilter { 96 | $Feature -eq "$Script:ToolName" -and 97 | $InstallPath -eq "$Env:ProgramFiles\Containerd\cni\bin" -and 98 | $SourceFile -eq "$Script:TestDownloadPath" -and 99 | $EnvPath -eq $null -and 100 | $cleanup -eq $true -and 101 | $UpdateEnvPath -eq $false 102 | } 103 | } 104 | 105 | It "Should call function with user-specified values" { 106 | # Mocks 107 | $MockZipFileName = 'windows-container-networking-cni-386-v1.2.3.zip' 108 | $MockDownloadFilePath = "$HOME\Downloads\$MockZipFileName" 109 | Mock Get-InstallationFile -ModuleName 'ContainerNetworkTools' -MockWith { $MockDownloadFilePath } 110 | 111 | # Test 112 | Install-WinCNIPlugin -WinCNIVersion '1.2.3' -WinCNIPath 'TestDrive:\WinCNI\bin' -SourceRepo "containernetworking/plugins" -OSArchitecture '386' -Force -Confirm:$false 113 | 114 | # Assertions 115 | Should -Invoke Uninstall-WinCNIPlugin -ModuleName 'ContainerNetworkTools' -Times 0 -Exactly -Scope It 116 | Should -Invoke Get-InstallationFile -ModuleName 'ContainerNetworkTools' -ParameterFilter { 117 | $fileParameters[0].Version -eq '1.2.3' -and 118 | $fileParameters[0].Repo -eq 'containernetworking/plugins' -and 119 | $fileParameters[0].OSArchitecture -eq '386' -and 120 | $fileParameters[0].FileFilterRegEx -eq ".*tgz(.SHA512)?$" 121 | } 122 | Should -Invoke Install-RequiredFeature -ModuleName 'ContainerNetworkTools' -ParameterFilter { 123 | $Feature -eq "$Script:ToolName" -and 124 | $InstallPath -eq 'TestDrive:\WinCNI\bin' -and 125 | $SourceFile -eq $MockDownloadFilePath -and 126 | $cleanup -eq $true -and 127 | $UpdateEnvPath -eq $false 128 | } 129 | } 130 | 131 | It "Should uninstall tool if it is already installed" { 132 | Mock Test-EmptyDirectory -ModuleName 'ContainerNetworkTools' -MockWith { return $false } 133 | 134 | Install-WinCNIPlugin -Force -Confirm:$false 135 | 136 | Should -Invoke Uninstall-WinCNIPlugin -ModuleName 'ContainerNetworkTools' -Times 1 -Exactly -Scope It ` 137 | -ParameterFilter { $Path -eq "$Env:ProgramFiles\Containerd\cni" } 138 | } 139 | 140 | It "Should throw an error if uninstallation fails" { 141 | Mock Test-EmptyDirectory -ModuleName 'ContainerNetworkTools' -MockWith { return $false } 142 | Mock Uninstall-WinCNIPlugin -ModuleName 'ContainerNetworkTools' -MockWith { throw 'Error' } 143 | 144 | { Install-WinCNIPlugin -Confirm:$false } | Should -Throw "Windows CNI plugin installation failed. Error" 145 | } 146 | } 147 | 148 | Context "Initialize-NatNetwork" -Tag "Initialize-NatNetwork" { 149 | BeforeAll { 150 | Mock Get-DefaultInstallPath -ModuleName 'ContainerNetworkTools' -MockWith { return 'TestDrive:\Program Files\Containerd' } 151 | Mock Get-NetRoute -ModuleName 'ContainerNetworkTools' -MockWith { @{NextHop = "99.2.0.8" } } 152 | Mock Test-EmptyDirectory -ModuleName 'ContainerNetworkTools' -MockWith { return $false } 153 | Mock Get-WinCNILatestVersion { return '1.0.0' } -ModuleName 'ContainerNetworkTools' 154 | Mock Get-Module -ModuleName 'ContainerNetworkTools' -MockWith { return @{} } 155 | Mock Import-Module -ModuleName 'ContainerNetworkTools' 156 | Mock Get-HnsNetwork -ModuleName 'ContainerNetworkTools' 157 | Mock New-HNSNetwork -ModuleName 'ContainerNetworkTools' 158 | Mock Restart-Service -ModuleName 'ContainerNetworkTools' 159 | Mock Install-WinCNIPlugin -ModuleName 'ContainerNetworkTools' 160 | Mock Set-Content -ModuleName 'ContainerNetworkTools' -ParameterFilter { 161 | $Path -eq "$ENV:ProgramFiles\Containerd\cni\conf\0-containerd-nat.conf" } 162 | } 163 | 164 | It "Should use defaults" { 165 | Initialize-NatNetwork -Force 166 | 167 | Should -Invoke Get-NetRoute -ModuleName 'ContainerNetworkTools' 168 | Should -Invoke New-HNSNetwork -ModuleName 'ContainerNetworkTools' -ParameterFilter { 169 | $Name -eq 'NAT' 170 | $Type -eq 'NAT' 171 | $Gateway -eq '99.2.0.8' 172 | $AddressPrefix -eq '99.2.0.0/16' 173 | } 174 | 175 | # NOTE: Since we are running as non-admin, we are not able to write to the default path 176 | # "C:\Program Files\Containerd\cni\conf\0-containerd-nat.conf". Instead, we test that 177 | # Set-Content is called with the correct parameters. 178 | $MockConfFilePath = "C:\Program Files\Containerd\cni\conf\0-containerd-nat.conf" 179 | Should -Invoke Set-Content -ModuleName 'ContainerNetworkTools' -ParameterFilter { 180 | $Path -eq $MockConfFilePath 181 | } 182 | } 183 | 184 | It "Should use user-specified values" { 185 | Initialize-NatNetwork -NetworkName 'TestN/W' -Gateway '80.7.9.5' -CIDR 32 -WinCNIVersion '2.5.7' -WinCNIPath 'TestDrive:\Test Dir\cni' -Force 186 | 187 | Should -Invoke Get-DefaultInstallPath -ModuleName 'ContainerNetworkTools' -Times 0 -Scope It 188 | Should -Invoke Get-NetRoute -ModuleName 'ContainerNetworkTools' -Times 0 -Scope It 189 | Should -Invoke Get-WinCNILatestVersion -ModuleName 'ContainerNetworkTools' -Times 0 -Scope It 190 | Should -Invoke New-HNSNetwork -ModuleName 'ContainerNetworkTools' -ParameterFilter { 191 | $Name -eq 'TestN/W' 192 | $Type -eq 'NAT' 193 | $Gateway -eq '80.7.9.5' 194 | $AddressPrefix -eq '80.7.9.5/32' 195 | } 196 | 197 | $MockConfFilePath = "TestDrive:\Test Dir\cni\conf\0-containerd-nat.conf" 198 | $MockConfFilePath | Should -Exist 199 | $MockConfFilePath | Should -FileContentMatch "`"cniVersion`": `"2.5.7`"" 200 | } 201 | 202 | It "Should install missing WinCNI plugins if plugins are missing" { 203 | Mock Test-EmptyDirectory -ModuleName 'ContainerNetworkTools' -MockWith { return $true } 204 | Mock New-Item -ModuleName 'ContainerNetworkTools' 205 | 206 | Initialize-NatNetwork -Force 207 | Should -Invoke Install-WinCNIPlugin -ModuleName 'ContainerNetworkTools' -ParameterFilter { 208 | $WinCNIPath -eq "$Env:ProgramFiles\Containerd\cni" 209 | } 210 | } 211 | 212 | It "Should throw error if HostNetworkingService and HNS module are not installed" { 213 | Mock Get-Module -ModuleName 'ContainerNetworkTools' 214 | 215 | { Initialize-NatNetwork -Force } | Should -Throw "Could not import HNS module.*" 216 | Should -Invoke Get-Module -ModuleName 'ContainerNetworkTools' -ParameterFilter { $Name -eq 'HostNetworkingService' -or $Name -eq 'HNS' } 217 | } 218 | 219 | It "Should first check HostNetworkingService module by default" { 220 | Mock Get-Module -ModuleName 'ContainerNetworkTools' -ParameterFilter { $Name -eq 'HostNetworkingService' } -MockWith { return @{} } 221 | Mock Get-Module -ModuleName 'ContainerNetworkTools' -ParameterFilter { $Name -eq 'HNS' } 222 | 223 | Initialize-NatNetwork -Force 224 | 225 | Should -Invoke Import-Module -Times 0 -Scope It -ModuleName 'ContainerNetworkTools' -ParameterFilter { $Name -eq 'HNS' } 226 | Should -Invoke Get-Module -Times 0 -Scope It -ModuleName 'ContainerNetworkTools' -ParameterFilter { $Name -eq 'HNS' } 227 | } 228 | 229 | It "Should use HNS module if HostNetworkingService is not installed" { 230 | Mock Get-Module -ModuleName 'ContainerNetworkTools' -ParameterFilter { $Name -eq 'HostNetworkingService' } 231 | Mock Get-Module -ModuleName 'ContainerNetworkTools' -ParameterFilter { $Name -eq 'HNS' } -MockWith { return @{} } 232 | 233 | Initialize-NatNetwork -Force 234 | 235 | Should -Invoke Import-Module -Times 0 -Scope It -ModuleName 'ContainerNetworkTools' -ParameterFilter { $Name -eq 'HostNetworkingService' } 236 | Should -Invoke Import-Module -Times 1 -Scope It -ModuleName 'ContainerNetworkTools' -ParameterFilter { $Name -eq 'HNS' } 237 | } 238 | 239 | It "Should throw an error when importing HNS module fails" { 240 | Mock Get-Module -ModuleName 'ContainerNetworkTools' -ParameterFilter { $Name -eq 'HostNetworkingService' } 241 | Mock Get-Module -ModuleName 'ContainerNetworkTools' -ParameterFilter { $Name -eq 'HNS' } -MockWith { return @{} } 242 | Mock Import-Module -ModuleName 'ContainerNetworkTools' -MockWith { Throw 'Error message.' } 243 | 244 | { Initialize-NatNetwork -Force } | Should -Throw "Could not import HNS module. Error message." 245 | } 246 | 247 | It "Should throw an error if network exists" { 248 | Mock Get-HnsNetwork -ModuleName 'ContainerNetworkTools' -MockWith { return @{ Name = 'TestN/W' } } 249 | { Initialize-NatNetwork -NetworkName 'TestN/W' -Force } | Should -Not -Throw 250 | Should -Invoke New-HNSNetwork -Times 0 -Scope It -ModuleName 'ContainerNetworkTools' 251 | } 252 | 253 | It "Should throw an error if creating a new network fails" { 254 | Mock New-HNSNetwork -ModuleName 'ContainerNetworkTools' -MockWith { Throw 'Error message' } 255 | { Initialize-NatNetwork -NetworkName 'TestN/W' -Force } | Should -Throw "Could not create a new NAT network TestN/W with Gateway 99.2.0.8 and Subnet mask 99.2.0.0/16.*" 256 | } 257 | } 258 | 259 | Context "Uninstall-WinCNIPlugin" -Tag "Uninstall-WinCNIPlugin" { 260 | BeforeAll { 261 | Mock Get-DefaultInstallPath -ModuleName 'ContainerNetworkTools' -MockWith { return 'TestDrive:\Program Files\Containerd' } 262 | Mock Test-EmptyDirectory -ModuleName 'ContainerNetworkTools' -MockWith { return $false } 263 | Mock Remove-Item -ModuleName 'ContainerNetworkTools' 264 | } 265 | 266 | It "Should successfully uninstall WinCNI plugins" { 267 | Uninstall-WinCNIPlugin -Path 'TestDrive:\Program Files' -Confirm:$false -Force 268 | 269 | # Should remove containerd/cni dir 270 | Should -Invoke Remove-Item -Times 1 -Scope It -ModuleName "ContainerNetworkTools" ` 271 | -ParameterFilter { $Path -eq 'TestDrive:\Program Files\cni' } 272 | } 273 | 274 | It "Should successfully uninstall WinCNI plugins from default path" { 275 | Uninstall-WinCNIPlugin -Confirm:$false -Force 276 | 277 | Should -Invoke Remove-Item -Times 1 -Scope It -ModuleName "ContainerNetworkTools" ` 278 | -ParameterFilter { $Path -eq "$ENV:ProgramFiles\Containerd\cni" } 279 | } 280 | 281 | It "Should do nothing if user does not consent to uninstalling WinCNIPlugin" { 282 | $ENV:PESTER = $true 283 | Uninstall-WinCNIPlugin -Confirm:$false -Force:$false 284 | 285 | # Should NOT remove WinCNIPlugin binaries/dir 286 | Should -Invoke Remove-Item -Times 0 -Scope It -ModuleName "ContainerNetworkTools" 287 | } 288 | 289 | It "Should do nothing if WinCNI plugins is not installed at specified path" { 290 | Mock Test-EmptyDirectory -ModuleName 'ContainerNetworkTools' -MockWith { return $true } 291 | 292 | Uninstall-WinCNIPlugin -Path 'TestDrive:\TestDir\cni' -Confirm:$false 293 | Should -Invoke Remove-Item -Times 0 -Scope It -ModuleName "ContainerNetworkTools" 294 | } 295 | } 296 | } -------------------------------------------------------------------------------- /Tests/NerdctlTools.Tests.ps1: -------------------------------------------------------------------------------- 1 | ########################################################################### 2 | # # 3 | # Copyright (c) Microsoft Corporation. All rights reserved. # 4 | # # 5 | # This code is licensed under the MIT License (MIT). # 6 | # # 7 | ########################################################################### 8 | 9 | 10 | using module "..\containers-toolkit\Private\CommonToolUtilities.psm1" 11 | 12 | Describe "NerdctlTools.psm1" { 13 | BeforeAll { 14 | $RootPath = Split-Path -Parent $PSScriptRoot 15 | $ModuleParentPath = Join-Path -Path $RootPath -ChildPath 'Containers-Toolkit' 16 | Import-Module -Name "$ModuleParentPath\Private\CommonToolUtilities.psm1" -Force 17 | Import-Module -Name "$ModuleParentPath\Public\NerdctlTools.psm1" 18 | Import-Module -Name "$ModuleParentPath\Public\ContainerdTools.psm1" 19 | Import-Module -Name "$ModuleParentPath\Public\ContainerNetworkTools.psm1" 20 | Import-Module -Name "$ModuleParentPath\Public\NerdctlTools.psm1" -Force 21 | } 22 | 23 | AfterEach { 24 | $ENV:PESTER = $false 25 | } 26 | 27 | AfterAll { 28 | Remove-Module -Name "$ModuleParentPath\Private\CommonToolUtilities.psm1" -Force -ErrorAction Ignore 29 | Remove-Module -Name "$ModuleParentPath\Public\BuildkitTools.psm1" -Force -ErrorAction Ignore 30 | Remove-Module -Name "$ModuleParentPath\Public\ContainerdTools.psm1" -Force -ErrorAction Ignore 31 | Remove-Module -Name "$ModuleParentPath\Public\ContainerNetworkTools.psm1" -Force -ErrorAction Ignore 32 | Remove-Module -Name "$ModuleParentPath\Public\NerdctlTools.psm1" -Force -ErrorAction Ignore 33 | } 34 | 35 | Context "Install-Nerdctl" -Tag "Install-Nerdctl" { 36 | BeforeAll { 37 | $Script:nerdctlRepo = 'https://github.com/containerd/nerdctl/releases/download' 38 | $Script:TestDownloadPath = "$HOME\Downloads\nerdctl-7.9.8-windows-amd64.tar.gz" 39 | 40 | Mock Get-NerdctlLatestVersion { return '7.9.8' } -ModuleName 'NerdctlTools' 41 | Mock Uninstall-Nerdctl -ModuleName "NerdctlTools" 42 | Mock Get-InstallationFile -ModuleName 'NerdctlTools' -MockWith { return $Script:TestDownloadPath } 43 | Mock Install-RequiredFeature -ModuleName 'NerdctlTools' 44 | Mock Get-Command -ModuleName 'NerdctlTools' 45 | Mock Get-ChildItem -ModuleName 'NerdctlTools' 46 | Mock Test-EmptyDirectory -ModuleName 'NerdctlTools' -MockWith { return $true } 47 | Mock Install-Containerd -ModuleName 'NerdctlTools' 48 | Mock Install-Buildkit -ModuleName 'NerdctlTools' 49 | Mock Install-WinCNIPlugin -ModuleName 'NerdctlTools' 50 | Mock Install-Nerdctl -ModuleName 'NerdctlTools' 51 | Mock Remove-Item -ModuleName 'NerdctlTools' 52 | } 53 | 54 | It 'Should not process on implicit request for validation (WhatIfPreference)' { 55 | { 56 | $WhatIfPreference = $true 57 | Install-Nerdctl 58 | } 59 | Should -Invoke -CommandName Install-Nerdctl -ModuleName 'NerdctlTools' -Exactly -Times 0 -Scope It 60 | } 61 | 62 | It 'Should not process on explicit request for validation (-WhatIf)' { 63 | { Install-Nerdctl -WhatIf } 64 | Should -Invoke -CommandName Install-Nerdctl -ModuleName 'NerdctlTools' -Exactly -Times 0 -Scope It 65 | } 66 | 67 | It "Should use defaults" { 68 | Install-Nerdctl -Force -Confirm:$false 69 | 70 | Should -Invoke Uninstall-Nerdctl -ModuleName 'NerdctlTools' -Times 0 -Exactly -Scope It 71 | Should -Invoke Get-InstallationFile -ModuleName 'NerdctlTools' -ParameterFilter { 72 | $fileParameters[0].Feature -eq "nerdctl" -and 73 | $fileParameters[0].Repo -eq "containerd/nerdctl" -and 74 | $fileParameters[0].Version -eq 'latest' -and 75 | $fileParameters[0].DownloadPath -eq "$HOME\Downloads" 76 | [string]::IsNullOrWhiteSpace($fileParameters.ChecksumSchemaFile) -and 77 | $fileParameters[0].FileFilterRegEx -eq $null 78 | } 79 | 80 | Should -Invoke Install-RequiredFeature -ModuleName 'NerdctlTools' -ParameterFilter { 81 | $Feature -eq "nerdctl" -and 82 | $InstallPath -eq "$Env:ProgramFiles\nerdctl" -and 83 | $SourceFile -eq "$Script:TestDownloadPath" -and 84 | $EnvPath -eq "$Env:ProgramFiles\nerdctl" -and 85 | $cleanup -eq $true 86 | } 87 | 88 | Should -Invoke Install-Containerd -ModuleName 'NerdctlTools' -Times 0 -Exactly -Scope It 89 | Should -Invoke Install-Buildkit -ModuleName 'NerdctlTools' -Times 0 -Exactly -Scope It 90 | Should -Invoke Install-WinCNIPlugin -ModuleName 'NerdctlTools' -Times 0 -Exactly -Scope It 91 | } 92 | 93 | It "Should call function with user-specified values" { 94 | # Mocks 95 | $MockDownloadPath = 'TestDrive:\Downloads\nerdctl-1.2.3-windows-amd64.tar.gz' 96 | Mock Get-InstallationFile -ModuleName 'NerdctlTools' -MockWith { return $MockDownloadPath } 97 | 98 | # Test 99 | Install-Nerdctl -Version '1.2.3' -InstallPath 'TestDrive:\nerdctl' -DownloadPath 'TestDrive:\Downloads' -Dependencies 'containerd' -OSArchitecture "arm64" -Force -Confirm:$false 100 | 101 | # Assertions 102 | Should -Invoke Uninstall-Nerdctl -ModuleName 'NerdctlTools' -Times 0 -Exactly -Scope It 103 | Should -Invoke Get-InstallationFile -ModuleName 'NerdctlTools' -ParameterFilter { 104 | $fileParameters[0].Version -eq '1.2.3' 105 | $fileParameters[0].OSArchitecture -eq 'arm64' 106 | } 107 | Should -Invoke Install-RequiredFeature -ModuleName 'NerdctlTools' -ParameterFilter { 108 | $Feature -eq "nerdctl" 109 | $InstallPath -eq 'TestDrive:\nerdctl' 110 | $SourceFile -eq $MockDownloadPath 111 | $EnvPath -eq 'TestDrive:\nerdctl\bin' 112 | $cleanup -eq $true 113 | } 114 | 115 | Should -Invoke Install-Containerd -ModuleName 'NerdctlTools' -Times 1 -Exactly -Scope It 116 | Should -Invoke Install-Buildkit -ModuleName 'NerdctlTools' -Times 0 -Exactly -Scope It 117 | Should -Invoke Install-WinCNIPlugin -ModuleName 'NerdctlTools' -Times 0 -Exactly -Scope It 118 | } 119 | 120 | It "Should uninstall tool if it is already installed" { 121 | Mock Test-EmptyDirectory -ModuleName 'NerdctlTools' -MockWith { return $false } 122 | 123 | Install-Nerdctl -Force -Confirm:$false 124 | 125 | Should -Invoke Uninstall-Nerdctl -ModuleName 'NerdctlTools' -Times 1 -Exactly -Scope It ` 126 | -ParameterFilter { $Path -eq "$Env:ProgramFiles\nerdctl" } 127 | } 128 | 129 | It "Should throw an error if uninstallation fails" { 130 | Mock Test-EmptyDirectory -ModuleName 'NerdctlTools' -MockWith { return $false } 131 | Mock Uninstall-Nerdctl -ModuleName 'NerdctlTools' -MockWith { throw 'Error' } 132 | 133 | { Install-Nerdctl -Confirm:$false } | Should -Throw "nerdctl installation failed. Error" 134 | } 135 | 136 | It "Should install all dependencies if 'All' is specified" { 137 | Install-Nerdctl -Dependencies 'All' -Confirm:$false 138 | 139 | Should -Invoke Install-Containerd -ModuleName 'NerdctlTools' -Times 1 -Exactly -Scope It 140 | Should -Invoke Install-Buildkit -ModuleName 'NerdctlTools' -Times 1 -Exactly -Scope It 141 | Should -Invoke Install-WinCNIPlugin -ModuleName 'NerdctlTools' -Times 1 -Exactly -Scope It 142 | } 143 | 144 | It "Should install specified dependencies" { 145 | Install-Nerdctl -Dependencies 'containerd' -Confirm:$false 146 | 147 | Should -Invoke Install-Containerd -ModuleName 'NerdctlTools' -Times 1 -Exactly -Scope It 148 | Should -Invoke Install-Buildkit -ModuleName 'NerdctlTools' -Times 0 -Exactly -Scope It 149 | Should -Invoke Install-WinCNIPlugin -ModuleName 'NerdctlTools' -Times 0 -Exactly -Scope It 150 | } 151 | } 152 | 153 | Context "Uninstall-Nerdctl" -Tag "Uninstall-Nerdctl" { 154 | BeforeAll { 155 | Mock Get-DefaultInstallPath -ModuleName 'NerdctlTools' -MockWith { return 'TestDrive:\Program Files\nerdctl' } 156 | Mock Test-EmptyDirectory -ModuleName 'NerdctlTools' -MockWith { return $false } 157 | Mock Remove-Item -ModuleName 'NerdctlTools' 158 | Mock Remove-FeatureFromPath -ModuleName 'NerdctlTools' 159 | Mock Uninstall-ProgramFiles -ModuleName 'NerdctlTools' 160 | 161 | $mockProcess = New-MockObject -Type 'System.Diagnostics.Process' -Properties @{ ExitCode = 0 } 162 | Mock Invoke-ExecutableCommand -ModuleName "NerdctlTools" -MockWith { return $mockProcess } 163 | } 164 | 165 | It "Should successfully uninstall nerdctl" { 166 | Uninstall-Nerdctl -Path 'TestDrive:\Custom\nerdctl\' -Confirm:$false -Force 167 | 168 | # Should remove nerdctl dir 169 | Should -Invoke Remove-Item -Times 1 -Scope It -ModuleName "NerdctlTools" ` 170 | -ParameterFilter { $Path -eq 'TestDrive:\Custom\nerdctl\' } 171 | 172 | # Should not purge program data 173 | Should -Invoke Uninstall-ProgramFiles -Times 0 -Scope It -ModuleName "NerdctlTools" 174 | Should -Invoke Remove-FeatureFromPath -Times 0 -Scope It -ModuleName "NerdctlTools" 175 | Should -Invoke Invoke-ExecutableCommand -Time 0 -Scope It -ModuleName "NerdctlTools" 176 | } 177 | 178 | It "Should successfully uninstall nerdctl from default path" { 179 | Uninstall-Nerdctl -Confirm:$false -Force 180 | 181 | Should -Invoke Remove-Item -Times 1 -Scope It -ModuleName "NerdctlTools" ` 182 | -ParameterFilter { $Path -eq "$ENV:ProgramFiles\nerdctl" } 183 | } 184 | 185 | It "Should successfully purge program data" { 186 | Uninstall-Nerdctl -Path 'TestDrive:\Program Files\nerdctl' -Confirm:$false -Force -Purge 187 | 188 | # Should purge program data 189 | Should -Invoke Remove-Item -Times 1 -Scope It -ModuleName "NerdctlTools" ` 190 | -ParameterFilter { $Path -eq 'TestDrive:\Program Files\nerdctl' } 191 | Should -Invoke Uninstall-ProgramFiles -Times 1 -Scope It -ModuleName "NerdctlTools" ` 192 | -ParameterFilter { $Path -eq "$ENV:ProgramData\nerdctl" } 193 | Should -Invoke Remove-FeatureFromPath -Times 1 -Scope It -ModuleName "NerdctlTools" ` 194 | -ParameterFilter { $Feature -eq "nerdctl" } 195 | Should -Invoke Invoke-ExecutableCommand -Time 1 -Scope It -ModuleName "NerdctlTools" -ParameterFilter { 196 | $executable -eq "TestDrive:\Program Files\nerdctl\nerdctl.exe" -and 197 | $arguments -eq "system prune --all" 198 | } 199 | } 200 | 201 | It "Should do nothing if user does not consent to uninstalling nerdctl" { 202 | $ENV:PESTER = $true 203 | Uninstall-Nerdctl -Path 'TestDrive:\Program Files\nerdctl' -Confirm:$false -Force:$false 204 | 205 | # Should NOT remove nerdctl binaries/dir 206 | Should -Invoke Remove-Item -Times 0 -Scope It -ModuleName "NerdctlTools" 207 | } 208 | 209 | It "Should do nothing if nerdctl is not installed at specified path" { 210 | Mock Test-EmptyDirectory -ModuleName 'NerdctlTools' -MockWith { return $true } 211 | 212 | Uninstall-Nerdctl -Path 'TestDrive:\Program Files\nerdctl' -Confirm:$false 213 | Should -Invoke Remove-Item -Times 0 -Scope It -ModuleName "NerdctlTools" 214 | } 215 | } 216 | } 217 | -------------------------------------------------------------------------------- /Tests/TestData/MockClasses.psm1: -------------------------------------------------------------------------------- 1 | ########################################################################### 2 | # # 3 | # Copyright (c) Microsoft Corporation. All rights reserved. # 4 | # # 5 | # This code is licensed under the MIT License (MIT). # 6 | # # 7 | ########################################################################### 8 | 9 | 10 | class ChoiceClass { 11 | [Int]$MockedChoice 12 | 13 | ChoiceClass( 14 | [Int]$MockedChoice 15 | ) { 16 | $this.MockedChoice = $MockedChoice 17 | } 18 | 19 | [Int]PromptForChoice ($caption, $message, $choices, $defaultChoice) { 20 | return $this.MockedChoice 21 | } 22 | } 23 | 24 | class UITest { 25 | [Int]$MockedChoice 26 | [ChoiceClass]$UI 27 | 28 | UITest( 29 | [Int]$MockedChoice 30 | ) { 31 | $this.MockedChoice = $MockedChoice 32 | $this.UI = [ChoiceClass]::new($this.MockedChoice) 33 | } 34 | } 35 | 36 | class MockService { 37 | [String]$Name 38 | [String]$Status = "Running" 39 | 40 | MockService( 41 | [String]$ServiceName 42 | ) { 43 | $this.Name = $ServiceName 44 | } 45 | 46 | [void]WaitForStatus ($status, $duration) { } 47 | } 48 | 49 | 50 | # To avoid CommandNotFoundException in nodes that do not contain these PS cmdlets, 51 | # we create mock functions instead 52 | function New-HNSNetwork { 53 | [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute( 54 | "PSUseShouldProcessForStateChangingFunctions", 55 | '', 56 | Justification = 'Mock function for testing' 57 | )] 58 | [CmdletBinding()] 59 | param( 60 | $JsonString, 61 | $Type, 62 | $Name, 63 | $AddressPrefix, 64 | $Gateway, 65 | $SubnetPolicies, 66 | $IPv6, 67 | $DNSServer, 68 | $AdapterName, 69 | $AdditionalParams, 70 | $NetworkSpecificParams 71 | ) 72 | 73 | # Prevent PSReviewUnusedParameter false positive 74 | # https://github.com/PowerShell/PSScriptAnalyzer/issues/1472#issuecomment-1544510319 75 | $Null = $JsonString, $Type, $Name, $AddressPrefix, $Gateway, $SubnetPolicies, $IPv6, $DNSServer, $AdapterName, $AdditionalParams, $NetworkSpecificParams 76 | 77 | # Do nothing 78 | } 79 | 80 | 81 | Export-ModuleMember -Function New-HNSNetwork 82 | -------------------------------------------------------------------------------- /Tests/TestData/latestVersion.json: -------------------------------------------------------------------------------- 1 | { 2 | "url": "https://api.github.com/repos/moby/buildkit/releases/125880858", 3 | "assets_url": "https://api.github.com/repos/moby/buildkit/releases/125880858/assets", 4 | "upload_url": "https://uploads.github.com/repos/moby/buildkit/releases/125880858/assets{?name,label}", 5 | "html_url": "https://github.com/moby/buildkit/releases/tag/v0.12.3", 6 | "id": 125880858, 7 | "node_id": "RE_kwDOBYqZiM4HgMoa", 8 | "tag_name": "v0.12.3", 9 | "target_commitish": "master", 10 | "name": "v0.12.3", 11 | "draft": false, 12 | "prerelease": false, 13 | "created_at": "2023-10-19T16:49:00Z", 14 | "published_at": "2023-10-19T22:10:02Z" 15 | } -------------------------------------------------------------------------------- /Tests/TestData/release-assets.json: -------------------------------------------------------------------------------- 1 | { 2 | "tag_name": "v2.0.0-rc.1", 3 | "name": "v2.0.0-rc.1", 4 | "url": "https://api.github.com/repos/containerd/nerdctl/releases/170730383", 5 | "created_at": "2024-08-17T20:42:04Z", 6 | "published_at": "2024-08-17T20:57:32Z", 7 | "assets": [ 8 | { 9 | "url": "https://api.github.com/repos/containerd/nerdctl/releases/assets/186602872", 10 | "id": 186602872, 11 | "node_id": "RA_kwDOEvuRnc4LH1V4", 12 | "name": "nerdctl-2.0.0-rc.1-freebsd-arm64.tar.gz", 13 | "label": "", 14 | "content_type": "application/x-gtar", 15 | "state": "uploaded", 16 | "size": 8875928, 17 | "download_count": 8, 18 | "created_at": "2024-08-17T20:56:39Z", 19 | "updated_at": "2024-08-17T20:56:40Z", 20 | "browser_download_url": "https://github.com/containerd/nerdctl/releases/download/v2.0.0-rc.1/nerdctl-2.0.0-rc.1-freebsd-arm64.tar.gz" 21 | }, 22 | { 23 | "url": "https://api.github.com/repos/containerd/nerdctl/releases/assets/186602868", 24 | "id": 186602868, 25 | "node_id": "RA_kwDOEvuRnc4LH1V0", 26 | "name": "nerdctl-2.0.0-rc.1-linux-amd64.tar.gz", 27 | "label": "", 28 | "content_type": "application/x-gtar", 29 | "state": "uploaded", 30 | "size": 9722129, 31 | "download_count": 242, 32 | "created_at": "2024-08-17T20:56:39Z", 33 | "updated_at": "2024-08-17T20:56:40Z", 34 | "browser_download_url": "https://github.com/containerd/nerdctl/releases/download/v2.0.0-rc.1/nerdctl-2.0.0-rc.1-linux-amd64.tar.gz" 35 | }, 36 | { 37 | "url": "https://api.github.com/repos/containerd/nerdctl/releases/assets/186602929", 38 | "id": 186602929, 39 | "node_id": "RA_kwDOEvuRnc4LH1Wx", 40 | "name": "nerdctl-2.0.0-rc.1-windows-amd64.tar.gz", 41 | "label": "", 42 | "content_type": "application/x-gtar", 43 | "state": "uploaded", 44 | "size": 9189802, 45 | "download_count": 47, 46 | "created_at": "2024-08-17T20:56:45Z", 47 | "updated_at": "2024-08-17T20:56:45Z", 48 | "browser_download_url": "https://github.com/containerd/nerdctl/releases/download/v2.0.0-rc.1/nerdctl-2.0.0-rc.1-windows-amd64.tar.gz" 49 | }, 50 | { 51 | "url": "https://api.github.com/repos/containerd/nerdctl/releases/assets/186602928", 52 | "id": 186602928, 53 | "node_id": "RA_kwDOEvuRnc4LH1Ww", 54 | "name": "nerdctl-full-2.0.0-rc.1-linux-arm64.tar.gz", 55 | "label": "", 56 | "content_type": "application/x-gtar", 57 | "state": "uploaded", 58 | "size": 249734229, 59 | "download_count": 152, 60 | "created_at": "2024-08-17T20:56:45Z", 61 | "updated_at": "2024-08-17T20:56:52Z", 62 | "browser_download_url": "https://github.com/containerd/nerdctl/releases/download/v2.0.0-rc.1/nerdctl-full-2.0.0-rc.1-linux-arm64.tar.gz" 63 | }, 64 | { 65 | "url": "https://api.github.com/repos/containerd/nerdctl/releases/assets/186602870", 66 | "id": 186602870, 67 | "node_id": "RA_kwDOEvuRnc4LH1V2", 68 | "name": "SHA256SUMS", 69 | "label": "", 70 | "content_type": "application/octet-stream", 71 | "state": "uploaded", 72 | "size": 1165, 73 | "download_count": 15, 74 | "created_at": "2024-08-17T20:56:39Z", 75 | "updated_at": "2024-08-17T20:56:39Z", 76 | "browser_download_url": "https://github.com/containerd/nerdctl/releases/download/v2.0.0-rc.1/SHA256SUMS" 77 | }, 78 | { 79 | "url": "https://api.github.com/repos/containerd/nerdctl/releases/assets/186603171", 80 | "id": 186603171, 81 | "node_id": "RA_kwDOEvuRnc4LH1aj", 82 | "name": "SHA256SUMS.asc", 83 | "label": null, 84 | "content_type": "application/octet-stream", 85 | "state": "uploaded", 86 | "size": 659, 87 | "download_count": 3, 88 | "created_at": "2024-08-17T20:57:14Z", 89 | "updated_at": "2024-08-17T20:57:16Z", 90 | "browser_download_url": "https://github.com/containerd/nerdctl/releases/download/v2.0.0-rc.1/SHA256SUMS.asc" 91 | } 92 | ] 93 | } -------------------------------------------------------------------------------- /Tests/TestData/release-tags.json: -------------------------------------------------------------------------------- 1 | [ 2 | { 3 | "name": "v1.7.3", 4 | "zipball_url": "https://api.github.com/repos/containerd/nerdctl/zipball/refs/tags/v1.7.3", 5 | "tarball_url": "https://api.github.com/repos/containerd/nerdctl/tarball/refs/tags/v1.7.3", 6 | "commit": { 7 | "sha": "qwert123456", 8 | "url": "https://api.github.com/repos/containerd/nerdctl/commits/qwert123456" 9 | }, 10 | "node_id": "RANDOMNODEID123654==" 11 | }, 12 | { 13 | "name": "v2.0.0-rc.1", 14 | "zipball_url": "https://api.github.com/repos/containerd/nerdctl/zipball/refs/tags/v2.0.0-rc.1", 15 | "tarball_url": "https://api.github.com/repos/containerd/nerdctl/tarball/refs/tags/v2.0.0-rc.1", 16 | "commit": { 17 | "sha": "yt234567yut3wqw64", 18 | "url": "https://api.github.com/repos/containerd/nerdctl/commits/yt234567yut3wqw64" 19 | }, 20 | "node_id": "RANDOMNODEID087457==" 21 | }, 22 | { 23 | "name": "v1.7.0", 24 | "zipball_url": "https://api.github.com/repos/containerd/nerdctl/zipball/refs/tags/v1.7.0", 25 | "tarball_url": "https://api.github.com/repos/containerd/nerdctl/tarball/refs/tags/v1.7.0", 26 | "commit": { 27 | "sha": "87re0w9er879", 28 | "url": "https://api.github.com/repos/containerd/nerdctl/commits/87re0w9er879" 29 | }, 30 | "node_id": "RANDOMNODEID03722392==" 31 | } 32 | ] -------------------------------------------------------------------------------- /Tests/TestData/test-schema.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-07/schema#", 3 | "type": "object", 4 | "properties": { 5 | "subject": { 6 | "type": "array", 7 | "items": { 8 | "type": "object", 9 | "properties": { 10 | "name": { 11 | "type": "string" 12 | }, 13 | "digest": { 14 | "type": "object", 15 | "patternProperties": { 16 | "^.*$": { 17 | "type": "string" 18 | } 19 | }, 20 | "additionalProperties": false 21 | } 22 | }, 23 | "required": [ 24 | "name", 25 | "digest" 26 | ] 27 | } 28 | } 29 | }, 30 | "required": [ 31 | "subject" 32 | ] 33 | } 34 | -------------------------------------------------------------------------------- /Tests/UpdateEnvironmentPath.Tests.ps1: -------------------------------------------------------------------------------- 1 | ########################################################################### 2 | # # 3 | # Copyright (c) Microsoft Corporation. All rights reserved. # 4 | # # 5 | # This code is licensed under the MIT License (MIT). # 6 | # # 7 | ########################################################################### 8 | 9 | 10 | Describe "UpdateEnvironmentPath.psm1" { 11 | BeforeAll { 12 | $RootPath = Split-Path -Parent $PSScriptRoot 13 | $ModuleParentPath = Join-Path -Path $RootPath -ChildPath 'Containers-Toolkit' 14 | Import-Module -Name "$ModuleParentPath\Private\UpdateEnvironmentPath.psm1" -Force 15 | 16 | # Original enviromnent values 17 | $Script:originalUserPathString = $ENV:Path 18 | $Script:originalSysPathString = [System.Environment]::GetEnvironmentVariable("Path", "Machine") 19 | } 20 | 21 | AfterAll { 22 | Remove-Module -Name "$ModuleParentPath\Private\UpdateEnvironmentPath.psm1" -Force -ErrorAction Ignore 23 | } 24 | 25 | Context "Add feature from env path" -Tag "Update-EnvironmentPath" { 26 | It "Should successfully add the tool to the System environment path" { 27 | # Arrange 28 | $tool = "MyTool" 29 | $path = "TestDrive:\TestTool" 30 | $pathType = "System" 31 | $action = "Add" 32 | 33 | # Act 34 | $result = Update-EnvironmentPath -Tool $tool -Path $path -PathType $pathType -Action $action 35 | 36 | # Assert 37 | $result | Should -BeLike "*$path*" 38 | 39 | # should not update actual values during testing 40 | [System.Environment]::GetEnvironmentVariable("Path", "Machine") | Should -Be $Script:originalSysPathString 41 | $env:Path | Should -Be $Script:originalUserPathString 42 | } 43 | 44 | It "Should successfully add the tool to the User environment path" { 45 | # Arrange 46 | $tool = "MyTool" 47 | $path = "TestDrive:\TestTool" 48 | $pathType = "User" 49 | $action = "Add" 50 | 51 | # Act 52 | $result = Update-EnvironmentPath -Tool $tool -Path $path -PathType $pathType -Action $action 53 | 54 | # Assert 55 | $result | Should -BeLike "*$path*" 56 | 57 | # should not update actual values during testing 58 | [System.Environment]::GetEnvironmentVariable("Path", "Machine") | Should -Be $Script:originalSysPathString 59 | $env:Path | Should -Be $Script:originalUserPathString 60 | } 61 | } 62 | 63 | Context "Remove feature from env path" -Tag "Update-EnvironmentPath" { 64 | It "Should successfully remove the tool to the System environment path" { 65 | # Arrange 66 | $tool = "MyTool" 67 | $path = "TestDrive:\TestTool" 68 | $pathType = "System" 69 | $action = "Remove" 70 | 71 | # Act 72 | $result = Update-EnvironmentPath -Tool $tool -Path $path -PathType $pathType -Action $action 73 | 74 | # Assert 75 | $result | Should -Not -BeLike "*$path*" 76 | 77 | # should not update actual values during testing 78 | [System.Environment]::GetEnvironmentVariable("Path", "Machine") | Should -Be $Script:originalSysPathString 79 | $env:Path | Should -Be $Script:originalUserPathString 80 | } 81 | 82 | It "Should remove the tool from the User environment path" { 83 | # Arrange 84 | $tool = "MyTool" 85 | $path = "TestDrive:\TestTool" 86 | $pathType = "User" 87 | $action = "Remove" 88 | 89 | # Act 90 | $result = Update-EnvironmentPath -Tool $tool -Path $path -PathType $pathType -Action $action 91 | 92 | # Assert 93 | $result | Should -Not -BeLike "*$path*" 94 | 95 | # should not update actual values during testing 96 | [System.Environment]::GetEnvironmentVariable("Path", "Machine") | Should -Be $Script:originalSysPathString 97 | $env:Path | Should -Be $Script:originalUserPathString 98 | } 99 | } 100 | 101 | Context "Invalid parameters" -Tag "Update-EnvironmentPath" { 102 | It "Should throw an error for an invalid Action" { 103 | # Arrange 104 | $tool = "MyTool" 105 | $path = "TestDrive:\TestTool" 106 | $pathType = "User" 107 | $action = "Invalid" 108 | 109 | # Act & Assert 110 | { Update-EnvironmentPath -Tool $tool -Path $path -PathType $pathType -Action $action } | Should -Throw 111 | } 112 | 113 | It "Should throw an error for an invalid PathType" { 114 | # Arrange 115 | $tool = "MyTool" 116 | $path = "TestDrive:\TestTool" 117 | $pathType = "Invalid" 118 | $action = "Add" 119 | 120 | # Act & Assert 121 | { Update-EnvironmentPath -Tool $tool -Path $path -PathType $pathType -Action $action } | Should -Throw 122 | } 123 | } 124 | } 125 | -------------------------------------------------------------------------------- /assets/child-object-permission.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/microsoft/containers-toolkit/216fb37e5b02399090a023f95610d003adc72374/assets/child-object-permission.png -------------------------------------------------------------------------------- /build/hacks/link-check-config.json: -------------------------------------------------------------------------------- 1 | 2 | { 3 | "ignorePatterns": [ 4 | "*/command-reference.md" 5 | ] 6 | } -------------------------------------------------------------------------------- /build/hacks/release-notes-template.md: -------------------------------------------------------------------------------- 1 | ## Introduction 2 | 3 | _Provide a brief summary of the update._ 4 | 5 | ## New Features 6 | 7 | _List the new features and give a short description of what the feature does._ 8 | 9 | ## Bug fixes 10 | 11 | _Bulleted list of bug fixes and issue resolutions: Discuss the resolved issues and their impact._ 12 | 13 | ## Known issues 14 | 15 | _Ongoing issue that are still being worked on._ 16 | 17 | ## Quick start guide 18 | 19 | ### Install from PowerShell Gallery 20 | 21 | ```PowerShell 22 | Install-Module -Name Containers-Toolkit -RequiredVersion "__NEW_VERSTION__" 23 | ``` 24 | 25 | If the module is already installed, update the module: 26 | 27 | ```PowerShell 28 | Update-Module -Name Containers-Toolkit -RequiredVersion "__NEW_VERSTION__" 29 | ``` 30 | 31 | ### Download Source Files 32 | 33 | 1. Download source files 34 | 1. Open a new terminal 35 | 1. cd into the location of the downloaded files 36 | Example: If downloaded to the downloads folder: 37 | 38 | ```PowerShell 39 | cd "$env:USERPROFILE\Downloads\containers-toolkit" 40 | ``` 41 | 42 | 1. Unblock the files 43 | 44 | ```PowerShell 45 | Get-ChildItem -Path . -Recurse | Unblock-File" 46 | ``` 47 | 48 | 1. Import the module 49 | 50 | See instructions in the [Installing and importting Containers-Toolkit module](../../README.md#download-source-files) section 51 | 52 | ## Visuals 53 | 54 | _Screenshots, Side-by-side comparisons, 30-second videos_ 55 | 56 | ## Discussions 57 | 58 | _**Update the discussoin link**_ 59 | 60 | For any questions or feedback on this release, see the discussion: [Containers.ToolKit v__NEW_VERSTION__]() 61 | 62 | ## Release Authors 63 | 64 | [ADD YOUR NAME HERE] (@[ADD YOUR GITHUB ID HERE]) 65 | -------------------------------------------------------------------------------- /build/scripts/generate-ref.ps1: -------------------------------------------------------------------------------- 1 | # Generate the command-reference.md file 2 | 3 | [CmdletBinding()] 4 | param ( 5 | [Parameter(Mandatory = $false)] 6 | [ValidateScript({ Test-Path $_ -PathType Leaf })] 7 | [String]$ManifestPath = (Get-ChildItem -Recurse -Filter "containers-toolkit.psd1").FullName 8 | ) 9 | 10 | # Get the functions exported by the module 11 | $ExportedFunctions = (Get-Module $ManifestPath -ListAvailable).ExportedFunctions 12 | 13 | # Tools 14 | $tools = @( 15 | "ContainerTools", 16 | "BuildKit", 17 | "Containerd", 18 | "Nerdctl", 19 | "WinCNIPlugin" 20 | ) 21 | 22 | # The markdown to be written to the command-reference.md file 23 | $mdString = @" 24 | # Command Reference 25 | 26 | ## Table of Contents 27 | "@ 28 | 29 | # Parse the exported functions and generate the markdown 30 | foreach ($tool in $tools) { 31 | $result = $ExportedFunctions.Keys | Where-Object { $_ -match "$tool" } | ForEach-Object { 32 | "- [$_](./About/$($_).md)" 33 | } 34 | $heading = if ($tool -eq "ContainerTools") { 35 | "General" 36 | } else { 37 | "$tool" 38 | } 39 | $mdString += "`n- $heading`n $($result -join "`n ")" 40 | } 41 | 42 | # Write the markdown to the file 43 | $parentPath = Split-Path -Parent (Split-Path -Parent $PSScriptRoot) 44 | $REF_FILE = Join-Path -Path $parentPath -ChildPath "docs\command-reference.md" 45 | Set-Content -Path $REF_FILE -Value $mdString -Force -Encoding UTF8 46 | 47 | Write-Host "Command reference file generated at: $REF_FILE" -ForegroundColor Green 48 | Write-Host "Please review the generated file and make any necessary adjustments." -ForegroundColor Green -------------------------------------------------------------------------------- /build/scripts/run-tests.ps1: -------------------------------------------------------------------------------- 1 | ########################################################################### 2 | # # 3 | # Copyright (c) Microsoft Corporation. All rights reserved. # 4 | # # 5 | # This code is licensed under the MIT License (MIT). # 6 | # # 7 | ########################################################################### 8 | 9 | <# 10 | .SYNOPSIS 11 | Runs containers-toolkit module tests 12 | 13 | .DESCRIPTION 14 | Runs containers-toolkit module tests. 15 | https://pester.dev/docs/commands/New-PesterConfiguration 16 | https://pester.dev/docs/usage/output 17 | 18 | .PARAMETER ModuleName 19 | Comma-separated list of specific module file (.psm1) in this module to run tests on 20 | 21 | .PARAMETER Tag 22 | Comma-separated list of specific commands/functions in this module to run tests on 23 | https://pester.dev/docs/usage/tags 24 | 25 | .PARAMETER Verbosity 26 | The verbosity of output, options are None, Normal, Detailed and Diagnostic. Default value: 'Detailed' 27 | https://pester.dev/docs/usage/output#verbosity 28 | 29 | .EXAMPLE 30 | PS> .\run-tests.ps1 31 | 32 | .EXAMPLE 33 | To run tests for specific functions, provide the name of the cmdlet/function or a comma-separated list: 34 | PS> .\run-tests.ps1 -Tag "Get-LatestToolVersion,Uninstall-Buildkit" 35 | 36 | .EXAMPLE 37 | To run tests for specific module file, provide the name of the file or a comma-separated list: 38 | PS> .\run-tests.ps1 ModuleName "BuildkitTools.psm1" 39 | 40 | .NOTES 41 | - Set $ErrorActionPreference = "Continue" to ensure that Write-Error messages are not treated as terminating errors. 42 | 43 | #> 44 | 45 | #Requires -Modules @{ ModuleName="Pester"; ModuleVersion="5.5.0" } 46 | 47 | using module ..\..\Tests\TestData\MockClasses.psm1 48 | 49 | [CmdletBinding()] 50 | param ( 51 | [Parameter(HelpMessage = "Verbosity of output. Default: 'Detailed'")] 52 | [ValidateSet('None', 'Normal', 'Detailed', 'Diagnostic')] 53 | [string] $Verbosity = 'Detailed', 54 | 55 | [Parameter(HelpMessage = "Run tests for specific commands/functions")] 56 | [string] $Tag, 57 | 58 | [Parameter(HelpMessage = "Run tests for a specific module file, eg: ContainerdTools.psm1")] 59 | [ValidateScript( 60 | { 61 | $parentPath = Split-Path -Parent (Split-Path -Parent $PSScriptRoot) 62 | $validNames = (Get-ChildItem -Path $parentPath\containers-toolkit\ -Recurse -Filter "*.psm1").Name | Sort-Object -Unique 63 | 64 | # Check if the module name is valid with the extension 65 | if ($_ -in $validNames) { 66 | return $true 67 | } 68 | 69 | # Remove the extension from the valid names 70 | $validNames = $validNames | ForEach-Object { $_ -replace '\.psm1$' } 71 | if ($_ -in $validNames) { 72 | return $true 73 | } 74 | 75 | # Throw an error if the module name is not valid 76 | $_validNames = ($validNames | ForEach-Object { $_ + '(.psm1)' }) -join ', ' 77 | throw "Invalid module name '$_'. The valid names are: $_validNames" 78 | }, 79 | ErrorMessage = "Please specify a valid .psm1 file name." 80 | )] 81 | [string] $ModuleName 82 | ) 83 | Write-Output "ErrorActionPreference: $ErrorActionPreference" 84 | 85 | $RootDir = Split-Path -Parent (Split-Path -Parent $PSScriptRoot) 86 | Write-Output "Root directory: $RootDir" 87 | 88 | New-Item -Path Env:\Pester -Value $true -Force | Out-Null 89 | 90 | ######################################################## 91 | #################### IMPORT MODULES #################### 92 | ######################################################## 93 | Write-Output "Importing modules" 94 | Import-Module PowerShellGet # Needed to avoid error: "CommandNotFoundException: Could not find Command Install-Module" 95 | Import-Module Pester -Force 96 | 97 | ####################################################### 98 | ################### DISCONVER TESTS ################### 99 | ####################################################### 100 | Write-Output "Discovering tests" 101 | $ModuleParentPath = "$RootDir\containers-toolkit" 102 | $unitTests = Get-ChildItem -Path "$RootDir\Tests" -Filter "*.tests.ps1" -Recurse 103 | $array = @() 104 | 105 | foreach ($unitTest in $unitTests) { 106 | Write-Output "Unit tests found in $($unitTest.FullName)" 107 | $container = New-PesterContainer -Path $unitTest.FullName 108 | $array += $container 109 | } 110 | 111 | 112 | ####################################################### 113 | ###################### FUNCTIONS ###################### 114 | ####################################################### 115 | 116 | function ParseModuleNames { 117 | param ( 118 | [string] $ModuleName 119 | ) 120 | 121 | if (-not $ModuleName) { 122 | return 123 | } 124 | 125 | $moduleNames = $ModuleName -split ',' | ForEach-Object { 126 | $name = $_.Trim() 127 | if ($name -like '*.psm1') { 128 | return $name 129 | } 130 | else { 131 | return $name += '.psm1' 132 | } 133 | } 134 | return $moduleNames 135 | } 136 | 137 | ####################################################### 138 | ################ PESTER CONFIGURATION ################# 139 | ####################################################### 140 | # https://pester.dev/docs/commands/New-PesterConfiguration 141 | $config = [PesterConfiguration]::Default 142 | $config.Output.Verbosity = $Verbosity 143 | $config.Filter.Tag = ($tag -split ',') 144 | $config.Filter.FullName = (ParseModuleNames -ModuleName $ModuleName) 145 | $config.TestResult.Enabled = $true 146 | $config.TestResult.OutputFormat = "NUnitXML" 147 | $config.TestResult.OutputPath = "$RootDir\TestResults\Test-Results.xml" 148 | $config.CodeCoverage.Enabled = $true 149 | $config.CodeCoverage.OutputFormat = "JaCoCo" 150 | $config.CodeCoverage.OutputPath = "$RootDir\TestResults\coverage.xml" 151 | $config.CodeCoverage.Path = @( "$ModuleParentPath\Private", "$ModuleParentPath\Public" ) 152 | $config.Run.Exit = $False 153 | $config.Run.Container = $array 154 | 155 | Invoke-Pester -Configuration $config 156 | 157 | 158 | ###################################################### 159 | ###################### CLEANUP ####################### 160 | ###################################################### 161 | Get-Item -Path Env:\Pester -ErrorAction SilentlyContinue | Remove-Item -Force 162 | -------------------------------------------------------------------------------- /build/scripts/script-analyzer.ps1: -------------------------------------------------------------------------------- 1 | ########################################################################### 2 | # # 3 | # Copyright (c) Microsoft Corporation. All rights reserved. # 4 | # # 5 | # This code is licensed under the MIT License (MIT). # 6 | # # 7 | ########################################################################### 8 | 9 | # $ErrorActionPreference = 'Stop' 10 | function ConvertTo-MarkdownTable { 11 | param ( 12 | [Parameter(Mandatory = $true)] 13 | [PSObject]$InputObject 14 | ) 15 | 16 | $table = "| Rule Name | Severity | Count |`n| -------- | ------- | ------- |" 17 | foreach ($object in $InputObject) { 18 | $count = $object.Count 19 | 20 | $name = $object.Name -split "," 21 | $severity = $name[0].Trim() 22 | $ruleName = $name[1].Trim() 23 | 24 | $table += "`n| $ruleName | $severity | $count |" 25 | } 26 | 27 | return $table 28 | } 29 | 30 | function ConvertTo-MarkDown { 31 | param ( 32 | [PSObject]$InputObject, 33 | [String]$IssueCountString 34 | ) 35 | 36 | $summary = $InputObject | Group-Object -Property Severity, RuleName -NoElement | Sort-Object Count -Descending 37 | $table = ConvertTo-MarkdownTable $summary 38 | 39 | return @( 40 | "### PSSciptAnalysis Report`n" 41 | "
" 42 | "" 43 | ":triangular_flag_on_post: " 44 | $IssueCountString 45 | "`n" 46 | # blank lines are needed before/after a section of markdown that is within an html tag, 47 | # otherwise the markdown won't work 48 | "`n" 49 | "$table" 50 | "`n" 51 | "`n
" 52 | ) -join ' ' 53 | } 54 | 55 | function Invoke-CTKScriptAnalyzer { 56 | $codeAnalysis = Invoke-ScriptAnalyzer -Path . -Recurse -ExcludeRule PSProvideCommentHelp, PSUseSingularNouns 57 | 58 | $lintIssues = $codeAnalysis | Where-Object { $_.Severity -notlike 'Error' } 59 | $lintErrors = $codeAnalysis | Where-Object { $_.Severity -like '*Error' } 60 | 61 | $IssueCountString = "$($lintErrors.Count) errors and $($lintIssues.Count) warnings found" 62 | Write-Warning $IssueCountString 63 | 64 | if ($lintErrors -or $lintIssues) { 65 | Export-Clixml -Path 'psscriptanalysis.xml' -InputObject $codeAnalysis 66 | 67 | # Convert to markdown 68 | Write-Output (ConvertTo-MarkDown -InputObject $codeAnalysis -IssueCountString $IssueCountString) 69 | } 70 | else { 71 | Write-Output ":clap: $IssueCountString" 72 | } 73 | 74 | if ($lintErrors) { 75 | Throw "$($lintErrors.Count) lint errors found" 76 | } 77 | } 78 | 79 | 80 | if (!(Get-Module -Name PSScriptAnalyzer -ListAvailable)) { 81 | Install-Module -Name PSScriptAnalyzer -Scope CurrentUser 82 | } 83 | Import-Module -Name PSScriptAnalyzer -Force 84 | 85 | Invoke-CTKScriptAnalyzer 86 | -------------------------------------------------------------------------------- /build/scripts/update-ctkmanifest.ps1: -------------------------------------------------------------------------------- 1 | ########################################################################### 2 | # # 3 | # Copyright (c) Microsoft Corporation. All rights reserved. # 4 | # # 5 | # This code is licensed under the MIT License (MIT). # 6 | # # 7 | ########################################################################### 8 | 9 | <# 10 | .SYNOPSIS 11 | Updates the version of the containers-toolkit module in the module manifest file. 12 | 13 | The script is a PowerShell script that takes two parameters: 14 | .PARAMETER ManifestPath 15 | The path to the module manifest file. 16 | Defaults to the first containers-toolkit.psd1 file found in the repository. 17 | 18 | .PARAMETER ReleaseType 19 | The type of release to perform. 20 | Defaults to 'patch'. 21 | #> 22 | 23 | [CmdletBinding()] 24 | param ( 25 | [Parameter(Mandatory = $false)] 26 | [ValidateScript({ Test-Path $_ -PathType Leaf })] 27 | [String]$ManifestPath = (Get-ChildItem -Recurse -Filter "containers-toolkit.psd1").FullName, 28 | 29 | [Parameter(Mandatory = $false)] 30 | [ValidateSet('major', 'minor', 'patch')] 31 | [String]$ReleaseType = 'patch' 32 | ) 33 | 34 | $Script:ManifestPath = $ManifestPath 35 | $Script:ReleaseType = $ReleaseType 36 | 37 | function Get-NewVersion { 38 | [version]$currentVersion = (Get-Module -ListAvailable -Name $Script:ManifestPath).Version 39 | 40 | $Major = $currentVersion.Major 41 | $Minor = $currentVersion.Minor 42 | $Build = $currentVersion.Build 43 | 44 | switch ($Script:ReleaseType) { 45 | # MAJOR version is increased for incompatible API changes. 46 | 'major' { 47 | $Major++ 48 | $Minor = 0 49 | $Build = 0 50 | } 51 | # MINOR version is increased for backward-compatible feature additions. 52 | 'minor' { 53 | $Minor++ 54 | $Build = 0 55 | } 56 | # PATCH version is increased for backward-compatible bug fixes. 57 | 'patch' { 58 | $Build++ 59 | } 60 | Default { 61 | Write-Error "Invalid release type specified: '$Script:ReleaseType'" 62 | exit 1 63 | } 64 | } 65 | 66 | return (New-Object Version -ArgumentList $major, $minor, $build).ToString() 67 | } 68 | 69 | function Update-CTKModuleManifest { 70 | [CmdletBinding( 71 | SupportsShouldProcess = $true, 72 | ConfirmImpact = 'High' 73 | )] 74 | param() 75 | 76 | begin { 77 | $NewSemVer = Get-NewVersion 78 | $WhatIfMessage = "Module version will be updated to version $NewSemVer" 79 | } 80 | 81 | process { 82 | if ($PSCmdlet.ShouldProcess($Script:ManifestPath, $WhatIfMessage)) { 83 | $Params = @{ 84 | Path = $manifestPath 85 | ModuleVersion = $NewSemVer 86 | LicenseUri = "https://github.com/microsoft/containers-toolkit/blob/v$NewSemVer/LICENSE" 87 | } 88 | Update-ModuleManifest @Params 89 | 90 | # Test the manifest script is valid 91 | Test-ModuleManifest -Path $manifestPath | Out-Null 92 | 93 | return $NewSemVer 94 | } 95 | else { 96 | # Code that should be processed if doing a WhatIf operation 97 | # Must NOT change anything outside of the function / script 98 | return 99 | } 100 | } 101 | } 102 | 103 | Update-CTKModuleManifest -Confirm:$false 104 | -------------------------------------------------------------------------------- /containers-toolkit/Private/UpdateEnvironmentPath.psm1: -------------------------------------------------------------------------------- 1 | ########################################################################### 2 | # # 3 | # Copyright (c) Microsoft Corporation. All rights reserved. # 4 | # # 5 | # This code is licensed under the MIT License (MIT). # 6 | # # 7 | ########################################################################### 8 | 9 | function Update-EnvironmentPath { 10 | [CmdletBinding( 11 | SupportsShouldProcess = $true 12 | )] 13 | param ( 14 | [parameter(HelpMessage = "Name of the tool add or remove from env path")] 15 | [string] $Tool, 16 | 17 | [parameter(HelpMessage = "Path of the tool to add or remove from env path")] 18 | [string] $Path, 19 | 20 | [ValidateSet("System", "User")] 21 | [parameter(HelpMessage = "Path to change: System or User")] 22 | [string]$PathType, 23 | 24 | [ValidateSet("Add", "Remove")] 25 | [parameter(HelpMessage = "Action: Add or Remove the feature path from the environment")] 26 | [string] $Action 27 | ) 28 | 29 | process { 30 | if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, "$path will be added to environment path")) { 31 | # Get current environment path 32 | $parsedPathString = switch ($PathType) { 33 | "System" { 34 | $pathVariable = [System.Environment]::GetEnvironmentVariable("Path", "Machine") 35 | ParsePathString -PathString $pathVariable 36 | } 37 | "User" { 38 | ParsePathString -PathString $env:Path 39 | } 40 | Default { throw "Invalid PathType: $PathType" } 41 | } 42 | 43 | # Check if the path needs to be changed 44 | $pathFound = "$Path" -in ($parsedPathString -split ";") 45 | switch ($Action) { 46 | "Add" { 47 | $pathChanged = (-not $pathFound) 48 | $toAction = $Path 49 | $ActionVerb = "Adding" 50 | } 51 | "Remove" { 52 | $pathChanged = $pathFound 53 | $toAction = $Tool 54 | $ActionVerb = "Removing" 55 | } 56 | Default { throw "Invalid PathType: $PathType" } 57 | } 58 | 59 | if ($pathChanged) { 60 | Write-Information -InformationAction Continue -MessageData "$ActionVerb $toAction in $PathType Environment Path" 61 | 62 | # Get the updated path 63 | $updatedPath = switch ($Action) { 64 | "Add" { AddFeatureToPath -PathString $parsedPathString -ToolPath $Path } 65 | "Remove" { RemoveFeatureFromPath -PathString $parsedPathString -Tool $Tool } 66 | Default { throw "Invalid Action: $Action" } 67 | } 68 | 69 | # For tests, we do not want to update the environment path 70 | if ($env:pester) { 71 | Write-Debug "Skipping environment path update for tests" 72 | return $updatedPath 73 | } 74 | 75 | # Update the environment path 76 | switch ($PathType) { 77 | "System" { 78 | [System.Environment]::SetEnvironmentVariable("Path", "$updatedPath", [System.EnvironmentVariableTarget]::Machine) 79 | } 80 | "User" { 81 | $env:Path = $updatedPath 82 | } 83 | Default { 84 | throw"Invalid PathType: $PathType" 85 | } 86 | } 87 | } 88 | } 89 | else { 90 | # Code that should be processed if doing a WhatIf operation 91 | # Must NOT change anything outside of the function / script 92 | return 93 | } 94 | } 95 | } 96 | 97 | function ParsePathString($PathString) { 98 | $parsedString = $PathString -split ";" | ` 99 | ForEach-Object { $_.TrimEnd("\") } | ` 100 | Select-Object -Unique | ` 101 | Where-Object { ![string]::IsNullOrWhiteSpace($_) } 102 | 103 | if ($null -eq $parsedString) { 104 | Throw 'Env path cannot be null or an empty string' 105 | } 106 | return $parsedString -join ";" 107 | } 108 | 109 | function AddFeatureToPath ($PathString, $ToolPath) { 110 | if (!$PathString) { 111 | Throw 'Env path cannot be null or an empty string' 112 | } 113 | return (ParsePathString -PathString "$ToolPath;$PathString") 114 | } 115 | 116 | function RemoveFeatureFromPath ($PathString, $Tool) { 117 | $pathString = ParsePathString -PathString $pathString 118 | $parsedString = $pathString -split ";" | Where-Object { ($_ -notlike "*$tool*") } 119 | 120 | if (!$parsedString) { 121 | Throw 'Env path cannot be null or an empty string' 122 | } 123 | return $parsedString -join ";" 124 | } 125 | 126 | 127 | Export-ModuleMember -Function Update-EnvironmentPath 128 | -------------------------------------------------------------------------------- /containers-toolkit/Private/schemas/in-toto.sbom.schema.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-07/schema#", 3 | "type": "object", 4 | "properties": { 5 | "_type": { 6 | "type": "string" 7 | }, 8 | "subject": { 9 | "type": "array", 10 | "items": { 11 | "type": "object", 12 | "properties": { 13 | "name": { 14 | "type": "string" 15 | }, 16 | "digest": { 17 | "type": "object", 18 | "patternProperties": { 19 | "^.*$": { 20 | "type": "string" 21 | } 22 | }, 23 | "additionalProperties": false 24 | } 25 | }, 26 | "required": [ 27 | "name", 28 | "digest" 29 | ] 30 | } 31 | } 32 | }, 33 | "required": [ 34 | "_type", 35 | "subject" 36 | ] 37 | } 38 | -------------------------------------------------------------------------------- /containers-toolkit/Public/AllToolsUtilities.psm1: -------------------------------------------------------------------------------- 1 | ########################################################################### 2 | # # 3 | # Copyright (c) Microsoft Corporation. All rights reserved. # 4 | # # 5 | # This code is licensed under the MIT License (MIT). # 6 | # # 7 | ########################################################################### 8 | 9 | 10 | $ModuleParentPath = Split-Path -Parent $PSScriptRoot 11 | Import-Module -Name "$ModuleParentPath\Private\CommonToolUtilities.psm1" -Force 12 | 13 | 14 | function Show-ContainerTools { 15 | param ( 16 | [Parameter(HelpMessage = "Show latest release version")] 17 | [Switch]$Latest, 18 | 19 | [Parameter(HelpMessage = "Tool to show")] 20 | [ValidateSet("containerd", "buildkit", "nerdctl")] 21 | [String[]]$ToolName 22 | ) 23 | 24 | $tools = if ($ToolName) { $ToolName } else { @("containerd", "buildkit", "nerdctl") } 25 | 26 | $installedTools = @() 27 | foreach ($tool in $tools) { 28 | $installedTools += (Get-InstalledVersion -Feature $tool -Latest:$Latest) 29 | } 30 | 31 | $registerCommands = (Get-Command -Name "*-*Service" -Module 'Containers-Toolkit').Name -join ', ' 32 | $message = "For unregistered services/daemons, check the tool's help or register the service using `n`t$registerCommands" 33 | Write-Information -MessageData $message -Tags "Instructions" -InformationAction Continue 34 | return $installedTools 35 | } 36 | 37 | function Install-ContainerTools { 38 | [CmdletBinding( 39 | SupportsShouldProcess = $true, 40 | ConfirmImpact = 'High' 41 | )] 42 | param( 43 | [string] 44 | [ValidateNotNullOrEmpty()] 45 | [parameter(HelpMessage = "ContainerD version to use")] 46 | $ContainerDVersion = "latest", 47 | 48 | [string] 49 | [ValidateNotNullOrEmpty()] 50 | [parameter(HelpMessage = "Buildkit version to use")] 51 | $BuildKitVersion = "latest", 52 | 53 | [string] 54 | [ValidateNotNullOrEmpty()] 55 | [parameter(HelpMessage = "nerdctl version to use")] 56 | $NerdCTLVersion = "latest", 57 | 58 | [String] 59 | [parameter(HelpMessage = "Path to Install files. Defaults to Program Files")] 60 | $InstallPath = $Env:ProgramFiles, 61 | 62 | [String] 63 | [parameter(HelpMessage = "Path to download files. Defaults to user's Downloads folder")] 64 | $DownloadPath = "$HOME\Downloads", 65 | 66 | [Switch] 67 | [parameter(HelpMessage = "Force install the tools even if they already exists at the specified path")] 68 | $Force, 69 | 70 | [switch] 71 | [parameter(HelpMessage = "Register and Start Containerd and Buildkitd services and set up NAT network")] 72 | $RegisterServices 73 | ) 74 | 75 | begin { 76 | # Strip leading "v" from version 77 | $containerdVersion = $containerdVersion.TrimStart("v") 78 | $buildKitVersion = $buildKitVersion.TrimStart("v") 79 | $nerdctlVersion = $nerdctlVersion.TrimStart("v") 80 | 81 | $toInstall = @("containerd v$containerdVersion", "buildkit v$buildKitVersion", "nerdctl v$nerdctlVersion") 82 | $toInstallString = $($toInstall -join ', ') 83 | 84 | $WhatIfMessage = "$toInstallString will be installed. Any downloaded files will be removed" 85 | if ($Force) { 86 | $WhatIfMessage = "$toInstallString will be automatically uninstalled (if they are already installed) and reinstalled. Any downloaded files will be removed" 87 | } 88 | } 89 | 90 | process { 91 | if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { 92 | Write-Output "The following tools will be installed: $toInstallString" 93 | 94 | Write-Debug "Downloading files to $DownloadPath" 95 | Write-Debug "Installing files to $InstallPath" 96 | 97 | $completedInstalls = @() 98 | $failedInstalls = @() 99 | 100 | $installTasks = @( 101 | @{ 102 | name = "Containerd" 103 | function = { 104 | Install-Containerd -Force:$force -Confirm:$false ` 105 | -Version $containerdVersion ` 106 | -InstallPath "$InstallPath\Containerd" ` 107 | -DownloadPath "$DownloadPath" ` 108 | -Setup:$RegisterServices 109 | } 110 | }, 111 | @{ 112 | name = "Buildkit" 113 | function = { 114 | Install-Buildkit -Force:$force -Confirm:$false ` 115 | -Version $buildKitVersion ` 116 | -InstallPath "$InstallPath\Buildkit" ` 117 | -DownloadPath "$DownloadPath" ` 118 | -Setup:$RegisterServices 119 | } 120 | }, 121 | @{ 122 | name = "nerdctl" 123 | function = { 124 | Install-Nerdctl -Force:$force -Confirm:$false ` 125 | -Version $nerdctlVersion ` 126 | -InstallPath "$InstallPath\nerdctl" ` 127 | -DownloadPath "$DownloadPath" 128 | } 129 | } 130 | ) 131 | 132 | foreach ($task in $installTasks) { 133 | try { 134 | & $task.Function 135 | $completedInstalls += $task.Name 136 | } 137 | catch { 138 | Write-Error "$($task.Name) installation failed. $_" 139 | $failedInstalls += $task.Name 140 | } 141 | } 142 | 143 | if ($completedInstalls) { 144 | Write-Output "$($completedInstalls -join ', ') installed successfully.`n" 145 | } 146 | 147 | if ($failedInstalls) { 148 | Write-Warning "Installation failed for $($failedInstalls -join ', ')`n" 149 | } 150 | 151 | if ($RegisterServices) { 152 | try { 153 | Initialize-NatNetwork -Force:$force -Confirm:$false 154 | } 155 | catch { 156 | Write-Error "Failed to initialize NAT network. $_" 157 | } 158 | } 159 | else { 160 | $message = @" 161 | To register containerd and buildkitd services and create a NAT network, see help on the following commands: 162 | Get-Help Register-ContainerdService 163 | Get-Help Register-BuildkitdService 164 | Get-Help Initialize-NatNetwork 165 | "@ 166 | Write-Information -MessageData $message -Tags "Instructions" -InformationAction Continue 167 | } 168 | 169 | Write-Output "Installation complete. See logs for more details" 170 | } 171 | else { 172 | # Code that should be processed if doing a WhatIf operation 173 | # Must NOT change anything outside of the function / script 174 | return 175 | } 176 | } 177 | } 178 | 179 | function Get-InstalledVersion($feature, $Latest) { 180 | $sourceLocation = $null 181 | $daemon = $null 182 | $buildctlPath = $null 183 | switch ($feature) { 184 | "buildkit" { 185 | $blktCommandInfo = Get-Command "build*.exe" | Where-Object { $_.Source -like "*buildkit*" } 186 | if ($null -ne $blktCommandInfo) { 187 | # Get buildkitd executable 188 | $buldkitdCommandInfo = $blktCommandInfo | Where-Object { $_.Name -like "buildkitd.exe" } 189 | $sourceLocation = $buldkitdCommandInfo.Source 190 | } 191 | $daemon = 'buildkitd' 192 | 193 | $buildctlPath = ($blktCommandInfo | Where-Object { $_.Name -like "buildctl.exe" }).Source 194 | } 195 | Default { 196 | $commandInfo = Get-Command "$feature.exe" -ErrorAction Ignore 197 | 198 | if ($null -ne $commandInfo) { 199 | $sourceLocation = $commandInfo.Source 200 | } 201 | 202 | if ($feature -eq 'containerd') { 203 | $daemon = 'containerd' 204 | } 205 | } 206 | } 207 | 208 | $result = [PSCustomObject]@{ 209 | Tool = $feature 210 | Installed = $False 211 | } 212 | if ($sourceLocation) { 213 | $result = getToolVersion -Executable $sourceLocation 214 | Add-Member -InputObject $result -Name 'Tool' -Value $feature -MemberType 'NoteProperty' 215 | Add-Member -InputObject $result -Name 'Path' -Value $sourceLocation -MemberType 'NoteProperty' 216 | $result = $result | Select-Object Tool, Path, Installed, Version 217 | 218 | if ($daemon) { 219 | Add-Member -InputObject $result -Name 'Daemon' -Value $daemon -MemberType 'NoteProperty' 220 | Add-Member -InputObject $result -Name 'DaemonStatus' -MemberType 'NoteProperty' ` 221 | -Value (getDaemonStatus -Daemon $daemon) 222 | } 223 | 224 | if ($buildctlPath) { 225 | $result | Add-Member -Name 'BuildctlPath' -Value $buildctlPath -MemberType 'NoteProperty' 226 | } 227 | } 228 | 229 | # Get latest version 230 | $latestVersion = "-" 231 | if ($Latest) { 232 | $latestVersionCommand = "Get-$($feature)LatestVersion" 233 | $latestVersion = & $latestVersionCommand 234 | Add-Member -InputObject $result -Name 'LatestVersion' -Value "v$latestVersion" -MemberType 'NoteProperty' 235 | } 236 | 237 | return $result 238 | } 239 | 240 | function getToolVersion($executable) { 241 | $toolName = [System.IO.Path]::GetFileNameWithoutExtension([System.IO.Path]::GetFileName($executable)) 242 | 243 | $installedVersion = $null 244 | try { 245 | $cmdOutput = Invoke-ExecutableCommand -Executable $executable -Arguments '--version' 246 | if ($cmdOutput.ExitCode -ne 0) { 247 | Throw "Couldn't get $toolName version. $($cmdOutput.StandardError.ReadToEnd())" 248 | } 249 | 250 | $version = $cmdOutput.StandardOutput.ReadToEnd() 251 | 252 | $pattern = "(\d+\.)(\d+\.)(\*|\d+)" 253 | $installedVersion = ($version | Select-String -Pattern $pattern).Matches.Value 254 | if ($installedVersion) { 255 | $installedVersion = "v$installedVersion" 256 | } 257 | else { 258 | $installedVersion = 'unknown' 259 | } 260 | } 261 | catch { 262 | $installedVersion = "-" 263 | } 264 | 265 | $Installed = ($null -ne $installedVersion) 266 | if (!$Installed) { 267 | $executablePath = Get-Command $executable.Source -ErrorAction Ignore 268 | $installed = ($null -ne $executablePath) 269 | } 270 | 271 | $result = [PSCustomObject]@{ 272 | Installed = $Installed 273 | Version = $installedVersion 274 | } 275 | return $result 276 | } 277 | 278 | function getDaemonStatus($daemon) { 279 | $daemonStatus = Get-Service -Name $daemon -ErrorAction Ignore 280 | if ($null -eq $daemonStatus) { 281 | return 'Unregistered' 282 | } 283 | 284 | return $daemonStatus.Status 285 | } 286 | 287 | Export-ModuleMember -Function Show-ContainerTools 288 | Export-ModuleMember -Function Install-ContainerTools 289 | -------------------------------------------------------------------------------- /containers-toolkit/Public/NerdctlTools.psm1: -------------------------------------------------------------------------------- 1 | ########################################################################### 2 | # # 3 | # Copyright (c) Microsoft Corporation. All rights reserved. # 4 | # # 5 | # This code is licensed under the MIT License (MIT). # 6 | # # 7 | ########################################################################### 8 | 9 | using module "..\Private\CommonToolUtilities.psm1" 10 | 11 | $ModuleParentPath = Split-Path -Parent $PSScriptRoot 12 | Import-Module -Name "$ModuleParentPath\Private\CommonToolUtilities.psm1" -Force 13 | 14 | function Get-NerdctlLatestVersion { 15 | $latestVersion = Get-LatestToolVersion -Tool "nerdctl" 16 | return $latestVersion 17 | } 18 | 19 | function Get-NerdctlDependencies($dependencies) { 20 | if (!$dependencies) { 21 | return 22 | } 23 | 24 | $nerdctlDependencies = @("Containerd", "Buildkit", "WinCNIPlugin") 25 | if ($Dependencies -and $Dependencies -contains "All") { 26 | $dependencies = $nerdctlDependencies 27 | } 28 | 29 | foreach ($dependency in $dependencies) { 30 | if (-not ($nerdctlDependencies -contains $dependency)) { 31 | Throw "Invalid dependency option: $dependency. Allowed options: All, Containerd, Buildkit, WinCNIPlugin" 32 | } 33 | } 34 | 35 | return $dependencies 36 | } 37 | 38 | function Install-NerdctlDependencies { 39 | param( 40 | [String[]]$Dependencies, 41 | [string]$OsArch, 42 | [Switch]$Force 43 | ) 44 | 45 | foreach ($dependency in $Dependencies) { 46 | $InstallCommand = "Install-$dependency" 47 | try { 48 | & $InstallCommand -OSArchitecture $OsArch -Force:$Force -Confirm:$false 49 | } 50 | catch { 51 | Write-Error "Installation failed for $dependency. $_" 52 | } 53 | } 54 | } 55 | 56 | function Install-Nerdctl { 57 | [CmdletBinding( 58 | SupportsShouldProcess = $true, 59 | ConfirmImpact = 'High' 60 | )] 61 | param( 62 | [string] 63 | [parameter(HelpMessage = "nerdctl version to use. Defaults to 'latest'")] 64 | $Version = "latest", 65 | 66 | [String] 67 | [parameter(HelpMessage = "Path to install nerdctl. Defaults to ~\program files\nerdctl")] 68 | $InstallPath = "$Env:ProgramFiles\nerdctl", 69 | 70 | [String] 71 | [parameter(HelpMessage = "Path to download files. Defaults to user's Downloads folder")] 72 | $DownloadPath = "$HOME\Downloads", 73 | 74 | [String[]] 75 | [parameter(HelpMessage = "Specify nerdctl dependencies (All, Containerd, Buildkit, WinCNIPlugin) to install")] 76 | $Dependencies, 77 | 78 | [string] 79 | [Parameter(HelpMessage = 'OS architecture to download files for. Default is $env:PROCESSOR_ARCHITECTURE')] 80 | [ValidateSet('amd64', '386', "arm", "arm64")] 81 | $OSArchitecture = $env:PROCESSOR_ARCHITECTURE, 82 | 83 | [Switch] 84 | [parameter(HelpMessage = "Installs nerdctl (and its dependencies if specified) even if the tool already exists at the specified path")] 85 | $Force 86 | ) 87 | 88 | begin { 89 | # Check if Containerd is alread installed 90 | $isInstalled = -not (Test-EmptyDirectory -Path "$InstallPath") 91 | 92 | $toInstall = @("nerdctl") 93 | 94 | $dependencies = Get-NerdctlDependencies -Dependencies $dependencies 95 | if ($dependencies) { 96 | $toInstall += $dependencies 97 | } 98 | 99 | $WhatIfMessage = "nerdctl will be installed at '$installPath'" 100 | if ($isInstalled) { 101 | $WhatIfMessage = "nerdctl will be uninstalled and reinstalled at '$InstallPath'" 102 | } 103 | if ($dependencies) { 104 | $WhatIfMessage = "nerdctl and its dependencies (Containerd, Buildkit, WinCNIPlugin) will be installed" 105 | } 106 | } 107 | 108 | process { 109 | if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { 110 | # Check if nerdctl already exists at specified location 111 | if ($isInstalled) { 112 | $errMsg = "nerdctl already exists at '$InstallPath' or the directory is not empty." 113 | Write-Warning $errMsg 114 | 115 | # Uninstall if tool exists at specified location. Requires user consent 116 | try { 117 | Uninstall-Nerdctl -Path "$InstallPath" -Confirm:$false -Force:$Force | Out-Null 118 | } 119 | catch { 120 | Throw "nerdctl installation failed. $_" 121 | } 122 | } 123 | 124 | # Get nerdctl version to install if not specified 125 | if (!$Version) { 126 | $Version = Get-NerdctlLatestVersion 127 | } 128 | $Version = $Version.TrimStart('v') 129 | 130 | Write-Output "Downloading and installing nerdctl v$Version at $InstallPath" 131 | 132 | # Download files 133 | $downloadParams = @{ 134 | ToolName = "nerdctl" 135 | Repository = "$NERDCTL_REPO" 136 | Version = $Version 137 | OSArchitecture = $OSArchitecture 138 | DownloadPath = $DownloadPath 139 | ChecksumSchemaFile = $null 140 | FileFilterRegEx = $null 141 | } 142 | $downloadParamsProperties = [FileDownloadParameters]::new( 143 | $downloadParams.ToolName, 144 | $downloadParams.Repository, 145 | $downloadParams.Version, 146 | $downloadParams.OSArchitecture, 147 | $downloadParams.DownloadPath, 148 | $downloadParams.ChecksumSchemaFile, 149 | $downloadParams.FileFilterRegEx 150 | ) 151 | $sourceFile = Get-InstallationFile -FileParameters $downloadParamsProperties 152 | 153 | # Untar and install tool 154 | $params = @{ 155 | Feature = "nerdctl" 156 | InstallPath = $InstallPath 157 | SourceFile = $sourceFile 158 | EnvPath = $InstallPath 159 | cleanup = $true 160 | } 161 | Install-RequiredFeature @params 162 | 163 | Write-Output "nerdctl v$version successfully installed at $InstallPath" 164 | Write-Output "For nerdctl usage: run 'nerdctl -h'`n" 165 | 166 | # Install dependencies 167 | Write-Output "Installing nerdctl dependencies: $toinstall" 168 | Install-NerdctlDependencies -Dependencies $dependencies -OsArch $OSArchitecture -Force:$true 169 | } 170 | else { 171 | # Code that should be processed if doing a WhatIf operation 172 | # Must NOT change anything outside of the function / script 173 | return 174 | } 175 | } 176 | } 177 | 178 | 179 | # TODO: Implement this 180 | function Initialize-NerdctlToml { 181 | param( 182 | [parameter(HelpMessage = "Toml path. Defaults to ~\AppData\nerdctl\nerdctl.toml")] 183 | [String]$Path = "$env:APPDATA\nerdctl\nerdctl.toml" 184 | ) 185 | 186 | # https://github.com/containerd/nerdctl/blob/main/docs/config.md 187 | $nerdctlConfig = @" 188 | {} 189 | "@ 190 | 191 | $nerdctlConfig | Set-Content $Path -Force 192 | } 193 | 194 | function Uninstall-Nerdctl { 195 | [CmdletBinding( 196 | SupportsShouldProcess = $true, 197 | ConfirmImpact = 'High' 198 | )] 199 | param( 200 | [parameter(HelpMessage = "nerdctl path")] 201 | [String]$Path = "$Env:ProgramFiles\nerdctl", 202 | 203 | [parameter(HelpMessage = "Delete all nerdctl program files and program data")] 204 | [Switch] $Purge, 205 | 206 | [parameter(HelpMessage = "Bypass confirmation to uninstall nerdctl")] 207 | [Switch] $Force 208 | ) 209 | 210 | begin { 211 | $tool = 'nerdctl' 212 | if (!$Path) { 213 | $Path = Get-DefaultInstallPath -Tool "nerdctl" 214 | } 215 | 216 | $WhatIfMessage = "nerdctl will be uninstalled from '$Path'." 217 | if ($Purge) { 218 | $WhatIfMessage += " nerdctl program data will also be removed." 219 | } 220 | else { 221 | $WhatIfMessage += " nerdctl program data won't be removed. To remove program data, run 'Uninstall-Nerdctl' command without -Purge flag." 222 | } 223 | } 224 | 225 | process { 226 | if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { 227 | if (Test-EmptyDirectory -Path "$path") { 228 | Write-Output "$tool does not exist at '$Path' or the directory is empty" 229 | return 230 | } 231 | 232 | $consent = $force 233 | if (!$ENV:PESTER) { 234 | $consent = $force -or $PSCmdlet.ShouldContinue($Path, 'Are you sure you want to uninstall nerdctl?') 235 | } 236 | 237 | if (!$consent) { 238 | Write-Warning "$tool uninstallation cancelled." 239 | return 240 | } 241 | 242 | Write-Warning "Uninstalling preinstalled $tool at the path '$path'.`n$WhatIfMessage" 243 | try { 244 | if ($Purge) { 245 | # Remove all unused images, not just dangling ones 246 | $cmdOutput = Invoke-ExecutableCommand -Executable "$path\nerdctl.exe" -Arguments "system prune --all" 247 | if ($cmdOutput.ExitCode -ne 0) { 248 | Write-Warning "Couldn't prune images. $($cmdOutput.StandardError.ReadToEnd())" 249 | } 250 | } 251 | 252 | # Uninstall nerdctl 253 | Uninstall-NerdctlHelper -Path "$path" -Purge:$Purge 254 | } 255 | catch { 256 | Throw "Could not uninstall $tool. $_" 257 | } 258 | } 259 | else { 260 | # Code that should be processed if doing a WhatIf operation 261 | # Must NOT change anything outside of the function / script 262 | return 263 | } 264 | } 265 | } 266 | 267 | function Uninstall-NerdctlHelper { 268 | param( 269 | [ValidateNotNullOrEmpty()] 270 | [parameter(Mandatory = $true, HelpMessage = "nerdctl path")] 271 | [String]$Path, 272 | 273 | [parameter(HelpMessage = "Remove all program data for Containerd")] 274 | [Switch] $Purge 275 | ) 276 | 277 | if (Test-EmptyDirectory -Path "$Path") { 278 | Write-Error "nerdctl does not exist at '$Path' or the directory is empty." 279 | return 280 | } 281 | 282 | # Remove the folder where nerdctl is installed and related folders 283 | Remove-Item -Path "$Path" -Recurse -Force 284 | 285 | if ($Purge) { 286 | Write-Output "Purging nerdctl program data" 287 | 288 | # Remove ProgramData files 289 | Write-Warning "Removing nerdctl program data" 290 | Uninstall-ProgramFiles "$ENV:ProgramData\nerdctl" 291 | 292 | # Remove from env path 293 | Write-Warning "Removing nerdctl from env path" 294 | Remove-FeatureFromPath -Feature "nerdctl" 295 | } 296 | 297 | Write-Output "Successfully uninstalled nerdctl." 298 | } 299 | 300 | Export-ModuleMember -Function Get-NerdctlLatestVersion 301 | Export-ModuleMember -Function Install-Nerdctl 302 | Export-ModuleMember -Function Uninstall-Nerdctl 303 | Export-ModuleMember -Function Uninstall-NerdctlHelper 304 | Export-ModuleMember -Function Install-NerdctlDependencies 305 | -------------------------------------------------------------------------------- /containers-toolkit/containers-toolkit.psd1: -------------------------------------------------------------------------------- 1 | @{ 2 | # Script module or binary module file associated with this manifest. 3 | # RootModule = '' 4 | 5 | # Version number of this module. 6 | ModuleVersion = '0.0.0' 7 | 8 | # Supported PSEditions 9 | # CompatiblePSEditions = @() 10 | 11 | # ID used to uniquely identify this module 12 | GUID = '8a534dc0-6e6f-431b-9de8-29d4659af987' 13 | 14 | # Author of this module 15 | Author = 'Microsoft Corporation' 16 | 17 | # Company or vendor of this module 18 | CompanyName = 'Microsoft Corporation' 19 | 20 | # Copyright statement for this module 21 | Copyright = '(c) Microsoft Corporation. All rights reserved.' 22 | 23 | # Description of the functionality provided by this module 24 | Description = @" 25 | The Containers-Toolkit module contains PowerShell functions for downloading, installing, and configuring Containerd, Buildkit, nerdctl, and Windows CNI plugins for container networks. It also allows you to get a list of the container tools and their installation statuses. 26 | 27 | Configurations done with these functions are default configurations that allow you to get started with interacting with the tools. Further configurations may be necessary. 28 | You can find documentation for these functions here: [Containers-Toolkit Documentation](https://github.com/microsoft/containers-toolkit/tree/main/docs/command-reference.md) 29 | 30 | This module requires the HNS module to execute the "Initialize-NatNetwork" command. The Host Networking Service (HNS) and the Host Compute Service (HCS) work together to create containers and attach endpoints to a network. The HNS module is necessary because the HostNetworkingService module does not include the "New-HNSNetwork" cmdlet. 31 | 32 | Note that the HostNetworkingService module is available only when the Hyper-V Windows feature is enabled. 33 | "@ 34 | 35 | # Minimum version of the PowerShell engine required by this module 36 | PowerShellVersion = '5.0' 37 | 38 | # Name of the PowerShell host required by this module 39 | # PowerShellHostName = '' 40 | 41 | # Minimum version of the PowerShell host required by this module 42 | # PowerShellHostVersion = '' 43 | 44 | # Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only. 45 | # DotNetFrameworkVersion = '' 46 | 47 | # Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only. 48 | # ClrVersion = '' 49 | 50 | # Processor architecture (None, X86, Amd64) required by this module 51 | # ProcessorArchitecture = '' 52 | 53 | # Modules that must be imported into the global environment prior to importing this module 54 | # RequiredModules = @() 55 | 56 | # Assemblies that must be loaded prior to importing this module 57 | # RequiredAssemblies = @() 58 | 59 | # Script files (.ps1) that are run in the caller's environment prior to importing this module. 60 | # ScriptsToProcess = @() 61 | 62 | # Type files (.ps1xml) to be loaded when importing this module 63 | # TypesToProcess = @() 64 | 65 | # Format files (.ps1xml) to be loaded when importing this module 66 | # FormatsToProcess = @() 67 | 68 | # Modules to import as nested modules of the module specified in RootModule/ModuleToProcess 69 | NestedModules = @( 70 | 'Private\CommonToolUtilities.psm1', 71 | 'Private\UpdateEnvironmentPath.psm1', 72 | 'Public\AllToolsUtilities.psm1', 73 | 'Public\BuildkitTools.psm1', 74 | 'Public\ContainerdTools.psm1', 75 | 'Public\ContainerNetworkTools.psm1', 76 | 'Public\NerdctlTools.psm1' 77 | ) 78 | 79 | # Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export. 80 | FunctionsToExport = @( 81 | 'Show-ContainerTools', 82 | 'Install-ContainerTools', 83 | 'Get-BuildkitLatestVersion', 84 | 'Install-Buildkit', 85 | 'Register-BuildkitdService', 86 | 'Start-BuildkitdService', 87 | 'Stop-BuildkitdService', 88 | 'Uninstall-Buildkit', 89 | 'Get-ContainerdLatestVersion', 90 | 'Install-Containerd', 91 | 'Register-ContainerdService', 92 | 'Start-ContainerdService', 93 | 'Stop-ContainerdService', 94 | 'Uninstall-Containerd', 95 | 'Get-NerdctlLatestVersion', 96 | 'Install-Nerdctl', 97 | 'Uninstall-Nerdctl', 98 | 'Get-WinCNILatestVersion', 99 | 'Install-WinCNIPlugin', 100 | 'Initialize-NatNetwork', 101 | 'Uninstall-WinCNIPlugin' 102 | ) 103 | 104 | # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export. 105 | CmdletsToExport = @() 106 | 107 | # Variables to export from this module 108 | # VariablesToExport = @() 109 | 110 | # Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export. 111 | AliasesToExport = @( 112 | 'Start-Containerd', 113 | 'Stop-Containerd', 114 | 'Start-Buildkitd', 115 | 'Stop-Buildkitd' 116 | ) 117 | 118 | # DSC resources to export from this module 119 | # DscResourcesToExport = @() 120 | 121 | # List of all modules packaged with this module 122 | # ModuleList = @() 123 | 124 | # List of all files packaged with this module 125 | FileList = @( 126 | './Private/CommonToolUtilities.psm1', 127 | './Private/UpdateEnvironmentPath.psm1', 128 | './Public/AllToolsUtilities.psm1', 129 | './Public/BuildkitTools.psm1', 130 | './Public/ContainerdTools.psm1', 131 | './Public/ContainerNetworkTools.psm1', 132 | './Public/NerdctlTools.psm1' 133 | ) 134 | 135 | # Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell. 136 | PrivateData = @{ 137 | PSData = @{ 138 | # Tags applied to this module. These help with module discovery in online galleries. 139 | Tags = 'Containerd', 'Buildkit', 'nerdctl', 'Windows Containers', 'Container Tools' 140 | 141 | # A URL to the license for this module. 142 | LicenseUri = 'https://raw.githubusercontent.com/microsoft/containers-toolkit/main/LICENSE' 143 | 144 | # A URL to the main website for this project. 145 | ProjectUri = 'https://github.com/microsoft/containers-toolkit' 146 | 147 | # A URL to an icon representing this module. 148 | # IconUri = '' 149 | 150 | # ReleaseNotes of this module 151 | # ReleaseNotes = '' 152 | 153 | # Prerelease string of this module 154 | # Prerelease = '' 155 | 156 | # Flag to indicate whether the module requires explicit user acceptance for install/update/save 157 | RequireLicenseAcceptance = $true 158 | 159 | # External dependent modules of this module 160 | # ExternalModuleDependencies = @() 161 | 162 | } # End of PSData hashtable 163 | 164 | } # End of PrivateData hashtable 165 | 166 | # HelpInfo URI of this module 167 | # HelpInfoURI = '' 168 | 169 | # Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix. 170 | # DefaultCommandPrefix = '' 171 | } 172 | -------------------------------------------------------------------------------- /containers-toolkit/en-US/about_containers-toolkit.help.txt: -------------------------------------------------------------------------------- 1 | TOPIC 2 | about_containerstoolkit 3 | 4 | Containers-Toolkit contains PowerShell functions that allow you to download, 5 | install, and configure Containerd, BuildKit, nerdctl, and Windows CNI for 6 | container networks. 7 | 8 | SHORT DESCRIPTION 9 | Containers-Toolkit contains PowerShell functions that allow you to download, 10 | install, and configure Containerd, BuildKit, nerdctl, and Windows CNI for 11 | container networks. 12 | 13 | LONG DESCRIPTION 14 | This is a rudimentary module that allows to download, install, and configure 15 | Containerd, BuildKit, nerdctl, and Windows CNI for container networks. It 16 | also allows you to get the list of the container tools and their 17 | installation statuses. 18 | Configurations done with these functions are the default configurations that 19 | allow you to get started with interacting with the tools. Further 20 | configurations may be necessary. 21 | You can find documentation for these functions here: 22 | https://github.com/microsoft/containers-toolkit/tree/main/docs/command-reference.md 23 | This module requires the HNS module. To install these modules, refer to 24 | https://github.com/microsoft/containers-toolkit/tree/main/docs/README.md#prerequisites 25 | 26 | 27 | KEYWORDS 28 | - Containerd 29 | - BuildKit 30 | - nerdctl 31 | - CNI 32 | - Windows Containers 33 | - Microsoft Windows 34 | -------------------------------------------------------------------------------- /docs/About/Get-BuildkitLatestVersion.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Containers-Toolkit-help.xml 3 | Module Name: Containers-Toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Get-BuildkitLatestVersion 9 | 10 | ## SYNOPSIS 11 | 12 | Gets the latest BuildKit version number. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Get-BuildkitLatestVersion 18 | ``` 19 | 20 | ## DESCRIPTION 21 | 22 | Uses GitHub API to get the latest BuildKit release version from the moby/buildkit GitHub repository. 23 | 24 | ## EXAMPLES 25 | 26 | ### Example 1: Get latest BuildKit version 27 | 28 | This returns a string of the latest release version of BuildKit, e.g., v1.2.0. 29 | 30 | ```powershell 31 | PS C:\> Get-BuildkitLatestVersion 32 | 33 | v1.2.0 34 | ``` 35 | 36 | ## PARAMETERS 37 | 38 | ## INPUTS 39 | 40 | ## OUTPUTS 41 | 42 | ### String 43 | 44 | This is a string of the latest BuildKit release version. 45 | 46 | ## RELATED LINKS 47 | 48 | - [Install-BuildKit](Install-BuildKit.md) 49 | - [Register-BuildkitdService](Register-BuildkitdService.md) 50 | - [Start-BuildkitdService](Start-BuildkitdService.md) 51 | - [Stop-BuildkitdService](Stop-BuildkitdService.md) 52 | - [Uninstall-BuildKit](Uninstall-BuildKit.md) 53 | -------------------------------------------------------------------------------- /docs/About/Get-ContainerdLatestVersion.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Containers-Toolkit-help.xml 3 | Module Name: Containers-Toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Get-ContainerdLatestVersion 9 | 10 | ## SYNOPSIS 11 | 12 | Gets the latest Containerd version number. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Get-ContainerdLatestVersion 18 | ``` 19 | 20 | ## DESCRIPTION 21 | 22 | Uses GitHub API to get the latest Containerd release version from the containerd/containerd GitHub repository. 23 | 24 | ## EXAMPLES 25 | 26 | ### Example 1: Get latest Containerd version 27 | 28 | This returns a string of the latest release version of Containerd, e.g., v1.2.0. 29 | 30 | ```powershell 31 | PS C:\> Get-ContainerdLatestVersion 32 | 33 | v1.2.0 34 | ``` 35 | 36 | ## PARAMETERS 37 | 38 | ## INPUTS 39 | 40 | ## OUTPUTS 41 | 42 | ### String 43 | 44 | This is a string of the latest Containerd release version. 45 | 46 | ## RELATED LINKS 47 | 48 | - [Install-Containerd](Install-Containerd.md) 49 | - [Register-ContainerdService](Register-ContainerdService.md) 50 | - [Start-ContainerdService](Start-ContainerdService.md) 51 | - [Stop-ContainerdService](Stop-ContainerdService.md) 52 | - [Uninstall-Containerd](Uninstall-Containerd.md) 53 | -------------------------------------------------------------------------------- /docs/About/Get-NerdctlLatestVersion.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Containers-Toolkit-help.xml 3 | Module Name: Containers-Toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Get-NerdctlLatestVersion 9 | 10 | ## SYNOPSIS 11 | 12 | Gets the latest nerdctl version number. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Get-NerdctlLatestVersion 18 | ``` 19 | 20 | ## DESCRIPTION 21 | 22 | Uses GitHub API to get the latest nerdctl release version from the containerd/nerdctl GitHub repository. 23 | 24 | ## EXAMPLES 25 | 26 | ### Example 1: Get latest nerdctl version 27 | 28 | This returns a string of the latest release version of nerdctl, e.g., v1.2.0. 29 | 30 | ```powershell 31 | PS C:\> Get-NerdctlLatestVersion 32 | 33 | v1.2.0 34 | ``` 35 | 36 | ## PARAMETERS 37 | 38 | ## INPUTS 39 | 40 | ## OUTPUTS 41 | 42 | ### String 43 | 44 | This is a string of the latest nerdctl release version. 45 | 46 | ## RELATED LINKS 47 | 48 | - [Install-Nerdctl](Install-Nerdctl.md) 49 | - [Uninstall-Nerdctl](Uninstall-Nerdctl.md) 50 | -------------------------------------------------------------------------------- /docs/About/Get-WinCNILatestVersion.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Containers-Toolkit-help.xml 3 | Module Name: Containers-Toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Get-WinCNILatestVersion 9 | 10 | ## SYNOPSIS 11 | 12 | Gets the latest Windows CNI version number. 13 | 14 | ## SYNTAX 15 | 16 | ```Text 17 | Get-WinCNILatestVersion [-Repo ] 18 | ``` 19 | 20 | ## DESCRIPTION 21 | 22 | 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. 23 | 24 | ## EXAMPLES 25 | 26 | ### Example 1: Get latest nerdctl version 27 | 28 | This returns a string of the latest release version of Windows CNI, e.g., v1.2.0. 29 | 30 | ```powershell 31 | PS C:\> Get-WinCNILatestVersion 32 | 33 | v1.2.0 34 | ``` 35 | 36 | ## PARAMETERS 37 | 38 | ### -Repo 39 | 40 | Source repository for the CNI plugins. Accepted values are 'microsoft/windows-container-networking' and 'containernetworking/plugins'. 41 | 42 | ```yaml 43 | Type: String 44 | Parameter Sets: (All) 45 | Aliases: SourceRepo, Repository 46 | 47 | Required: False 48 | Position: Named 49 | Default value: microsoft/windows-container-networking 50 | Accept pipeline input: False 51 | Accept wildcard characters: False 52 | ``` 53 | 54 | ## OUTPUTS 55 | 56 | ### String 57 | 58 | This is a string of the latest CNI plugins release version. 59 | 60 | ## RELATED LINKS 61 | 62 | - [Install-WinCNIPlugin](Install-WinCNIPlugin.md) 63 | - [Uninstall-WinCNIPlugin](Uninstall-WinCNIPlugin.md) 64 | - [Initialize-NatNetwork](Initialize-NatNetwork.md) 65 | -------------------------------------------------------------------------------- /docs/About/Initialize-NatNetwork.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: containers-toolkit-help.xml 3 | Module Name: containers-toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Initialize-NatNetwork 9 | 10 | ## SYNOPSIS 11 | 12 | Initializes a NAT network. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Initialize-NatNetwork [[-NetworkName] ] [[-Gateway] ] [[-CIDR] ] 18 | [[-WinCNIVersion] ] [[-WinCNIPath] ] [-Force] [-WhatIf] [-Confirm] [] 19 | ``` 20 | 21 | ## DESCRIPTION 22 | 23 | Initializes a NAT network. 24 | 25 | ## EXAMPLES 26 | 27 | ### Example 1: Using defaults 28 | 29 | Initializes a NAT network using default values. 30 | 31 | ```powershell 32 | PS C:\> Initialize-NatNetwork 33 | ``` 34 | 35 | ### Example 2: Using defaults 36 | 37 | Initializes a NAT network using default values. 38 | 39 | ```powershell 40 | PS C:\> Initialize-NatNetwork -NetworkName 'natNW' -Gateway '192.168.0.5' -CIDR 32 41 | ``` 42 | 43 | ## PARAMETERS 44 | 45 | ### -CIDR 46 | 47 | Size of the subnet mask. Defaults to 16 48 | 49 | ```yaml 50 | Type: Int32 51 | Parameter Sets: (All) 52 | Aliases: 53 | 54 | Required: False 55 | Position: 2 56 | Default value: 16 57 | Accept pipeline input: False 58 | Accept wildcard characters: False 59 | ``` 60 | 61 | ### -Force 62 | 63 | Bypass confirmation to install any missing dependencies (Windows CNI plugins and HNS module) 64 | 65 | ```yaml 66 | Type: SwitchParameter 67 | Parameter Sets: (All) 68 | Aliases: 69 | 70 | Required: False 71 | Position: Named 72 | Default value: False 73 | Accept pipeline input: False 74 | Accept wildcard characters: False 75 | ``` 76 | 77 | ### -Gateway 78 | 79 | Gateway IP address. Defaults to default gateway address. 80 | 81 | ```yaml 82 | Type: String 83 | Parameter Sets: (All) 84 | Aliases: 85 | 86 | Required: False 87 | Position: 1 88 | Default value: None 89 | Accept pipeline input: False 90 | Accept wildcard characters: False 91 | ``` 92 | 93 | ### -NetworkName 94 | 95 | Name of the new network. Defaults to 'nat'. 96 | 97 | ```yaml 98 | Type: String 99 | Parameter Sets: (All) 100 | Aliases: 101 | 102 | Required: False 103 | Position: 0 104 | Default value: nat 105 | Accept pipeline input: False 106 | Accept wildcard characters: False 107 | ``` 108 | 109 | ### -WinCNIPath 110 | 111 | Absolute path to cni folder, e.g. ~\cni (not ~\cni\bin). 112 | 113 | ```yaml 114 | Type: String 115 | Parameter Sets: (All) 116 | Aliases: 117 | 118 | Required: False 119 | Position: 4 120 | Default value: $env:ProgramFiles\containerd\cni 121 | Accept pipeline input: False 122 | Accept wildcard characters: False 123 | ``` 124 | 125 | ### -WinCNIVersion 126 | 127 | Windows CNI plugins version to use. Defaults to latest version. 128 | 129 | ```yaml 130 | Type: String 131 | Parameter Sets: (All) 132 | Aliases: 133 | 134 | Required: False 135 | Position: 3 136 | Default value: latest 137 | Accept pipeline input: False 138 | Accept wildcard characters: False 139 | ``` 140 | 141 | ### -Confirm 142 | 143 | Prompts you for confirmation before running the cmdlet. 144 | 145 | ```yaml 146 | Type: SwitchParameter 147 | Parameter Sets: (All) 148 | Aliases: cf 149 | 150 | Required: False 151 | Position: Named 152 | Default value: False 153 | Accept pipeline input: False 154 | Accept wildcard characters: False 155 | ``` 156 | 157 | ### -WhatIf 158 | 159 | Shows what would happen if the cmdlet runs. The cmdlet is not run. 160 | 161 | ```yaml 162 | Type: SwitchParameter 163 | Parameter Sets: (All) 164 | Aliases: wi 165 | 166 | Required: False 167 | Position: Named 168 | Default value: False 169 | Accept pipeline input: False 170 | Accept wildcard characters: False 171 | ``` 172 | 173 | ### CommonParameters 174 | 175 | 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). 176 | 177 | ## NOTES 178 | 179 | The specified version must match the installed version. To avoid compatibility issues, it is recommended to install the latest version. 180 | 181 | If the CNI plugins are not found at the default or specified path, the user will be prompted to install them —unless `-Confirm` 182 | is explicitly set to `$false`, in which case the plugins will be installed automatically without prompting. 183 | 184 | If the user declines the installation, the NAT network setup operation will be terminated with a warning. 185 | 186 | ## RELATED LINKS 187 | 188 | - [Get-WinCNILatestVersion](Get-WinCNILatestVersion.md) 189 | - [Install-WinCNIPlugin](Install-WinCNIPlugin.md) 190 | - [Uninstall-WinCNIPlugin](Uninstall-WinCNIPlugin.md) 191 | -------------------------------------------------------------------------------- /docs/About/Install-Buildkit.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: containers-toolkit-help.xml 3 | Module Name: Containers-Toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Install-Buildkit 9 | 10 | ## SYNOPSIS 11 | 12 | Downloads and installs BuildKit. 13 | 14 | ## SYNTAX 15 | 16 | ### Install (Default) 17 | 18 | ``` 19 | Install-Buildkit [-Version ] [-InstallPath ] [-DownloadPath ] [-OSArchitecture ] 20 | [-Force] [-WhatIf] [-Confirm] [] 21 | ``` 22 | 23 | ### Setup 24 | 25 | ``` 26 | Install-Buildkit [-Version ] [-InstallPath ] [-DownloadPath ] [-RegisterService] 27 | [-WinCNIPath ] [-OSArchitecture ] [-Force] [-WhatIf] [-Confirm] [] 28 | ``` 29 | 30 | ## DESCRIPTION 31 | 32 | 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. 33 | We can get the path where Buildkit is installed using: 34 | 35 | ```PowerShell 36 | ((Get-Command -Name "buildkitd.exe").Source | Split-Path -Parent).TrimEnd("\bin") 37 | ``` 38 | 39 | **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. 40 | 41 | ## EXAMPLES 42 | 43 | ### Example 1: Using defaults 44 | 45 | Installs BuildKit using default version and path. 46 | 47 | ```powershell 48 | PS C:\> Install-BuildKit 49 | ``` 50 | 51 | ### Example 2: Using custom values 52 | 53 | Installs BuildKit version 0.12.2 at 'C:\Test\Path\buildkit' and adds 'C:\Test\Path\buildkit' in the environment path. 54 | 55 | ```powershell 56 | PS C:\> Install-BuildKit -Version "0.12.2" -InstallPath 'C:\Test\Path\buildkit' 57 | ``` 58 | 59 | ## PARAMETERS 60 | 61 | ### -DownloadPath 62 | 63 | Path to download files. Defaults to `$HOME\Downloads` 64 | 65 | ```yaml 66 | Type: String 67 | Parameter Sets: (All) 68 | Aliases: 69 | 70 | Required: False 71 | Position: Named 72 | Default value: $HOME\Downloads 73 | Accept pipeline input: False 74 | Accept wildcard characters: False 75 | ``` 76 | 77 | ### -Force 78 | 79 | Installs Buildkit even if the tool already exists at the specified path. 80 | 81 | ```yaml 82 | Type: SwitchParameter 83 | Parameter Sets: (All) 84 | Aliases: 85 | 86 | Required: False 87 | Position: Named 88 | Default value: False 89 | Accept pipeline input: False 90 | Accept wildcard characters: False 91 | ``` 92 | 93 | ### -InstallPath 94 | 95 | Path to install BuildKit. Defaults to `$ENV:ProgramFiles\BuildKit` 96 | 97 | ```yaml 98 | Type: String 99 | Parameter Sets: (All) 100 | Aliases: 101 | 102 | Required: False 103 | Position: Named 104 | Default value: $Env:ProgramFiles\Buildkit 105 | Accept pipeline input: False 106 | Accept wildcard characters: False 107 | ``` 108 | 109 | ### -OSArchitecture 110 | 111 | OS architecture to download files for. 112 | Default is `$env:PROCESSOR_ARCHITECTURE` 113 | 114 | ```yaml 115 | Type: String 116 | Parameter Sets: (All) 117 | Aliases: 118 | 119 | Required: False 120 | Position: Named 121 | Default value: $env:PROCESSOR_ARCHITECTURE 122 | Accept pipeline input: False 123 | Accept wildcard characters: False 124 | ``` 125 | 126 | ### -RegisterService 127 | 128 | Register and start the buildkitd Service. 129 | 130 | ```yaml 131 | Type: SwitchParameter 132 | Parameter Sets: (All) 133 | Aliases: Setup 134 | 135 | Required: False 136 | Position: Named 137 | Default value: None 138 | Accept pipeline input: False 139 | Accept wildcard characters: False 140 | ``` 141 | 142 | ### -Version 143 | 144 | Buildkit version to use. Defaults to latest version. 145 | 146 | ```yaml 147 | Type: String 148 | Parameter Sets: (All) 149 | Aliases: 150 | 151 | Required: False 152 | Position: Named 153 | Default value: latest 154 | Accept pipeline input: False 155 | Accept wildcard characters: False 156 | ``` 157 | 158 | ### -WinCNIPath 159 | 160 | Path where Windows CNI plugins are installed. Defaults to $ENV:ProgramFiles\Containerd\cni 161 | 162 | ```yaml 163 | Type: String 164 | Parameter Sets: Setup 165 | Aliases: 166 | 167 | Required: False 168 | Position: Named 169 | Default value: $ENV:ProgramFiles\Containerd\cni 170 | Accept pipeline input: False 171 | Accept wildcard characters: False 172 | ``` 173 | 174 | ### -Confirm 175 | 176 | Prompts you for confirmation before running the cmdlet. 177 | 178 | ```yaml 179 | Type: SwitchParameter 180 | Parameter Sets: (All) 181 | Aliases: cf 182 | 183 | Required: False 184 | Position: Named 185 | Default value: False 186 | Accept pipeline input: False 187 | Accept wildcard characters: False 188 | ``` 189 | 190 | ### -WhatIf 191 | 192 | Shows what would happen if the cmdlet runs. The cmdlet is not run. 193 | 194 | ```yaml 195 | Type: SwitchParameter 196 | Parameter Sets: (All) 197 | Aliases: wi 198 | 199 | Required: False 200 | Position: Named 201 | Default value: False 202 | Accept pipeline input: False 203 | Accept wildcard characters: False 204 | ``` 205 | 206 | ### CommonParameters 207 | 208 | 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). 209 | 210 | ## RELATED LINKS 211 | 212 | - [Get-BuildkitLatestVersion](Get-BuildkitLatestVersion.md) 213 | - [Register-BuildkitdService](Register-BuildkitdService.md) 214 | - [Start-BuildkitdService](Start-BuildkitdService.md) 215 | - [Stop-BuildkitdService](Stop-BuildkitdService.md) 216 | - [Uninstall-BuildKit](Uninstall-BuildKit.md) 217 | -------------------------------------------------------------------------------- /docs/About/Install-ContainerTools.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: containers-toolkit-help.xml 3 | Module Name: containers-toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Install-ContainerTools 9 | 10 | ## SYNOPSIS 11 | 12 | Downloads and installs container tool (Containerd, BuildKit, and nerdctl). 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Install-ContainerTools [[-ContainerDVersion] ] [[-BuildKitVersion] ] 18 | [[-NerdCTLVersion] ] [[-InstallPath] ] [[-DownloadPath] ] [-RegisterServices] 19 | [-Force] [-WhatIf] [-Confirm] [] 20 | ``` 21 | 22 | ## DESCRIPTION 23 | 24 | Downloads container tool (Containerd, BuildKit, and nerdctl) asynchronously and installs them at the specified location. 25 | 26 | ## EXAMPLES 27 | 28 | ### Example 1: Using defaults 29 | 30 | Install the latest versions of Containerd, BuildKit, and nerdctl at the default path 31 | 32 | ```powershell 33 | PS C:\> Install-ContainerTools 34 | ``` 35 | 36 | ### Example 2: Download Containerd version 1.6.8 and default nerdctl and BuildKit versions 37 | 38 | Download Containerd version 1.6.8 and default nerdctl and BuildKit versions 39 | 40 | ```powershell 41 | PS C:\> Install-ContainerTools -ContainerDVersion 1.6.8 42 | ``` 43 | 44 | ### Example 3: Register and Start Containerd and Buildkitd services and set up NAT network 45 | 46 | Register and Start Containerd and Buildkitd services and set up NAT network 47 | 48 | ```powershell 49 | PS C:\> Install-ContainerTools -RegisterServices 50 | ``` 51 | 52 | ## PARAMETERS 53 | 54 | ### -BuildKitVersion 55 | 56 | BuildKit version to install 57 | 58 | ```yaml 59 | Type: String 60 | Parameter Sets: (All) 61 | Aliases: 62 | 63 | Required: False 64 | Position: 1 65 | Default value: Latest version 66 | Accept pipeline input: False 67 | Accept wildcard characters: False 68 | ``` 69 | 70 | ### -ContainerDVersion 71 | 72 | Containerd version to install 73 | 74 | ```yaml 75 | Type: String 76 | Parameter Sets: (All) 77 | Aliases: 78 | 79 | Required: False 80 | Position: 0 81 | Default value: Latest version 82 | Accept pipeline input: False 83 | Accept wildcard characters: False 84 | ``` 85 | 86 | ### -DownloadPath 87 | 88 | Path to download files. 89 | Defaults to user's Downloads folder, `$HOME\Downloads` 90 | 91 | ```yaml 92 | Type: String 93 | Parameter Sets: (All) 94 | Aliases: 95 | 96 | Required: False 97 | Position: 4 98 | Default value: $HOME\Downloads 99 | Accept pipeline input: False 100 | Accept wildcard characters: False 101 | ``` 102 | 103 | ### -Force 104 | 105 | Force container tools uninstallation (if it exists) without any confirmation prompts 106 | 107 | ```yaml 108 | Type: SwitchParameter 109 | Parameter Sets: (All) 110 | Aliases: 111 | 112 | Required: False 113 | Position: Named 114 | Default value: False 115 | Accept pipeline input: False 116 | Accept wildcard characters: False 117 | ``` 118 | 119 | ### -InstallPath 120 | 121 | Path to Install files. 122 | Defaults to Program Files, \`$Env:ProgramFiles\` 123 | 124 | ```yaml 125 | Type: String 126 | Parameter Sets: (All) 127 | Aliases: 128 | 129 | Required: False 130 | Position: 3 131 | Default value: $Env:ProgramFiles 132 | Accept pipeline input: False 133 | Accept wildcard characters: False 134 | ``` 135 | 136 | ### -NerdCTLVersion 137 | 138 | nerdctl version to install 139 | 140 | ```yaml 141 | Type: String 142 | Parameter Sets: (All) 143 | Aliases: 144 | 145 | Required: False 146 | Position: 2 147 | Default value: Latest version 148 | Accept pipeline input: False 149 | Accept wildcard characters: False 150 | ``` 151 | 152 | ### -RegisterServices 153 | 154 | Register and Start Containerd and Buildkitd services and set up NAT network. 155 | 156 | ```yaml 157 | Type: SwitchParameter 158 | Parameter Sets: (All) 159 | Aliases: 160 | 161 | Required: False 162 | Position: Named 163 | Default value: False 164 | Accept pipeline input: False 165 | Accept wildcard characters: False 166 | ``` 167 | 168 | ### -Confirm 169 | 170 | Prompts for confirmation before running the cmdlet. 171 | For more information, see the following articles: 172 | 173 | ```yaml 174 | Type: SwitchParameter 175 | Parameter Sets: (All) 176 | Aliases: cf 177 | 178 | Required: False 179 | Position: Named 180 | Default value: False 181 | Accept pipeline input: False 182 | Accept wildcard characters: False 183 | ``` 184 | 185 | ### -WhatIf 186 | 187 | Shows what would happen if the cmdlet runs. 188 | The cmdlet isn't run. 189 | 190 | ```yaml 191 | Type: SwitchParameter 192 | Parameter Sets: (All) 193 | Aliases: wi 194 | 195 | Required: False 196 | Position: Named 197 | Default value: False 198 | Accept pipeline input: False 199 | Accept wildcard characters: False 200 | ``` 201 | 202 | ### CommonParameters 203 | 204 | 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). 205 | 206 | ## RELATED LINKS 207 | 208 | - [Install-Containerd](Install-Containerd.md) 209 | - [Install-BuildKit](Install-BuildKit.md) 210 | - [Install-Nerdctl](Install-Nerdctl.md) 211 | -------------------------------------------------------------------------------- /docs/About/Install-Containerd.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Containers-Toolkit-help.xml 3 | Module Name: Containers-Toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Install-Containerd 9 | 10 | ## SYNOPSIS 11 | 12 | Downloads and installs Containerd. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Install-Containerd [[-Version] ] [[-InstallPath] ] [[-DownloadPath] ] 18 | [-RegisterService] [-OSArchitecture ] [-Force] [-WhatIf] [-Confirm] [] 19 | ``` 20 | 21 | ## DESCRIPTION 22 | 23 | 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. 24 | We can get the path where it is installed using: 25 | 26 | ```PowerShell 27 | ((Get-Command -Name containerd.exe).Source | Split-Path -Parent).TrimEnd("\bin") 28 | ``` 29 | 30 | **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. 31 | 32 | ## EXAMPLES 33 | 34 | ### Example 1: Using defaults 35 | 36 | Installs Containerd using defaults 37 | 38 | ```powershell 39 | PS C:\> Install-Containerd 40 | ``` 41 | 42 | ### Example 2: Using custom values 43 | 44 | Installs Containerd version 1.7.7 at 'C:\Test\Path\containerd' and adds 'C:\Test\Path\containerd' in the environment path. 45 | 46 | ```powershell 47 | PS C:\> Install-Containerd -Version "1.7.7" -InstallPath 'C:\Test\Path\Containerd' 48 | 49 | ## PARAMETERS 50 | 51 | ### -DownloadPath 52 | 53 | Path to download files. Defaults to `$HOME\Downloads` 54 | 55 | ```yaml 56 | Type: String 57 | Parameter Sets: (All) 58 | Aliases: 59 | 60 | Required: False 61 | Position: 2 62 | Default value: $HOME\Downloads 63 | Accept pipeline input: False 64 | Accept wildcard characters: False 65 | ``` 66 | 67 | ### -Force 68 | 69 | Installs Containerd even if the tool already exists at the specified path. 70 | 71 | ```yaml 72 | Type: SwitchParameter 73 | Parameter Sets: (All) 74 | Aliases: 75 | 76 | Required: False 77 | Position: Named 78 | Default value: False 79 | Accept pipeline input: False 80 | Accept wildcard characters: False 81 | ``` 82 | 83 | ### -InstallPath 84 | 85 | Path to install Containerd. Defaults to Defaults to `$ENV:ProgramFiles\containerd` 86 | 87 | ```yaml 88 | Type: String 89 | Parameter Sets: (All) 90 | Aliases: 91 | 92 | Required: False 93 | Position: 1 94 | Default value: $ENV:ProgramFiles\containerd 95 | Accept pipeline input: False 96 | Accept wildcard characters: False 97 | ``` 98 | 99 | ### -OSArchitecture 100 | 101 | OS architecture to download files for. Default is `$env:PROCESSOR_ARCHITECTURE` 102 | 103 | ```yaml 104 | Type: String 105 | Parameter Sets: (All) 106 | Aliases: 107 | 108 | Required: False 109 | Position: Named 110 | Default value: $env:PROCESSOR_ARCHITECTURE 111 | Accept pipeline input: False 112 | Accept wildcard characters: False 113 | ``` 114 | 115 | ### -RegisterService 116 | 117 | Register and start the Containerd Service. 118 | 119 | ```yaml 120 | Type: SwitchParameter 121 | Parameter Sets: (All) 122 | Aliases: Setup 123 | 124 | Required: False 125 | Position: Named 126 | Default value: None 127 | Accept pipeline input: False 128 | Accept wildcard characters: False 129 | ``` 130 | 131 | ### -Version 132 | 133 | ContainerD version to use. Defaults to latest version 134 | 135 | ```yaml 136 | Type: String 137 | Parameter Sets: (All) 138 | Aliases: 139 | 140 | Required: False 141 | Position: 0 142 | Default value: latest 143 | Accept pipeline input: False 144 | Accept wildcard characters: False 145 | ``` 146 | 147 | ### -Confirm 148 | 149 | Prompts you for confirmation before running the cmdlet. 150 | 151 | ```yaml 152 | Type: SwitchParameter 153 | Parameter Sets: (All) 154 | Aliases: cf 155 | 156 | Required: False 157 | Position: Named 158 | Default value: False 159 | Accept pipeline input: False 160 | Accept wildcard characters: False 161 | ``` 162 | 163 | ### -WhatIf 164 | 165 | Shows what would happen if the cmdlet runs. The cmdlet is not run. 166 | 167 | ```yaml 168 | Type: SwitchParameter 169 | Parameter Sets: (All) 170 | Aliases: wi 171 | 172 | Required: False 173 | Position: Named 174 | Default value: None 175 | Accept pipeline input: False 176 | Accept wildcard characters: False 177 | ``` 178 | 179 | ### CommonParameters 180 | 181 | 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). 182 | 183 | ## RELATED LINKS 184 | 185 | - [Get-ContainerdLatestVersion](Get-ContainerdLatestVersion.md) 186 | - [Register-ContainerdService](Register-ContainerdService.md) 187 | - [Start-ContainerdService](Start-ContainerdService.md) 188 | - [Stop-ContainerdService](Stop-ContainerdService.md) 189 | - [Uninstall-Containerd](Uninstall-Containerd.md) 190 | -------------------------------------------------------------------------------- /docs/About/Install-Nerdctl.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: containers-toolkit-help.xml 3 | Module Name: containers-toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Install-Nerdctl 9 | 10 | ## SYNOPSIS 11 | 12 | Downloads and installs nerdctl. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Install-Nerdctl [[-Version] ] [[-InstallPath] ] [[-DownloadPath] ] 18 | [[-Dependencies] ] [-OSArchitecture ] [-Force] [-WhatIf] [-Confirm] [] 19 | ``` 20 | 21 | ## DESCRIPTION 22 | 23 | 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. 24 | 25 | ## EXAMPLES 26 | 27 | ### Example 1: Using defaults 28 | 29 | Installs nerdctl using default version and path. 30 | 31 | ```powershell 32 | PS C:\> Install-Nerdctl 33 | ``` 34 | 35 | ### Example 2: Using custom values 36 | 37 | Installs nerdctl version 1.6.1 at 'C:\Test\Path\nerdctl' and adds 'C:\Test\Path\nerdctl' in the environment path. 38 | 39 | ```powershell 40 | PS C:\> Install-Nerdctl -Version "1.6.1" -InstallPath 'C:\Test\Path\nerdctl' 41 | ``` 42 | 43 | ## PARAMETERS 44 | 45 | ### -Dependencies 46 | 47 | Specify the nerdctl dependencies (All, Containerd, Buildkit, WinCNIPlugin) to install. 48 | 49 | ```yaml 50 | Type: String[] 51 | Parameter Sets: (All) 52 | Aliases: 53 | 54 | Required: False 55 | Position: 3 56 | Default value: None 57 | Accept pipeline input: False 58 | Accept wildcard characters: False 59 | ``` 60 | 61 | ### -DownloadPath 62 | 63 | Path to download files. Defaults to user's Downloads folder, `$HOME\Downloads` 64 | 65 | ```yaml 66 | Type: String 67 | Parameter Sets: (All) 68 | Aliases: 69 | 70 | Required: False 71 | Position: 2 72 | Default value: $HOME\Downloads 73 | Accept pipeline input: False 74 | Accept wildcard characters: False 75 | ``` 76 | 77 | ### -Force 78 | 79 | Force nerdctl (and its dependecies if specified) uninstallation (if it exists) without any confirmation prompts 80 | 81 | ```yaml 82 | Type: SwitchParameter 83 | Parameter Sets: (All) 84 | Aliases: 85 | 86 | Required: False 87 | Position: Named 88 | Default value: False 89 | Accept pipeline input: False 90 | Accept wildcard characters: False 91 | ``` 92 | 93 | ### -InstallPath 94 | 95 | Path to install nerdctl. 96 | Defaults to `$ENV:ProgramFiles\nerdctl` 97 | 98 | ```yaml 99 | Type: String 100 | Parameter Sets: (All) 101 | Aliases: 102 | 103 | Required: False 104 | Position: 1 105 | Default value: $ENV:ProgramFiles\nerdctl` 106 | Accept pipeline input: False 107 | Accept wildcard characters: False 108 | ``` 109 | 110 | ### -OSArchitecture 111 | 112 | OS architecture to download files for. 113 | Default is `$env:PROCESSOR_ARCHITECTURE` 114 | 115 | ```yaml 116 | Type: String 117 | Parameter Sets: (All) 118 | Aliases: 119 | 120 | Required: False 121 | Position: Named 122 | Default value: $env:PROCESSOR_ARCHITECTURE 123 | Accept pipeline input: False 124 | Accept wildcard characters: False 125 | ``` 126 | 127 | ### -Version 128 | 129 | nerdctl version to install. 130 | Defaults to latest version. 131 | 132 | ```yaml 133 | Type: String 134 | Parameter Sets: (All) 135 | Aliases: 136 | 137 | Required: False 138 | Position: 0 139 | Default value: latest 140 | Accept pipeline input: False 141 | Accept wildcard characters: False 142 | ``` 143 | 144 | ### -Confirm 145 | 146 | Prompts for confirmation before running the cmdlet. 147 | 148 | ```yaml 149 | Type: SwitchParameter 150 | Parameter Sets: (All) 151 | Aliases: cf 152 | 153 | Required: False 154 | Position: Named 155 | Default value: False 156 | Accept pipeline input: False 157 | Accept wildcard characters: False 158 | ``` 159 | 160 | ### -WhatIf 161 | 162 | Shows what would happen if the cmdlet runs. 163 | The cmdlet is not run. 164 | 165 | ```yaml 166 | Type: SwitchParameter 167 | Parameter Sets: (All) 168 | Aliases: wi 169 | 170 | Required: False 171 | Position: Named 172 | Default value: False 173 | Accept pipeline input: False 174 | Accept wildcard characters: False 175 | ``` 176 | 177 | ### CommonParameters 178 | 179 | 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). 180 | 181 | ## RELATED LINKS 182 | 183 | - [Get-NerdctlLatestVersion](Get-NerdctlLatestVersion.md) 184 | - [Uninstall-Nerdctl](Uninstall-Nerdctl.md) 185 | -------------------------------------------------------------------------------- /docs/About/Install-WinCNIPlugin.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: containers-toolkit-help.xml 3 | Module Name: containers-toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Install-WinCNIPlugin 9 | 10 | ## SYNOPSIS 11 | 12 | Downloads and installs CNI plugin. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Install-WinCNIPlugin [[-WinCNIVersion] ] [[-WinCNIPath] ] [-SourceRepo ] 18 | [-OSArchitecture ] [-Force] [-WhatIf] [-Confirm] [] 19 | ``` 20 | 21 | ## DESCRIPTION 22 | 23 | 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. 24 | 25 | ## EXAMPLES 26 | 27 | ### Example 1: Using defaults 28 | 29 | Installs latest Windows CNI plugin at the default path. 30 | 31 | ```powershell 32 | PS C:\> Install-WinCNIPlugin 33 | ``` 34 | 35 | ### Example 2: Using custom values 36 | 37 | Installs Windows CNI plugin version 0.2.0 in the default path. 38 | 39 | ```powershell 40 | PS C:\> Install-WinCNIPlugin -WinCNIVersion "0.2.0" 41 | ``` 42 | 43 | ## PARAMETERS 44 | 45 | ### -Force 46 | 47 | Force CNI plugins uninstallation (if it exists) without any confirmation prompts. 48 | 49 | ```yaml 50 | Type: SwitchParameter 51 | Parameter Sets: (All) 52 | Aliases: 53 | 54 | Required: False 55 | Position: Named 56 | Default value: False 57 | Accept pipeline input: False 58 | Accept wildcard characters: False 59 | ``` 60 | 61 | ### -OSArchitecture 62 | 63 | OS architecture to download files for. 64 | Default is `$env:PROCESSOR_ARCHITECTURE` 65 | 66 | ```yaml 67 | Type: String 68 | Parameter Sets: (All) 69 | Aliases: 70 | 71 | Required: False 72 | Position: Named 73 | Default value: $env:PROCESSOR_ARCHITECTURE 74 | Accept pipeline input: False 75 | Accept wildcard characters: False 76 | ``` 77 | 78 | ### -SourceRepo 79 | 80 | Source of the Windows CNI plugins. 81 | Defaults to 'microsoft/windows-container-networking' 82 | 83 | ```yaml 84 | Type: String 85 | Parameter Sets: (All) 86 | Aliases: 87 | 88 | Required: False 89 | Position: Named 90 | Default value: "microsoft/windows-container-networking" 91 | Accept pipeline input: False 92 | Accept wildcard characters: False 93 | ``` 94 | 95 | ### -WinCNIPath 96 | 97 | Location to install Windows CNI. 98 | 99 | ```yaml 100 | Type: String 101 | Parameter Sets: (All) 102 | Aliases: 103 | 104 | Required: False 105 | Position: 1 106 | Default value: $Env:ProgramFiles\Containerd 107 | Accept pipeline input: False 108 | Accept wildcard characters: False 109 | ``` 110 | 111 | ### -WinCNIVersion 112 | 113 | Windows CNI plugin version to use. 114 | Defaults to latest version. 115 | 116 | ```yaml 117 | Type: String 118 | Parameter Sets: (All) 119 | Aliases: 120 | 121 | Required: False 122 | Position: 0 123 | Default value: latest 124 | Accept pipeline input: False 125 | Accept wildcard characters: False 126 | ``` 127 | 128 | ### -Confirm 129 | 130 | Prompts for confirmation before running the cmdlet. 131 | 132 | ```yaml 133 | Type: SwitchParameter 134 | Parameter Sets: (All) 135 | Aliases: cf 136 | 137 | Required: False 138 | Position: Named 139 | Default value: False 140 | Accept pipeline input: False 141 | Accept wildcard characters: False 142 | ``` 143 | 144 | ### -WhatIf 145 | 146 | Shows what would happen if the cmdlet runs. 147 | The cmdlet is not run. 148 | 149 | ```yaml 150 | Type: SwitchParameter 151 | Parameter Sets: (All) 152 | Aliases: wi 153 | 154 | Required: False 155 | Position: Named 156 | Default value: False 157 | Accept pipeline input: False 158 | Accept wildcard characters: False 159 | ``` 160 | 161 | ### CommonParameters 162 | 163 | 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). 164 | 165 | ## RELATED LINKS 166 | 167 | - [Get-WinCNILatestVersion](Get-WinCNILatestVersion.md) 168 | - [Initialize-NatNetwork](Initialize-NatNetwork.md) 169 | -------------------------------------------------------------------------------- /docs/About/Register-BuildkitdService.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: containers-toolkit-help.xml 3 | Module Name: containers-toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Register-BuildkitdService 9 | 10 | ## SYNOPSIS 11 | 12 | Registers the buildkitd service with a prompt to either register with the Containerd CNI configurations (0-containerd-nat.conf) or not. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Register-BuildkitdService [[-WinCNIPath] ] [[-BuildKitPath] ] [-Start] [-WhatIf] 18 | [] 19 | ``` 20 | 21 | ## DESCRIPTION 22 | 23 | Registers the buildkitd service with a prompt to either register with the Containerd CNI configurations (0-containerd-nat.conf) or not. 24 | 25 | ## EXAMPLES 26 | 27 | ### Example 1: Initializes buildkitd service with the defaults 28 | 29 | ```powershell 30 | PS C:\> Register-BuildkitdService 31 | ``` 32 | 33 | Registers buildkitd with the default Containerd configurations file `0-containerd-nat.conf` if it is available. 34 | 35 | ### Example 2: Initializes buildkitd service with the defaults 36 | 37 | ```powershell 38 | PS C:\> Register-BuildkitdService -WinCNIPath '$ENV:ProgramFiles\containerd\cni' -BuildKitPath '$ENV:ProgramFiles\Buildkit' 39 | ``` 40 | 41 | Registers buildkitd with the default Containerd configurations file `0-containerd-nat.conf` found at `$ENV:ProgramFiles\containerd\cni`. 42 | 43 | ## PARAMETERS 44 | 45 | ### -BuildKitPath 46 | 47 | Path where BuildKit is installed. If not provided, it defaults to BuildKit path in the environment path variable or `$Env:ProgramFiles\Buildkit` 48 | 49 | ```yaml 50 | Type: String 51 | Parameter Sets: (All) 52 | Aliases: 53 | 54 | Required: False 55 | Position: 1 56 | Default value: $Env:ProgramFiles\Buildkit 57 | Accept pipeline input: False 58 | Accept wildcard characters: False 59 | ``` 60 | 61 | ### -Force 62 | 63 | Bypass confirmation to register buildkitd service 64 | 65 | ```yaml 66 | Type: SwitchParameter 67 | Parameter Sets: (All) 68 | Aliases: 69 | 70 | Required: False 71 | Position: Named 72 | Default value: False 73 | Accept pipeline input: False 74 | Accept wildcard characters: False 75 | ``` 76 | 77 | ### -Start 78 | 79 | Specify to start Buildkitd service after registration is complete 80 | 81 | ```yaml 82 | Type: SwitchParameter 83 | Parameter Sets: (All) 84 | Aliases: 85 | 86 | Required: False 87 | Position: Named 88 | Default value: False 89 | Accept pipeline input: False 90 | Accept wildcard characters: False 91 | ``` 92 | 93 | ### -WinCNIPath 94 | 95 | Path where Windows CNI plugin is installed. 96 | If not provided, it defaults to Containerd path in the environment path variable or `$Env:ProgramFiles\Containerd` 97 | 98 | ```yaml 99 | Type: String 100 | Parameter Sets: (All) 101 | Aliases: 102 | 103 | Required: False 104 | Position: 0 105 | Default value: $Env:ProgramFiles\Containerd 106 | Accept pipeline input: False 107 | Accept wildcard characters: False 108 | ``` 109 | 110 | ### -Confirm 111 | 112 | Prompts you for confirmation before running the cmdlet. 113 | 114 | ```yaml 115 | Type: SwitchParameter 116 | Parameter Sets: (All) 117 | Aliases: cf 118 | 119 | Required: False 120 | Position: Named 121 | Default value: False 122 | Accept pipeline input: False 123 | Accept wildcard characters: False 124 | ``` 125 | 126 | ### -WhatIf 127 | 128 | Shows what would happen if the cmdlet runs. 129 | The cmdlet is not run. 130 | 131 | ```yaml 132 | Type: SwitchParameter 133 | Parameter Sets: (All) 134 | Aliases: wi 135 | 136 | Required: False 137 | Position: Named 138 | Default value: False 139 | Accept pipeline input: False 140 | Accept wildcard characters: False 141 | ``` 142 | 143 | ### CommonParameters 144 | 145 | 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). 146 | 147 | ## NOTES 148 | 149 | When the `0-containerd-nat.conf` does not exist, the user is prompted to register buildkitd service with or without this file. 150 | 151 | ```Output 152 | Buildkit conf file not found at ~\cni\conf\0-containerd-nat.conf. 153 | Do you want to register buildkit service without Containerd cni configuration? 154 | [Y] Yes [N] No [?] Help (default is "Y"): 155 | ``` 156 | 157 | - If a user enters `Y` (default), the user consents to register buildkitd service without the default Containerd NAT configuration file. 158 | - If a user enters `N`, buildkitd service is not registered and the user has to register the service themselves. 159 | 160 | ## RELATED LINKS 161 | 162 | - [Get-BuildkitLatestVersion](Get-BuildkitLatestVersion.md) 163 | - [Install-Buildkit](Install-Buildkit.md) 164 | - [Start-BuildkitdService](Start-BuildkitdService.md) 165 | - [Stop-BuildkitdService](Stop-BuildkitdService.md) 166 | - [Uninstall-Buildkit](Uninstall-Buildkit.md) 167 | -------------------------------------------------------------------------------- /docs/About/Register-ContainerdService.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Containers-Toolkit-help.xml 3 | Module Name: Containers-Toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Register-ContainerdService 9 | 10 | ## SYNOPSIS 11 | 12 | Create a default Containerd configuration file called `config.toml` at the Containerd path and registers the Containerd service. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Register-ContainerdService [[-ContainerdPath] ] [-Start] [] 18 | ``` 19 | 20 | ## DESCRIPTION 21 | 22 | Create a default Containerd configuration file called `config.toml` at the Containerd path and registers the Containerd service. 23 | 24 | ## EXAMPLES 25 | 26 | ### Example 1: Using default Containerd path 27 | 28 | Creates the config.toml file at the default Containerd path and registers the Containerd service. 29 | 30 | ```powershell 31 | PS C:\> Register-ContainerdService 32 | ``` 33 | 34 | ### Example 2: Using custom path 35 | 36 | Creates the config.toml file at the provided Containerd path and registers the Containerd service. If Containerd does not exist at the provided path, execution fails with an error. 37 | 38 | ```powershell 39 | PS C:\> Register-ContainerdService -ContainerdPath 'C:\Test\Path\containerd' 40 | ``` 41 | 42 | ## PARAMETERS 43 | 44 | ### -ContainerdPath 45 | 46 | Path where Containerd is installed. 47 | 48 | ```yaml 49 | Type: String 50 | Parameter Sets: (All) 51 | Aliases: 52 | 53 | Required: False 54 | Position: 0 55 | Default value: $Env:ProgramFiles\containerd 56 | Accept pipeline input: False 57 | Accept wildcard characters: False 58 | ``` 59 | 60 | ### -Force 61 | 62 | Bypass confirmation to register containerd service 63 | 64 | ```yaml 65 | Type: SwitchParameter 66 | Parameter Sets: (All) 67 | Aliases: 68 | 69 | Required: False 70 | Position: Named 71 | Default value: False 72 | Accept pipeline input: False 73 | Accept wildcard characters: False 74 | ``` 75 | 76 | ### -Start 77 | 78 | Specify to start Containerd service after registration is complete 79 | 80 | ```yaml 81 | Type: SwitchParameter 82 | Parameter Sets: (All) 83 | Aliases: 84 | 85 | Required: False 86 | Position: Named 87 | Default value: False 88 | Accept pipeline input: False 89 | Accept wildcard characters: False 90 | ``` 91 | 92 | ### -Confirm 93 | 94 | Prompts you for confirmation before running the cmdlet. 95 | 96 | ```yaml 97 | Type: SwitchParameter 98 | Parameter Sets: (All) 99 | Aliases: cf 100 | 101 | Required: False 102 | Position: Named 103 | Default value: False 104 | Accept pipeline input: False 105 | Accept wildcard characters: False 106 | ``` 107 | 108 | ### -WhatIf 109 | 110 | Shows what would happen if the cmdlet runs. 111 | The cmdlet is not run. 112 | 113 | ```yaml 114 | Type: SwitchParameter 115 | Parameter Sets: (All) 116 | Aliases: wi 117 | 118 | Required: False 119 | Position: Named 120 | Default value: False 121 | Accept pipeline input: False 122 | Accept wildcard characters: False 123 | ``` 124 | 125 | ### CommonParameters 126 | 127 | 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). 128 | 129 | ## RELATED LINKS 130 | 131 | - [Get-ContainerdLatestVersion](Get-ContainerdLatestVersion.md) 132 | - [Install-Containerd](Install-Containerd.md) 133 | - [Start-ContainerdService](Start-ContainerdService.md) 134 | - [Stop-ContainerdService](Stop-ContainerdService.md) 135 | - [Uninstall-Containerd](Uninstall-Containerd.md) 136 | -------------------------------------------------------------------------------- /docs/About/Show-ContainerTools.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Containers-Toolkit-help.xml 3 | Module Name: Containers-Toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Show-ContainerTools 9 | 10 | ## SYNOPSIS 11 | 12 | List container tools (Containerd, BuildKit, and nerdctl) install status. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Show-ContainerTools [-Latest] [-ToolName ] [] 18 | ``` 19 | 20 | ## DESCRIPTION 21 | 22 | List container tools (Containerd, BuildKit, nerdctl) and shows if the tool is installed, the installed version and the latest available version. 23 | 24 | ## EXAMPLES 25 | 26 | ### Example 1 27 | 28 | ```powershell 29 | PS C:\> Show-ContainerTools -Latest 30 | 31 | Tool Installed Version LatestVersion 32 | ------ ------ ------ ------ 33 | containerd True v1.7.7 v1.7.7 34 | buildkit False - v0.12.2 35 | nerdctl True unknown v1.6.1 36 | ``` 37 | 38 | ## PARAMETERS 39 | 40 | ### -Latest 41 | 42 | Show latest release version 43 | 44 | ```yaml 45 | Type: SwitchParameter 46 | Parameter Sets: (All) 47 | Aliases: 48 | 49 | Required: False 50 | Position: Named 51 | Default value: False 52 | Accept pipeline input: False 53 | Accept wildcard characters: False 54 | ``` 55 | 56 | ### -ToolName 57 | 58 | Displays the version of a specified tool. 59 | If no tool is specified, it returns the versions of containerd, buildkit, and nerdctl. 60 | 61 | ```yaml 62 | Type: String[] 63 | Parameter Sets: (All) 64 | Aliases: 65 | 66 | Required: False 67 | Position: Named 68 | Default value: Null 69 | Accept pipeline input: False 70 | Accept wildcard characters: False 71 | ``` 72 | 73 | ### CommonParameters 74 | 75 | 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). 76 | 77 | ## OUTPUTS 78 | 79 | ### [System.Array](https://learn.microsoft.com/en-us/dotnet/api/system.array?view=net-7.0) 80 | 81 | Returns an array of [PSCustomObject](https://learn.microsoft.com/en-us/dotnet/api/system.management.automation.pscustomobject?view=powershellsdk-7.3.0), 82 | 83 | | Name | Type | Description | 84 | | -------- | ------- | ------- | 85 | | Tool | String | Name of the container tool. Either Containerd, BuildKit, or nerdctl. | 86 | | Installed | Boolean | Specifies whether the tool is installed or not. | 87 | | Version | String | Installed version. | 88 | | LatestVersion | String | Latest available version | 89 | | Daemon | String | Tools daemon, e.g., containerd and buildkitd | 90 | | Daemon Status| String | Specifies the status of the daemon: running, stopped, unregistered | 91 | 92 | ## NOTES 93 | 94 | 1. This information may not be accurate if a tool's paths has not been added to environment path. 95 | 2. A daemon's status could be unavailable if the service has not been registered or started. 96 | 3. The latest version is fetched from the GitHub releases page of the tool. 97 | 98 | ## RELATED LINKS 99 | 100 | - [Get-BuildkitLatestVersion](./Get-BuildkitLatestVersion.md) 101 | - [Get-ContainerdLatestVersion](./Get-ContainerdLatestVersion.md) 102 | - [Get-NerdctlLatestVersion](./Get-NerdctlLatestVersion.md) 103 | - [Get-WinCNILatestVersion](./Get-WinCNILatestVersion.md) 104 | -------------------------------------------------------------------------------- /docs/About/Start-BuildkitdService.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Containers-Toolkit-help.xml 3 | Module Name: Containers-Toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Start-BuildkitdService 9 | 10 | ## SYNOPSIS 11 | 12 | Starts buildkitd service. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Start-BuildkitdService [-WhatIf] [-Confirm] [] 18 | ``` 19 | 20 | ## DESCRIPTION 21 | 22 | Starts buildkitd service and waits for 30 seconds for the service to start. If the service does not start within the this time, execution terminates with an error. 23 | 24 | ## EXAMPLES 25 | 26 | ### Example 1 27 | 28 | Start buildkitd Service. 29 | 30 | ```powershell 31 | PS C:\> Start-BuildkitdService 32 | ``` 33 | 34 | ## PARAMETERS 35 | 36 | ### -Confirm 37 | 38 | Prompts you for confirmation before running the cmdlet. 39 | 40 | ```yaml 41 | Type: SwitchParameter 42 | Parameter Sets: (All) 43 | Aliases: cf 44 | 45 | Required: False 46 | Position: Named 47 | Default value: False 48 | Accept pipeline input: False 49 | Accept wildcard characters: False 50 | ``` 51 | 52 | ### -WhatIf 53 | 54 | Shows what would happen if the cmdlet runs. 55 | The cmdlet is not run. 56 | 57 | ```yaml 58 | Type: SwitchParameter 59 | Parameter Sets: (All) 60 | Aliases: wi 61 | 62 | Required: False 63 | Position: Named 64 | Default value: False 65 | Accept pipeline input: False 66 | Accept wildcard characters: False 67 | ``` 68 | 69 | ### CommonParameters 70 | 71 | 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). 72 | 73 | ## RELATED LINKS 74 | 75 | - [Start-Service](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/start-service?view=powershell-7.3) 76 | - [Get-BuildkitLatestVersion](Get-BuildkitLatestVersion.md) 77 | - [Install-Buildkit](Install-Buildkit.md) 78 | - [Register-BuildkitdService](Register-BuildkitdService.md) 79 | - [Stop-BuildkitdService](Stop-BuildkitdService.md) 80 | - [Uninstall-Buildkit](Uninstall-Buildkit.md) 81 | -------------------------------------------------------------------------------- /docs/About/Start-ContainerdService.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Containers-Toolkit-help.xml 3 | Module Name: Containers-Toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Start-ContainerdService 9 | 10 | ## SYNOPSIS 11 | 12 | Starts Containerd service. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Start-ContainerdService [-WhatIf] [-Confirm] [] 18 | ``` 19 | 20 | ## DESCRIPTION 21 | 22 | Starts Containerd service and waits for 30 seconds for the service to start. If the service does not start within the this time, execution terminates with an error. 23 | 24 | ## EXAMPLES 25 | 26 | ### Example 1 27 | 28 | Start Containerd Service. 29 | 30 | ```powershell 31 | PS C:\> Start-ContainerdService 32 | ``` 33 | 34 | ## PARAMETERS 35 | 36 | ### -Confirm 37 | 38 | Prompts you for confirmation before running the cmdlet. 39 | 40 | ```yaml 41 | Type: SwitchParameter 42 | Parameter Sets: (All) 43 | Aliases: cf 44 | 45 | Required: False 46 | Position: Named 47 | Default value: False 48 | Accept pipeline input: False 49 | Accept wildcard characters: False 50 | ``` 51 | 52 | ### -WhatIf 53 | 54 | Shows what would happen if the cmdlet runs. 55 | The cmdlet is not run. 56 | 57 | ```yaml 58 | Type: SwitchParameter 59 | Parameter Sets: (All) 60 | Aliases: wi 61 | 62 | Required: False 63 | Position: Named 64 | Default value: False 65 | Accept pipeline input: False 66 | Accept wildcard characters: False 67 | ``` 68 | 69 | ### CommonParameters 70 | 71 | 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). 72 | 73 | ## RELATED LINKS 74 | 75 | - [Start-Service](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/start-service?view=powershell-7.3) 76 | - [Get-ContainerdLatestVersion](Get-ContainerdLatestVersion.md) 77 | - [Install-Containerd](Install-Containerd.md) 78 | - [Register-ContainerdService](Register-ContainerdService.md) 79 | - [Stop-ContainerdService](Stop-ContainerdService.md) 80 | - [Uninstall-Containerd](Uninstall-Containerd.md) 81 | -------------------------------------------------------------------------------- /docs/About/Stop-BuildkitdService.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Containers-Toolkit-help.xml 3 | Module Name: Containers-Toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Stop-BuildkitdService 9 | 10 | ## SYNOPSIS 11 | 12 | Stops buildkitd service. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Stop-BuildkitdService [-WhatIf] [-Confirm] [] 18 | ``` 19 | 20 | ## DESCRIPTION 21 | 22 | Stops buildkitd service and waits for 30 seconds for the service to stop. If the service does not stop within the this time, execution terminates with an error. 23 | 24 | ## EXAMPLES 25 | 26 | ### Example 1 27 | 28 | Start buildkitd Service. 29 | 30 | ```powershell 31 | PS C:\> Stop-BuildkitdService 32 | ``` 33 | 34 | ## PARAMETERS 35 | 36 | ### -Confirm 37 | Prompts you for confirmation before running the cmdlet. 38 | 39 | ```yaml 40 | Type: SwitchParameter 41 | Parameter Sets: (All) 42 | Aliases: cf 43 | 44 | Required: False 45 | Position: Named 46 | Default value: False 47 | Accept pipeline input: False 48 | Accept wildcard characters: False 49 | ``` 50 | 51 | ### -WhatIf 52 | Shows what would happen if the cmdlet runs. 53 | The cmdlet is not run. 54 | 55 | ```yaml 56 | Type: SwitchParameter 57 | Parameter Sets: (All) 58 | Aliases: wi 59 | 60 | Required: False 61 | Position: Named 62 | Default value: False 63 | Accept pipeline input: False 64 | Accept wildcard characters: False 65 | ``` 66 | 67 | ### CommonParameters 68 | 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). 69 | 70 | ## RELATED LINKS 71 | 72 | - [Stop-Service](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/stop-service?view=powershell-7.3) 73 | - [Get-BuildkitLatestVersion](Get-BuildkitLatestVersion.md) 74 | - [Install-Buildkit](Install-Buildkit.md) 75 | - [Register-BuildkitdService](Register-BuildkitdService.md) 76 | - [Start-BuildkitdService](Start-BuildkitdService.md) 77 | - [Uninstall-Buildkit](Uninstall-Buildkit.md) 78 | -------------------------------------------------------------------------------- /docs/About/Stop-ContainerdService.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Containers-Toolkit-help.xml 3 | Module Name: Containers-Toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Stop-ContainerdService 9 | 10 | ## SYNOPSIS 11 | 12 | Stops Containerd service. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Stop-ContainerdService [-WhatIf] [-Confirm] [] 18 | ``` 19 | 20 | ## DESCRIPTION 21 | 22 | Stops Containerd service and waits for 30 seconds for the service to stop. If the service does not stop within the this time, execution terminates with an error. 23 | 24 | ## EXAMPLES 25 | 26 | ### Example 1 27 | 28 | Stop Containerd Service. 29 | 30 | ```powershell 31 | PS C:\> Stop-ContainerdService 32 | ``` 33 | 34 | ## PARAMETERS 35 | 36 | ### -Confirm 37 | 38 | Prompts you for confirmation before running the cmdlet. 39 | 40 | ```yaml 41 | Type: SwitchParameter 42 | Parameter Sets: (All) 43 | Aliases: cf 44 | 45 | Required: False 46 | Position: Named 47 | Default value: False 48 | Accept pipeline input: False 49 | Accept wildcard characters: False 50 | ``` 51 | 52 | ### -WhatIf 53 | 54 | Shows what would happen if the cmdlet runs. 55 | The cmdlet is not run. 56 | 57 | ```yaml 58 | Type: SwitchParameter 59 | Parameter Sets: (All) 60 | Aliases: wi 61 | 62 | Required: False 63 | Position: Named 64 | Default value: False 65 | Accept pipeline input: False 66 | Accept wildcard characters: False 67 | ``` 68 | 69 | ### CommonParameters 70 | 71 | 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). 72 | 73 | ## RELATED LINKS 74 | 75 | - [Stop-Service](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/stop-service?view=powershell-7.3) 76 | - [Get-ContainerdLatestVersion](Get-ContainerdLatestVersion.md) 77 | - [Install-Containerd](Install-Containerd.md) 78 | - [Register-ContainerdService](Register-ContainerdService.md) 79 | - [Start-ContainerdService](Start-ContainerdService.md) 80 | - [Uninstall-Containerd](Uninstall-Containerd.md) 81 | -------------------------------------------------------------------------------- /docs/About/Uninstall-Buildkit.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: containers-toolkit-help.xml 3 | Module Name: containers-toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | 9 | # Uninstall-Buildkit 10 | 11 | ## SYNOPSIS 12 | 13 | Uninstalls BuildKit. 14 | 15 | ## SYNTAX 16 | 17 | ``` 18 | Uninstall-Buildkit [[-Path] ] [-Purge] [-Force] [-WhatIf] [-Confirm] [] 19 | ``` 20 | 21 | ## DESCRIPTION 22 | 23 | To uninstall BuildKit, this command stops buildkitd service and unregisters buildkitd service. 24 | The BuildKit directory is then deleted and BuildKit is removed from the environment path. 25 | 26 | ## EXAMPLES 27 | 28 | ### Example 1 29 | 30 | Uninstall BuildKit from the default path. 31 | 32 | ```powershell 33 | PS C:\> Uninstall-Buildkit 34 | ``` 35 | 36 | ## PARAMETERS 37 | 38 | ### -Force 39 | 40 | Bypass confirmation to uninstall BuildKit 41 | 42 | ```yaml 43 | Type: SwitchParameter 44 | Parameter Sets: (All) 45 | Aliases: 46 | 47 | Required: False 48 | Position: Named 49 | Default value: False 50 | Accept pipeline input: False 51 | Accept wildcard characters: False 52 | ``` 53 | 54 | ### -Path 55 | 56 | BuildKit path 57 | 58 | ```yaml 59 | Type: String 60 | Parameter Sets: (All) 61 | Aliases: 62 | 63 | Required: False 64 | Position: 0 65 | Default value: The Buildkit path in the environment path variable or `$Env:ProgramFiles\Buildkit` 66 | Accept pipeline input: False 67 | Accept wildcard characters: False 68 | ``` 69 | 70 | ### -Purge 71 | 72 | Delete all Buildkit program files and program data. 73 | 74 | ```yaml 75 | Type: SwitchParameter 76 | Parameter Sets: (All) 77 | Aliases: 78 | 79 | Required: False 80 | Position: Named 81 | Default value: False 82 | Accept pipeline input: False 83 | Accept wildcard characters: False 84 | ``` 85 | 86 | ### -Confirm 87 | 88 | Prompts you for confirmation before running the cmdlet. 89 | 90 | ```yaml 91 | Type: SwitchParameter 92 | Parameter Sets: (All) 93 | Aliases: cf 94 | 95 | Required: False 96 | Position: Named 97 | Default value: False 98 | Accept pipeline input: False 99 | Accept wildcard characters: False 100 | ``` 101 | 102 | ### -WhatIf 103 | 104 | Shows what would happen if the cmdlet runs. 105 | The cmdlet is not run. 106 | 107 | ```yaml 108 | Type: SwitchParameter 109 | Parameter Sets: (All) 110 | Aliases: wi 111 | 112 | Required: False 113 | Position: Named 114 | Default value: False 115 | Accept pipeline input: False 116 | Accept wildcard characters: False 117 | ``` 118 | 119 | ### CommonParameters 120 | 121 | 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). 122 | 123 | ## RELATED LINKS 124 | 125 | - [Get-BuildkitLatestVersion](Get-BuildkitLatestVersion.md) 126 | - [Install-Buildkit](Install-Buildkit.md) 127 | - [Register-BuildkitdService](Register-BuildkitdService.md) 128 | - [Start-BuildkitdService](Start-BuildkitdService.md) 129 | - [Stop-BuildkitdService](Stop-BuildkitdService.md) 130 | -------------------------------------------------------------------------------- /docs/About/Uninstall-Containerd.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: containers-toolkit-help.xml 3 | Module Name: containers-toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Uninstall-Containerd 9 | 10 | ## SYNOPSIS 11 | 12 | Uninstalls Containerd. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Uninstall-Containerd [[-Path] ] [-Purge] [-Force] [-WhatIf] [-Confirm] [] 18 | ``` 19 | 20 | ## DESCRIPTION 21 | 22 | To uninstall Containerd, this function first stops Containerd service and unregisters Containerd service. 23 | The Containerd directory is then deleted and Containerd is removed from the environment path. 24 | 25 | ## EXAMPLES 26 | 27 | ### Example 1 28 | 29 | Uninstall Containerd from the default path. 30 | 31 | ```powershell 32 | PS C:\> Uninstall-Containerd 33 | ``` 34 | 35 | ## PARAMETERS 36 | 37 | ### -Force 38 | 39 | Bypass confirmation to uninstall Containerd 40 | 41 | ```yaml 42 | Type: SwitchParameter 43 | Parameter Sets: (All) 44 | Aliases: 45 | 46 | Required: False 47 | Position: Named 48 | Default value: False 49 | Accept pipeline input: False 50 | Accept wildcard characters: False 51 | ``` 52 | 53 | ### -Path 54 | 55 | Containerd path 56 | 57 | ```yaml 58 | Type: String 59 | Parameter Sets: (All) 60 | Aliases: 61 | 62 | Required: False 63 | Position: 0 64 | Default value: $Env:ProgramFiles\Containerd 65 | Accept pipeline input: False 66 | Accept wildcard characters: False 67 | ``` 68 | 69 | ### -Purge 70 | 71 | Delete all Containerd program files and program data. 72 | 73 | ```yaml 74 | Type: SwitchParameter 75 | Parameter Sets: (All) 76 | Aliases: 77 | 78 | Required: False 79 | Position: Named 80 | Default value: False 81 | Accept pipeline input: False 82 | Accept wildcard characters: False 83 | ``` 84 | 85 | ### -Confirm 86 | 87 | Prompts you for confirmation before running the cmdlet. 88 | 89 | ```yaml 90 | Type: SwitchParameter 91 | Parameter Sets: (All) 92 | Aliases: cf 93 | 94 | Required: False 95 | Position: Named 96 | Default value: False 97 | Accept pipeline input: False 98 | Accept wildcard characters: False 99 | ``` 100 | 101 | ### -WhatIf 102 | 103 | Shows what would happen if the cmdlet runs. 104 | The cmdlet is not run. 105 | 106 | ```yaml 107 | Type: SwitchParameter 108 | Parameter Sets: (All) 109 | Aliases: wi 110 | 111 | Required: False 112 | Position: Named 113 | Default value: False 114 | Accept pipeline input: False 115 | Accept wildcard characters: False 116 | ``` 117 | 118 | ### CommonParameters 119 | 120 | 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). 121 | 122 | 123 | ## RELATED LINKS 124 | 125 | - [Get-ContainerdLatestVersion](Get-ContainerdLatestVersion.md) 126 | - [Install-Containerd](Install-Containerd.md) 127 | - [Register-ContainerdService](Register-ContainerdService.md) 128 | - [Start-ContainerdService](Start-ContainerdService.md) 129 | - [Stop-ContainerdService](Stop-ContainerdService.md) 130 | -------------------------------------------------------------------------------- /docs/About/Uninstall-Nerdctl.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: containers-toolkit-help.xml 3 | Module Name: containers-toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Uninstall-Nerdctl 9 | 10 | ## SYNOPSIS 11 | 12 | Uninstalls nerdctl. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Uninstall-Nerdctl [[-Path] ] [-Purge] [-Force] [-WhatIf] [-Confirm] [] 18 | ``` 19 | 20 | ## DESCRIPTION 21 | 22 | To uninstall nerdctl, the nerdctl directory is deleted and nerdctl is removed from the environment path. 23 | 24 | ## EXAMPLES 25 | 26 | ### Example 1 27 | 28 | Uninstall nerdctl from the default path. 29 | 30 | ```powershell 31 | PS C:\> Uninstall-Nerdctl 32 | ``` 33 | 34 | ## PARAMETERS 35 | 36 | ### -Force 37 | 38 | Bypass confirmation to uninstall nerdctl 39 | 40 | ```yaml 41 | Type: SwitchParameter 42 | Parameter Sets: (All) 43 | Aliases: 44 | 45 | Required: False 46 | Position: Named 47 | Default value: False 48 | Accept pipeline input: False 49 | Accept wildcard characters: False 50 | ``` 51 | 52 | ### -Path 53 | 54 | nerdctl path 55 | 56 | ```yaml 57 | Type: String 58 | Parameter Sets: (All) 59 | Aliases: 60 | 61 | Required: False 62 | Position: 0 63 | Default value: $Env:ProgramFiles\nerdctl 64 | Accept pipeline input: False 65 | Accept wildcard characters: False 66 | ``` 67 | 68 | ### -Purge 69 | 70 | Delete all nerdctl program files and program data. 71 | 72 | ```yaml 73 | Type: SwitchParameter 74 | Parameter Sets: (All) 75 | Aliases: 76 | 77 | Required: False 78 | Position: Named 79 | Default value: False 80 | Accept pipeline input: False 81 | Accept wildcard characters: False 82 | ``` 83 | 84 | ### -Confirm 85 | 86 | Prompts you for confirmation before running the cmdlet. 87 | 88 | ```yaml 89 | Type: SwitchParameter 90 | Parameter Sets: (All) 91 | Aliases: cf 92 | 93 | Required: False 94 | Position: Named 95 | Default value: False 96 | Accept pipeline input: False 97 | Accept wildcard characters: False 98 | ``` 99 | 100 | ### -WhatIf 101 | 102 | Shows what would happen if the cmdlet runs. 103 | The cmdlet is not run. 104 | 105 | ```yaml 106 | Type: SwitchParameter 107 | Parameter Sets: (All) 108 | Aliases: wi 109 | 110 | Required: False 111 | Position: Named 112 | Default value: False 113 | Accept pipeline input: False 114 | Accept wildcard characters: False 115 | ``` 116 | 117 | ### CommonParameters 118 | 119 | 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). 120 | 121 | ## RELATED LINKS 122 | 123 | - [Get-NerdctlLatestVersion](Get-NerdctlLatestVersion.md) 124 | - [Install-Nerdctl](Install-Nerdctl.md) 125 | -------------------------------------------------------------------------------- /docs/About/Uninstall-WinCNIPlugin.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: containers-toolkit-help.xml 3 | Module Name: containers-toolkit 4 | online version: 5 | schema: 2.0.0 6 | --- 7 | 8 | # Uninstall-WinCNIPlugin 9 | 10 | ## SYNOPSIS 11 | 12 | Uninstall Windows CNI plugins. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Uninstall-WinCNIPlugin [[-Path] ] [-Force] [-WhatIf] [-Confirm] [] 18 | ``` 19 | 20 | ## DESCRIPTION 21 | 22 | Uninstall Windows CNI plugins from the default or provided path. The default path is `$ENV:ProgramFiles\Containerd\cni`. 23 | 24 | ## EXAMPLES 25 | 26 | ### Example 1 27 | 28 | Uninstalls WinCNIPlugins from the default path, `$ENV:ProgramFiles\Containerd\cni` 29 | 30 | ```powershell 31 | PS C:\> Uninstall-WinCNIPlugin 32 | ``` 33 | 34 | ## PARAMETERS 35 | 36 | ### -Force 37 | 38 | Bypass confirmation to uninstall Windows CNI plugins 39 | 40 | ```yaml 41 | Type: SwitchParameter 42 | Parameter Sets: (All) 43 | Aliases: 44 | 45 | Required: False 46 | Position: Named 47 | Default value: False 48 | Accept pipeline input: False 49 | Accept wildcard characters: False 50 | ``` 51 | 52 | ### -Path 53 | 54 | Windows CNI plugin path 55 | 56 | ```yaml 57 | Type: String 58 | Parameter Sets: (All) 59 | Aliases: 60 | 61 | Required: False 62 | Position: 0 63 | Default value: $ENV:ProgramFiles\Containerd\cni 64 | Accept pipeline input: False 65 | Accept wildcard characters: False 66 | ``` 67 | 68 | ### -Confirm 69 | 70 | Prompts you for confirmation before running the cmdlet. 71 | 72 | ```yaml 73 | Type: SwitchParameter 74 | Parameter Sets: (All) 75 | Aliases: cf 76 | 77 | Required: False 78 | Position: Named 79 | Default value: False 80 | Accept pipeline input: False 81 | Accept wildcard characters: False 82 | ``` 83 | 84 | ### -WhatIf 85 | 86 | Shows what would happen if the cmdlet runs. 87 | The cmdlet is not run. 88 | 89 | ```yaml 90 | Type: SwitchParameter 91 | Parameter Sets: (All) 92 | Aliases: wi 93 | 94 | Required: False 95 | Position: Named 96 | Default value: False 97 | Accept pipeline input: False 98 | Accept wildcard characters: False 99 | ``` 100 | 101 | ### CommonParameters 102 | 103 | 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). 104 | 105 | ## RELATED LINKS 106 | 107 | - [Get-WinCNILatestVersion](Get-WinCNILatestVersion.md) 108 | - [Install-WinCNIPlugin](Install-WinCNIPlugin.md) 109 | - [Initialize-NatNetwork](Initialize-NatNetwork.md) 110 | -------------------------------------------------------------------------------- /docs/FAQs.md: -------------------------------------------------------------------------------- 1 | # FAQs 2 | 3 | ## Table of Contents 4 | 5 | - [`Import-Module` issues](#import-module-issues) 6 | - [Tool uninstall issues](#tool-uninstall-issues) 7 | - [`Initialize-NatNetwork` issues](#initialize-natnetwork-issues) 8 | 9 | ## `Import-Module` issues 10 | 11 | - [Unblock-File](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/unblock-file?view=powershell-7.4) 12 | - [Error when running Import-Module](https://vnote42.net/2019/07/30/error-when-running-import-module/) 13 | - [Unblock a script to run it without changing the execution policy](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-7.4#example-7-unblock-a-script-to-run-it-without-changing-the-execution-policy) 14 | 15 | ## Tool uninstall issues 16 | 17 | 22 | ### Access to path denied 23 | 24 | If you encounter an Access to path denied error during the uninstall process, even with Administrator privileges, it typically stems from issues with folder ownership. To resolve this, you'll need to reassign ownership to an account with administrative privileges. You can accomplish this using the `takeown` command. 25 | 26 | Example: 27 | 28 | ```PowerShell 29 | takeown /f "C:\ProgramData\containerd" /r /d Y 30 | ``` 31 | 32 | After successfully changing the ownership, you can proceed to remove the folder manually. 33 | 34 | If the issue persists, navigate to the folder's properties and choose the option to `Replace all child object permission entries with inheritable permission entries from this object`. This action will apply the inheritable permissions set on this folder to all sub-folders and files within it. 35 | 36 | ![alt text](../assets/child-object-permission.png) 37 | 38 | 1. Navigate to the folder. 39 | 2. Right-click on the folder and choose **Properties**. 40 | 3. Go to the **Security** tab. 41 | 4. Click on **Advanced**. 42 | 5. In the Advanced Security Settings, select the option `Replace all child object permission entries with inheritable permission entries from this object`. 43 | 6. Apply the changes and confirm. 44 | 45 | ## `Initialize-NatNetwork` issues 46 | 47 | 52 | ### 1. Could not import HNS module 53 | 54 | Ensure 'Hyper-V Host Compute Service' Windows features are enabled. 55 | 56 | ```PowerShell 57 | Get-WindowsOptionalFeature -Online | ` 58 | Where-Object { $_.FeatureName -match "Microsoft-Hyper-V(-All)?$" } | ` 59 | Select-Object FeatureName, Possible, State, RestartNeeded 60 | ``` 61 | 62 | To enable a feature: 63 | 64 | ```PowerShell 65 | Enable-WindowsOptionalFeature -Online -FeatureName '' -All -NoRestart 66 | 67 | # Restart device to apply changes 68 | # Restart-Computer 69 | ``` 70 | 71 | [Restart the operating system](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/restart-computer?view=powershell-7.4) to apply changes. 72 | 73 | 78 | ### 2. New-HNSNetwork command does not exist 79 | 80 | The built-in `HostNetworkingService` PowerShell module does not include the `New-HNSNetwork` command. This command is available through the HNS module. 81 | 82 | You can download it directly from the [microsoft/sdn](https://github.com/microsoft/SDN) repository. 83 | 84 | > [!TIP] 85 | > The `hns.psm1` file should be saved in a directory that is included in the `$env:PSModulePath` environment variable. 86 | > In the example below, the module is saved in the "Current User, Current Host" profile directory. Read more about [PowerShell profiles](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7.4). 87 | 88 | ```powershell 89 | $dirPath = (New-Item -Path "$(Split-Path $PROFILE.CurrentUserCurrentHost)/Modules/HNS" -ItemType Directory -Force).FullName 90 | $Uri = 'https://raw.githubusercontent.com/microsoft/SDN/dd4e8708ed184b49d3fddd611b6027f1755c6edb/Kubernetes/windows/hns.v2.psm1' 91 | Invoke-WebRequest -Uri $Uri -OutFile "$dirPath/hns.psm1" 92 | ``` 93 | 94 | After installing the module, import it into your session: 95 | 96 | > [!TIP] 97 | > Ensure the [Execution Policy](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.4#powershell-execution-policies) is set correctly to import the module. 98 | 99 | ```powershell 100 | # Check if the module is installed 101 | Get-Module -Name HNS -ListAvailable -Refresh 102 | 103 | # Import the module 104 | Import-Module HNS 105 | ``` 106 | 107 | > [!CAUTION] 108 | > **We do not recommend** using the [_third-party_ HNS module](https://www.powershellgallery.com/packages/HNS/0.2.4) available in the PowerShell Gallery. This module is **NOT** maintained and signed by Microsoft and may not be up-to-date with the latest changes in the HNS module. 109 | > _Microsoft does **NOT** take any responsibility for issues that may arise from installing and/or execution of commands in any third-party modules/scripts. Install the _third-party_ HNS module at your own risk!_ 110 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "devDependencies": { 3 | "dictionary-en": "^4.0.0", 4 | "markdown-link-check": "^3.13.7", 5 | "textlint": "^14.6.0", 6 | "textlint-filter-rule-comments": "^1.2.2", 7 | "textlint-rule-spelling": "^0.3.0" 8 | } 9 | } 10 | --------------------------------------------------------------------------------