diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..ddec128 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,14 @@ +# + +# Area: Documentation +docs/ @tinamor + +# Area: Test +*.Tests.ps1 @tinamor + + +# Tools +containers-toolkit//Public/BuildkitTools.psm1 @profnandaa @billywr @danielGithinji +containers-toolkit/Public/ontainerdTools.psm1 @charitykathure +containers-toolkit/Public/ContainerNetworkTools.psm1 @iankingori +containers-toolkit/Public/NerdctlTools.psm1 @tinamor diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index dd84ea7..601747c 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,38 +1,57 @@ --- name: Bug report -about: Create a report to help us improve -title: '' +about: Create a report to help improve Containers Toolkit PowerShell module +title: "[BUG] [CTK v1.0.0] Summary of the issue" labels: '' assignees: '' --- **Describe the bug** -A clear and concise description of what the bug is. + +Please file a single issue per bug instead of enumerating multiple items. **To Reproduce** -Steps to reproduce the behavior: -1. Go to '...' -2. Click on '....' -3. Scroll down to '....' -4. See error + +Detailed steps to reproduce the behavior: +1. +2. +3. ... + +The more information you can provide, the more likely someone will be successful at triaging and reproducing the issue and finding a fix. **Expected behavior** + +A clear and concise description of what you expected to happen. + +**Actual behavior** + A clear and concise description of what you expected to happen. **Screenshots** + If applicable, add screenshots to help explain your problem. -**Desktop (please complete the following information):** - - OS: [e.g. iOS] - - Browser [e.g. chrome, safari] - - Version [e.g. 22] +**System information** + +- Windows build and Version + - PowerShell -**Smartphone (please complete the following information):** - - Device: [e.g. iPhone6] - - OS: [e.g. iOS8.1] - - Browser [e.g. stock browser, safari] - - Version [e.g. 22] + ```PowerShell + systeminfo | findstr /B /C:"OS Name" /C:"OS Version" /C:"System Type" + ``` + +- PowerShell version +- Package version for which the problem occurs +- Container tool versions: + - Containerd + - Buildkit + - Nerdctl + - Win CNI plugin: + - Plugin: [Windows Container Networking CNI](https://github.com/microsoft/windows-container-networking) or [CNI network plugins](https://github.com/containernetworking/plugins) + - Version +- For issues with extensions, the version of the IDE for which the problem occurs **Additional context** + Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index bbcbbe7..d1a31e7 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,6 +1,6 @@ --- name: Feature request -about: Suggest an idea for this project +about: Suggest an idea for Containers Toolkit PowerShell module title: '' labels: '' assignees: '' diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..5585d34 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,39 @@ +## PR description + +### Github issue/ discussion () + +_related Isuue/discussion(s)_ + +### Background information + +_From the perspective of the reviewer, what context do they need to know to understand this PR?_ + +### What does this PR do + +_What does this PR achieve/fix._ + +### TODOs not included in this PR + +_What issues will/should be addressed in followup PRs. Link any of these issues if they exist_ + +### Testing information + +_How to test the changes_ + +### Relevant links () + +_Any links from your research that will help explain the changes_ + +## Checklist + +As part of our commitment to engineering excellence, **before** submitting this PR, please make sure: + +- [ ] You've tested this code in both Desktop & Server environments and AMD & ARM64 enviroments (**functional testing**). +- [ ] You've added **unit tests** for new code. +- [ ] You've added/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). +- [ ] You've reviewed the PR/code best practices defined in the [CONTRIBUTING.md](../CONTRIBUTING.md). + +In addition, **after** this PR has been reviewed, please agree to: + +- [ ] If changes have been made to your PR in the process of addressing comments, please make sure to test again the _final_ version in both AMD and ARM64 environments. +- [ ] Validate your changes have not introduced any regressions. diff --git a/.github/workflows/ci-build.yaml b/.github/workflows/ci-build.yaml index 7338ed8..2515c13 100644 --- a/.github/workflows/ci-build.yaml +++ b/.github/workflows/ci-build.yaml @@ -100,7 +100,7 @@ jobs: shell: pwsh run: | Set-PSRepository PSGallery -InstallationPolicy Trusted - $requiredModules = @('Pester', 'ThreadJob', 'HNS') + $requiredModules = @('Pester', 'ThreadJob') $missingModules = $requiredModules | Where-Object { -not (Get-Module -ListAvailable -Name $_) } if ($missingModules) { @@ -167,4 +167,4 @@ jobs: - name: Post results run: | - cat coveragereport/SummaryGithub.md >> $GITHUB_STEP_SUMMARY + cat coveragereport/SummaryGithub.md >> $env:GITHUB_STEP_SUMMARY diff --git a/.github/workflows/markdown-lint.yml b/.github/workflows/markdown-lint.yml new file mode 100644 index 0000000..259c70f --- /dev/null +++ b/.github/workflows/markdown-lint.yml @@ -0,0 +1,68 @@ +on: + pull_request: + branches: + - main + - "releases/**" + paths: + - "docs/**" + - "README.md" + - en-US/**" + +name: Check modified markdown files +permissions: + contents: read + +jobs: + markdown-check: + runs-on: windows-latest + steps: + - uses: actions/checkout@v4 + # - uses: actions/setup-node@v4 + # with: + # node-version: 21 + + - name: Install npm dependencies + run: npm install -g markdown-link-check textlint textlint-rule-spelling dictionary-en + + - name: Markdown link check + shell: pwsh + run: | + # Check all markdown files in the repository + $mlc_error_file = "link-errors.txt" + Get-ChildItem -Path "README.md", ".\docs\" -Filter "*.md" -Recurse | ` + ForEach-Object { & markdown-link-check $_.FullName -q 2>>$error_file } + + # Check if the error file exists + if (-not (Test-Path "$error_file")) { + return + } + + # Check if the error file file contains errors + if (Select-String -Path "$error_file" -Pattern "ERROR: ") { + $Link_Check_Summary = ":x: [Markdown Link Check] Broken links found. Please check the output for more information." + } + else { + $Link_Check_Summary = ":white_check_mark: [Markdown Link Check] All links are valid." + } + echo $Link_Check_Summary >> $env:GITHUB_STEP_SUMMARY + + - name: Markdown spell check + shell: pwsh + run: | + # Run spell check on all markdown files in the repository + $sc_error_file = "sc-errors.txt" + npx textlint README.md docs/**/*.md >>$sc_error_file + + # Check if the error file exists + if (-not (Test-Path "$sc_error_file")) { + return + } + + # Check if the error file file contains errors. If the file is empty, it means no errors were found. + if ([string]::IsNullOrWhiteSpace((Get-Content -Path $sc_error_file))) { + $Spell_Check_Summary = ":white_check_mark: [Markdown Spell Check] No spelling errors found." + } + else { + $Spell_Check_Summary = ":x: [Markdown Spell Check] Spelling errors found. Please check the output for more information." + } + echo $Spell_Check_Summary >> $env:GITHUB_STEP_SUMMARY diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 8b3f816..7116288 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -47,7 +47,7 @@ jobs: shell: pwsh run: | Set-PSRepository PSGallery -InstallationPolicy Trusted - $requiredModules = @('ThreadJob', 'HNS') + $requiredModules = @('ThreadJob') $missingModules = $requiredModules | Where-Object { -not (Get-Module -ListAvailable -Name $_) } if ($missingModules) { @@ -110,4 +110,4 @@ jobs: shell: pwsh run: | $tag="${{ steps.update-version.outputs.NEW_VERSION }}" - echo ":rocket: Succefully released Containers.Toolkit v$tag" >> $GITHUB_STEP_SUMMARY + echo ":rocket: Successfully released Containers.Toolkit v$tag" >> $env:GITHUB_STEP_SUMMARY diff --git a/.textlintrc.json b/.textlintrc.json index 073e5e8..f881d35 100644 --- a/.textlintrc.json +++ b/.textlintrc.json @@ -1,35 +1,53 @@ { - "rules": { - "spelling": { - "language": "en", - "skipPatterns": [ - "/[0-9]+/g", // numbers - "/\\bhttp(s)?:\\/\\/[^\\s)>]+/", // URL - // "/\\b[a-z\\d]{7,40}\\b/", // commit hash - "/\\([^)]+?\\)/", // inside parentheses - // // '/"[^"]+?"/', // inside quotation marks - // // "/`[^`]+?`/", // inside backticks - "/\\b(?:[A-Z]){2,}\\b/g", // acronyms - "/\\b(?:[a-zA-Z]+-[a-zA-Z]+)\\b/g", // hyphenated words/ function names - // "/\b\\S*\\.\\S{2,4}/g", // filenames - "/\\$[\\w]+(:\\w)?/g", // PowerShell variables - "/-\\w+\\b/g", // FIXME: PowerShell Cmdlets/function parameter names - "/\\b\\w+[./]\\w+\\b/g", // paths // FIXME: Does not work for \ in paths - "containers-toolkit", - "PowerShell", - "/Cmdlets/i", - "Containerd", - "BuildKit", - "buildkitd", - "nerdctl", - "WinCNIPlugin", - "NatNetwork", - "/nat/i", - "cni", - "HNS", - "CIDR", - "subnet" - ] - } + "plugins": {}, + "filters": {}, + "rules": { + "spelling": { + "language": "en", + "skipPatterns": [ + "/[0-9]+/g", // numbers + "/\\bhttp(s)?:\\/\\/[^\\s)>]+/", // URL + // "/\\b[a-z\\d]{7,40}\\b/", // commit hash + "/\\([^)]+?\\)/", // inside parentheses + // "/\"[^\"]+?\"/", // inside quotation marks + // "/`[^`]+?`/", // inside backticks + "/\\b(?:[A-Z]){2,}\\b/g", // acronyms + "/\\b(?:[a-zA-Z]+-[a-zA-Z]+)\\b/g", // hyphenated words/ function names + // "/\\b\\S*\\.\\S{2,4}/g", // filenames + "/\\$[\\w]+(:\\w)?/g", // PowerShell variables + "/-\\w+\\b/g", // FIXME: PowerShell Cmdlets/function parameter names + "/\\b\\w+[./]\\w+\\b/g", // paths // FIXME: (Note: Does not work for \ in paths) + "about_Preference_Variables", + "CIDR", + "Containers[\\s\\.\\-]ToolKit/gi", + "/Cmdlet/gi", + "cni", + "/Containerd/gi", + "/BuildKit/gi", + "/buildkitd/gi", + "/H(ost)?N(etworking)?S(ervice)?/g", + "/Hyper[\\s-]?V/g", + "/moby/gi", + "/nat/gi", + "NatNetwork", + "nerdctl", + "PowerShell", + "/PSCustomObject/gi", + "subnet", + "ThreadJob", + "/unregisters/gi", + "WinCNIPlugin", + + // Parameter names + "DownloadPath", + "InstallPath", + "LatestVersion", + "NetworkName", + "RegisterServices", + "WhatIf", + "WinCNIPath", + "WinCNIVersion" + ] } + } } \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..32f490b --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,3 @@ +## 1.0.0 + +* Initial release diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ebf23ac..cf390ae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,14 +1,345 @@ -# Contributing +# Contributing to Containers Toolkit Project -This project welcomes contributions and suggestions. Most contributions require you to -agree to a Contributor License Agreement (CLA) declaring that you have the right to, -and actually do, grant us the rights to use your contribution. For details, visit -https://cla.microsoft.com. +Welcome, and thank you for your interest in contributing to Containers Toolkit. -When you submit a pull request, a CLA-bot will automatically determine whether you need -to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the -instructions provided by the bot. You will only need to do this once across all repositories using our CLA. +There are many ways in which you can contribute, beyond writing code. The goal of this document is to provide a high-level overview of how you can get involved. See the [Table of Contents](#table-of-contents) for different ways to help and details about how this project handles them. -This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). -For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Contributor License Agreement](#contributor-license-agreement) +- [Reporting Issues](#reporting-issues) +- [Contributing to Documentation](#contributing-to-documentation) +- [Contributing to Code](#contributing-to-code) +- [Linting](#linting) +- [Testing Guidelines](#testing-guidelines) +- [Recommended Workflow](#recommended-workflow) + +## Code of Conduct + +This project and everyone participating in it is governed by the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). + +By participating, you are expected to uphold this code. Please report unacceptable behavior to . For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. + +## Contributor License Agreement + +This project welcomes contributions and suggestions. Most contributions require you to agree to a +Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us +the rights to use your contribution. For details, visit . + +When you submit a pull request, a CLA bot will automatically determine whether you need to provide +a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions +provided by the bot. You will only need to do this once across all repos using our CLA. + +## Reporting Issues + +This project uses GitHub Issues to track bugs and feature requests. Please search the [existing issues](https://github.com/microsoft/windows-container-tools/issues) before filing new issues to avoid duplicates. If you do find an existing issue, please include your own feedback in the discussion. Do consider upvoting (👍 reaction) the original post, as this helps us prioritize popular issues in our backlog. + +For new issues, file your bug or feature request as a [new issue](https://github.com/microsoft/containers-toolkit/issues). Be sure to include as much information as possible to help us understand and reproduce the problem: + +- Provide as much context as you can about what you are running into. +- Provide project and platform versions depending on what seems relevant. + +If you know how to fix the issue, feel free to send a pull request our way. (This Contribution Guide applies to that pull request, you may want to give it a read!) + +### Writing a Good Bug Report + +Good bug reports make it easier for maintainers to verify and triage the underlying problem. The better a bug report, the faster the problem will be resolved. Ideally, a bug report should contain the following information: + +- A high-level description of the problem. +- A _minimal reproduction_, i.e. the smallest size of code/configuration required to reproduce the wrong behavior. +- A description of the _expected behavior_, contrasted with the _actual behavior_ observed. +- Information on the environment: PowerShell version, container tool version, etc. +- Additional information, e.g. is it a regression from previous versions? are there any known workarounds? + +Your question serve as a resource to others searching for help. + +## Contributing to Documentation + +### Quick steps if you are changing an existing cmdlet + +If you made a change to an existing cmdlet and would like to update the documentation using PlatyPS, +here are the quick steps: + +1. Install `PlatyPS` if you do not have it - `Install-Module PlatyPS`. +1. Fork the [microsoft/containers-toolkit](https://github.com/Microsoft/containers-toolkit) repository if you do not already have it. +1. Start your local build of PowerShell. +1. Find the [cmdlet's Markdown file](./docs/About/) in Docs. For example: docs/About/Get-BuildkitLatestVersion.md +1. Run `Update-MarkdownHelp -Path ` which will update the documentation for you. +1. Make any additional changes needed for the cmdlet to be properly documented. +1. Update the module help files: + + ```PowerShell + Set-Location + $commandsDir= 'docs\About' + $enUSDir = 'containers-toolkit\en-US' + New-ExternalHelp -Path $commandsDir -OutputPath $enUSDir -Force + ``` + +1. Create a Pull Request to the [microsoft/containers-toolkit](https://github.com/Microsoft/containers-toolkit) repository with the changes + - Make sure you squash your commits + - Sign your commits +1. Link your Docs PR to your original change PR. + +### Spellchecking documentation + +Documentation is spellchecked. We use the[textlint](https://github.com/textlint/textlint/wiki/Collection-of-textlint-rule) command-line tool,which can be run in interactive mode to correct typos. + +To run the spellchecker, follow these steps: + +- Install [Node.js](https://nodejs.org/en/) (v10 or up) +- Install [textlint](https://github.com/textlint/textlint/wiki/Collection-of-textlint-rule) by `npm install -g textlint textlint-rule-spelling dictionary-en` +- Run `npx textlint `, adding `--fix` will accept all the recommendations. + +If you need to add a term or disable checking part of a file see the [configuration sections of the rule](https://github.com/sapegin/textlint-rule-terminology). + +### Checking links in documentation + +Documentation is link-checked. We make use of the `markdown-link-check` command-line tool, which can be run to see if any links are dead. + +To run the link-checker, follow these steps: + +- Install [Node.js](https://nodejs.org/en/) (v10 or up) +- Install `markdown-link-check` by + `npm install -g markdown-link-check` +- Run `markdown-link-check` on .md files in the project directory. + + ```PowerShell + Get-ChildItem -Path "README.md",".\docs\" -Filter "*.md" -Recurse | ForEach-Object { & markdown-link-check $_.FullName -q } + ``` + +## Contributing to Code + +### Coding guidelines + +Please follow the PowerShell [Common Engineering Practices](https://github.com/PowerShell/PowerShell/blob/master/.github/CONTRIBUTING.md#common-engineering-practices). + +These is not a comprehensive list, but a high-level guide. + +Please do: + +- **DO** follow our coding style. +- **DO** include tests when adding new features. When fixing bugs, start with + adding a test that highlights how the current behavior is broken. +- **DO** keep the discussions focused. When a new or related topic comes up + it's often better to create a new issue than to side track the discussion. +- **DO** feel free to blog, tweet, or share anywhere else about your contributions! + +Please do not: + +- **DON'T** make PRs for style changes. +- **DON'T** surprise us with big pull requests. For large changes, create + a new discussion so we can agree on a direction before you invest a large amount + of time. For bug fixes, create an issue. +- **DON'T** commit code that you didn't write. If you find code that you think is a good fit to add to any of the tools, file an issue and start a discussion before proceeding. +- **DON'T** submit PRs that alter licensing related files or headers. If you believe there's a problem with them, file an issue and we'll be happy to discuss it. + +### New files + +- If your change adds a new source file, ensure the appropriate copyright and license headers is on top. + It is standard practice to have both a copyright and license notice for each source file. + + ```PowerShell + ########################################################################### + # # + # Copyright (c) Microsoft Corporation. All rights reserved. # + # # + # This code is licensed under the MIT License (MIT). # + # # + ########################################################################### + + + + ``` + +### Setup development environment + +1. **Clone the repo** + + **Option 1:** Clone containers-toolkit into one of the folder locations in the `$env:PSModulePath` environment variable. + + 1. Get a possible module path: + + ```PowerShell + $env:PSModulePath -split ";" + ``` + + 1. Clone the repo + + ```PowerShell + cd + git clone https://github.com/microsoft/containers-toolkit.git + ``` + + **Option 2:** Clone containers-toolkit to a folder location of choice and add the new module location to the Windows PowerShell module path + + 1. Clone the repo + + ```PowerShell + cd + git clone https://github.com/microsoft/containers-toolkit.git + ``` + + 1. Add the directory to Windows PowerShell module path + + ```PowerShell + $env:PSModulePath += ";/containers-toolkit" + ``` + +1. **Check the module is imported** in the current session or that can be imported from the PSModulePath + + ```PowerShell + Get-Module -Name "containers-toolkit" -ListAvailable + ``` + +1. **Import the module** + + ```PowerShell + Import-Module -Name containers-toolkit -Force + ``` + +## Linting + +To maintain code quality and consistency, we use PowerShell Script Analyzer ([PSScriptAnalyzer](https://learn.microsoft.com/en-us/powershell/module/psscriptanalyzer/?view=ps-modules)) for linting our scripts. Follow these steps to lint your code before submitting a pull request: + +1. **Install PSScriptAnalyzer** (if not already installed): + + ```PowerShell + Install-Module -Name PSScriptAnalyzer -Force + ``` + +2. **Run the linter**: + + Navigate to the root directory of the repository and run the following command: + + ```PowerShell + Invoke-ScriptAnalyzer -Path . -Recurse -ExcludeRule PSProvideCommentHelp, PSUseSingularNouns + ``` + + - `-Path .` specifies the current directory. + - `-Recurse` ensures that the linter checks all subdirectories. + - `-ExcludeRule PSProvideCommentHelp, PSUseSingularNouns` excludes the `PSProvideCommentHelp` and `PSUseSingularNouns` rules from the analysis. We exclude these rules because: + - `PSProvideCommentHelp`: We might not require comment-based help for every function in the module. + - `PSUseSingularNouns`: There might be legitimate cases where plural nouns are necessary. + +3. **Review and fix issues**: + + Review the output of the linter and fix any issues that are flagged. Ensuring your code passes linting checks helps maintain a high standard of code quality and consistency across the repository. + +By following these linting guidelines, you help ensure that your contributions are aligned with the project's coding standards, making it easier for maintainers to review and merge your changes. + +## Testing Guidelines + +Testing is a critical and required part of this project. + +For creating new tests, please review the [Pester documentation](https://pester.dev/docs/quick-start) on how to create tests for PowerShell. There is a best practices document for [writing Pester tests](https://github.com/PowerShell/PowerShell/tree/master/docs/testing-guidelines/WritingPesterTests.md). + +### CI System + +We use [GitHub Actions workflows](https://docs.github.com/en/actions/using-workflows) as a continuous integration (CI) system for Windows and non-Windows platforms. + +In the `README.md` at the top of the repository, you can see CI Build badge. +It indicates the last build status of `master` branch. + +This badge is **clickable**; you can open corresponding build page with logs, artifacts, and tests results. +From there you can easily navigate to the build history. + +### Test Frameworks + +#### Pester + +Our script-based test framework is [Pester](https://github.com/Pester/Pester). We recommend adding tests for any new code or code that changes functionality. + +**References** + +- [`New-PesterConfiguration`](https://pester.dev/docs/commands/New-PesterConfiguration) cmdlet +- [`Invoke-Pester`](https://pester.dev/docs/commands/invoke-pester/) cmdlet +- [`Tag`](https://pester.dev/docs/usage/tags) parameter + +#### Running Containers-Toolkit tests outside of CI + +During the automated CI the unit tests and integration tests are run as part of the PR validation. You can run these tests locally by using [`Invoke-Pester` cmdlet](https://pester.dev/docs/commands/invoke-pester/) or the [`run-tests.ps1` file](./build/scripts/run-tests.ps1). The [`run-tests.ps1` file](./build/scripts/run-tests.ps1) uses a [PesterConfiguration-object](https://pester.dev/docs/commands/New-PesterConfiguration) for runnings tests using Invoke-Pester. + +> [!TIP] +> If using `run-tests.ps1`, remember to set `$ErrorActionPreference = "Continue"` to ensure that `Write-Error` messages are not treated as terminating errors. + +**Run all tests** + +```PowerShell +run-tests.ps1 +``` + +**Run tests for specific function** + +To execute tests for a specific method, use `-Tag` parameter. This parameter accepts a string or comma-separated list of specific commands/functions in this module to run tests on. This utilizes the [`Tag` parameter](https://pester.dev/docs/usage/tags) in Pester framework. + +```PowerShell +run-tests.ps1 -Tag "Initialize-NatNetwork" +``` + +**Run tests for specific file** + +To execute tests for a specific module files (.psm1), use `-ModuleName` parameter. This parameter accepts a string or a comma-separated list of specific commands or functions in this module to run tests on. + +```PowerShell +run-tests.ps1 -ModuleName ContainerNetworkTools.psm1 +``` + +**NOTE:** _The file extension (.psm1) is optional._ + +**Change verbosity of test output** + +To change the verbosity of the output, use `-Verbosity` parameter. Options are None, Normal, Detailed and Diagnostic. Default value: 'Detailed' + +```PowerShell +run-tests.ps1 -Verbosity Normal +``` + +## Recommended Workflow + +### Forks and Pull Requests + +GitHub fosters collaboration through the notion of [pull requests][using-prs]. On GitHub, anyone can [fork][fork-a-repo] an existing repository into their own user account, where they can make private changes to their fork. To contribute these changes back into the original repository, a user simply creates a pull request in order to "request" that the changes be taken "upstream". + +Additional references: + +- GitHub's guide on [forking](https://guides.github.com/activities/forking/) +- GitHub's guide on [Contributing to Open Source](https://guides.github.com/activities/contributing-to-open-source/#pull-request) +- GitHub's guide on [Understanding the GitHub Flow](https://guides.github.com/introduction/flow/) + +### How to submit pull requests + +To make changes to content, submit a pull request (PR) from your fork. Always create a pull request to the master branch of this repository. A pull request must be reviewed before it can be merged. See guide on [how to submit a pull request](https://learn.microsoft.com/en-us/powershell/scripting/community/contributing/pull-requests?view=powershell-7.4). + +### Suggested Workflow + +We use and recommend the following workflow: + +1. Create an issue for your work. + - You can skip this step for trivial changes. + - Reuse an existing issue on the topic, if there is one. + - Get agreement from the team and the community that your proposed change is a good one. + - Clearly state that you are going to take on implementing it, if that's the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer do not have to be the same person. +1. Create a personal fork of the repository on GitHub (if you do not already have one). +1. In your fork, create a branch off of main (`git checkout -b mybranch`). + - Name the branch so that it clearly communicates your intentions, such as issue-123 or githubhandle-issue. + - Branches are useful since they isolate your changes from incoming changes from upstream. They also enable you to create multiple PRs from the same fork. +1. Make and commit your changes to your branch. +1. Add new tests corresponding to your change, if applicable. +1. Build the repository with your changes. + - Make sure that the builds are clean. + - Make sure that the tests are all passing, including your new tests. + - Fix any linting/styling issues. + Run the [Script Analyzer](#linting) +1. Create a pull request (PR) against the [`microsoft/containers-toolkit`](https://github.com/microsoft/containers-toolkit/compare) repository's **main** branch. + - State in the description what issue or improvement your change is addressing. + - Check if all the tests are passing. +1. Wait for feedback or approval of your changes from the team. +1. When the team has signed off, and all checks are green, your PR will be merged. + - The next official build will include your change. + - You can delete the branch you used for making the change. + +## Attribution + +_Parts of the guideline adopted from [PowerShell CONTRIBUTING.md](https://github.com/PowerShell/PowerShell/blob/master/.github/CONTRIBUTING.md) and [.Net Monitor](https://github.com/dotnet/dotnet-monitor/blob/main/CONTRIBUTING.md)._ diff --git a/LICENSE b/LICENSE index 9e841e7..4425c7e 100644 --- a/LICENSE +++ b/LICENSE @@ -1,7 +1,7 @@ - MIT License - Copyright (c) Microsoft Corporation. + MIT License + Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights @@ -12,10 +12,10 @@ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - SOFTWARE + SOFTWARE. diff --git a/README.md b/README.md index bd8cb67..16b922c 100644 --- a/README.md +++ b/README.md @@ -14,79 +14,52 @@ ## Table of contents 1. [Introduction](#introduction) -2. [Usage](#usage) - - [Installing and importing Containers-Toolkit module](#installing-and-importing-containers-toolkit-module) - - [](#download-source-files) - - [Command reference](#command-reference) -3. [Important Notes](#important-notes) -4. [Contribution](#contribution) -5. [Related Projects](#related-projects) +1. [Prerequisites](#prerequisites) +1. [Installation and Setup](#installation-and-setup) +1. [Usage](#usage) +1. [Important Notes](#important-notes) +1. [Contribution](#contribution) ## Introduction -Containers-Toolkit is a Windows PowerShell module for downloading, installing, and setting up default configs for Containerd, BuildKit, Windows CNI plugin, and nerdctl. +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. -## Usage - -### Installing and importing Containers-Toolkit module - -#### Install the module from PowerShell Gallery - -> COMING SOON: We are currently working on publishing this module to PS Gallery to make it easier to import the module - -#### Download Source files - -> Coming soon - -#### Clone the repo +Configurations done with these functions are default configurations that allow you to get started with interacting with the tools. Further configurations may be necessary. +You can find documentation for these functions here: [Containers-Toolkit Documentation](https://github.com/microsoft/containers-toolkit/tree/main/docs/command-reference.md) -**Option 1:** Clone containers-toolkit into one of the folder locations in the `$env:PSModulePath` environment variable. +## Prerequisites -1. To get a possible module path: +This module requires `ThreadJob` and `HNS` modules. - ```PowerShell - $env:PSModulePath -split ";" - ``` - -2. Clone the repo +1. `ThreadJob` module - ```PowerShell - cd - git clone https://github.com/microsoft/containers-toolkit.git + ```powershell + Install-Module -Name ThreadJob -Force ``` -3. Import the module +1. `HNS` module - ```PowerShell - Import-Module -Name containers-toolkit -Force - ``` + To install the HNS module, follow the [instructions here](./docs/FAQs.md#2-new-hnsnetwork-command-does-not-exist) -**Option 2:** Clone containers-toolkit to a folder location of choice and add the new module location to the Windows PowerShell module path + **Reference:** + - [HostNetworkingService](https://docs.microsoft.com/en-us/powershell/module/hostnetworkingservice/?view=windowsserver2022-ps) + - [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) -1. Clone the repo +## Installation and Setup - ```PowerShell - git clone https://github.com/microsoft/containers-toolkit.git - ``` +### Install Containers-Toolkit module from PowerShell Gallery -1. Add the directory to Windows PowerShell module path +> COMING SOON: We are currently working on publishing this module to PS Gallery to make it easier to import the module - ```PowerShell - $env:PSModulePath += ";" - ``` +### Download signed source files -1. Install module dependencies +> Coming soon - ```powershell - Install-Module -Name ThreadJob -Force - Install-Module -Name HNS -AllowClobber -Force - ``` +### Downloading the source code from Containers-Toolkit repository -1. Import the module +To use the module, fork/clone the repository to your local machine and [setup your development environment](./CONTRIBUTING.md#setup-development-environment) - ```PowerShell - Import-Module -Name containers-toolkit -Force - ``` +## Usage ### Get the module details @@ -149,42 +122,29 @@ Get-Command -Module containers-toolkit Enable-WindowsOptionalFeature -Online -FeatureName '' -All -NoRestart ``` -1. Requires PowerShell modules [HNS](https://www.powershellgallery.com/packages/HNS) and [ThreadJob](https://www.powershellgallery.com/packages/ThreadJob) +1. Requires PowerShell modules [HNS](https://raw.githubusercontent.com/microsoft/SDN/master/Kubernetes/windows/hns.v2.psm1) and [ThreadJob](https://www.powershellgallery.com/packages/ThreadJob) ## FAQs -1. Error when running Import-Module - - [Error when running Import-Module](https://vnote42.net/2019/07/30/error-when-running-import-module/) - - [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) - - [Unblock-File](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/unblock-file?view=powershell-7.4) - -## TODO - -- [ ] Set up GitWorkflow files: - - [GitHub Repository Structure Best Practices](https://medium.com/code-factory-berlin/github-repository-structure-best-practices-248e6effc405) - - Setup ARM64 [self-hosted runner](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) - - Dependabot to update version in main + Licence -- [ ] Pipeline configuration: - - Code Analysis with [DevSkim](https://aka.ms/DevSkim) -- [ ] Publish module to PSGallery -- [ ] Fix Code analysis warnings -- [ ] Dev install: (Hacks) Add functions in Containerd and BuildKit to build from source files. (Is this really necessary? May be an overkill) -- [ ] Publish to Microsoft Learn: [MicrosoftDocs -/ -Virtualization-Documentation](https://github.com/MicrosoftDocs/Virtualization-Documentation/tree/live/virtualization/windowscontainers) - - [Contribute to the Microsoft Learn platform](https://learn.microsoft.com/en-us/contribute/content/?source=recommendations) -- [x] Rename this module to containerstoolkit: The current name for this module might cause confusion with repository named windows-containers-tools -- [x] Update README.md (Documentation) -- [x] Update containers-toolkit/containers-toolkit.Format.ps1xml (Documentation) -- [x] Update Containers-Toolkit/Containers-ToolkitlsForWindows.help.txt (Documentation) -- [x] Use Containers-Toolkit -- [x] Add Pester test -- [x] Replace GitHub username in URL: -- [ ] ~~Rootless installation~~: Not needed for Windows +Please visit the [FAQs.md](./docs/FAQs.md) to see the how to resolve common issues. ## Contribution -## Related Projects +Please look into the [Contribution Guide](./CONTRIBUTING.md) to know how to develop and contribute. + +## Legal and Licensing + +PowerShell is licensed under the [MIT license](./LICENSE). + +## Code of Conduct + +Please see our [Code of Conduct](./CODE_OF_CONDUCT.md) before participating in this project. + +## Security Policy + +For any security issues, please see our [Security Policy](./SECURITY.md). + +## Attributions This project builds on work done by others to create a PowerShell module. diff --git a/SECURITY.md b/SECURITY.md index b3c89ef..7b4732d 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,6 +1,6 @@ -## Security +# Security 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). diff --git a/containers-toolkit/Private/UpdateEnvironmentPath.psm1 b/containers-toolkit/Private/UpdateEnvironmentPath.psm1 index 24d5390..5a29c33 100644 --- a/containers-toolkit/Private/UpdateEnvironmentPath.psm1 +++ b/containers-toolkit/Private/UpdateEnvironmentPath.psm1 @@ -27,7 +27,7 @@ function Update-EnvironmentPath { ) process { - if ($PSCmdlet.ShouldProcess($InstallPath, "$path will be added to environment path")) { + if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, "$path will be added to environment path")) { # Get current environment path $parsedPathString = switch ($PathType) { "System" { diff --git a/containers-toolkit/Public/AllToolsUtilities.psm1 b/containers-toolkit/Public/AllToolsUtilities.psm1 index b21fee8..e44277e 100644 --- a/containers-toolkit/Public/AllToolsUtilities.psm1 +++ b/containers-toolkit/Public/AllToolsUtilities.psm1 @@ -92,7 +92,7 @@ function Install-ContainerTools { } process { - if ($PSCmdlet.ShouldProcess($InstallPath, $WhatIfMessage)) { + if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { Write-Output "Tools to install: $toInstallString" # Global Variables needed for the script diff --git a/containers-toolkit/Public/BuildkitTools.psm1 b/containers-toolkit/Public/BuildkitTools.psm1 index 94e29ab..743ad94 100644 --- a/containers-toolkit/Public/BuildkitTools.psm1 +++ b/containers-toolkit/Public/BuildkitTools.psm1 @@ -53,18 +53,18 @@ function Install-Buildkit { # Check if Buildkit is alread installed $isInstalled = -not (Test-EmptyDirectory -Path $InstallPath) - $WhatIfMessage = "Buildkit will be installed" + $WhatIfMessage = "Buildkit will be installed at $InstallPath" if ($isInstalled) { - $WhatIfMessage = "Buildkit will be uninstalled and reinstalled" + $WhatIfMessage = "Buildkit will be uninstalled from and reinstalled at $InstallPath" } if ($Setup) { <# Action when this condition is true #> - $WhatIfMessage = "Buildkit will be installed and buildkitd service will be registered and started" + $WhatIfMessage = "Buildkit will be installed at $InstallPath and buildkitd service will be registered and started" } } process { - if ($PSCmdlet.ShouldProcess($InstallPath, $WhatIfMessage)) { + if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { # Check if tool already exists at specified location if ($isInstalled) { $errMsg = "Buildkit already exists at $InstallPath or the directory is not empty" @@ -217,7 +217,7 @@ function Register-BuildkitdService { } process { - if ($PSCmdlet.ShouldProcess("$BuildKitPath\bin\buildkitd.exe", $WhatIfMessage)) { + if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { if (Test-EmptyDirectory -Path $BuildKitPath) { Throw "Buildkit does not exist at $BuildKitPath or the directory is empty" } diff --git a/containers-toolkit/Public/ContainerNetworkTools.psm1 b/containers-toolkit/Public/ContainerNetworkTools.psm1 index 0246784..fe9ac09 100644 --- a/containers-toolkit/Public/ContainerNetworkTools.psm1 +++ b/containers-toolkit/Public/ContainerNetworkTools.psm1 @@ -44,14 +44,14 @@ function Install-WinCNIPlugin { $plugin = "Windows CNI plugins" - $WhatIfMessage = "$plugin will be installed" + $WhatIfMessage = "$plugin will be installed at $WINCNIPath" if ($isInstalled) { - $WhatIfMessage = "$plugin will be uninstalled and reinstalled" + $WhatIfMessage = "$plugin will be uninstalled from and reinstalled at $WINCNIPath" } } process { - if ($PSCmdlet.ShouldProcess($WinCNIPath, $WhatIfMessage)) { + if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { # Check if tool already exists at specified location if ($isInstalled) { $errMsg = "Windows CNI plugins already exists at $WinCNIPath or the directory is not empty" @@ -152,12 +152,12 @@ function Initialize-NatNetwork { $WhatIfMessage = "Initialises a NAT network using Windows CNI plugins installed" if (!$isInstalled) { - $WhatIfMessage = "Installs Windows CNI plugins and initialises a NAT network using Windows CNI plugins installed" + $WhatIfMessage = "Installs Windows CNI plugins at $WinCNIPath and initialises a NAT network using Windows CNI plugins installed" } } process { - if ($PSCmdlet.ShouldProcess($WinCNIPath, $WhatIfMessage)) { + if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { if (!$force) { if (!$ENV:PESTER) { if (-not $PSCmdlet.ShouldContinue('', "Are you sure you want to initialises a NAT network? Missing dependencies (Windows CNI Plugins and HNS module) will be installed if missing.")) { @@ -252,11 +252,11 @@ function Uninstall-WinCNIPlugin { $Path = $Path -replace '(\\bin\\?)$', '' - $WhatIfMessage = "Windows CNI plugins will be uninstalled" + $WhatIfMessage = "Windows CNI plugins will be uninstalled from $path" } process { - if ($PSCmdlet.ShouldProcess($Path, $WhatIfMessage)) { + if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { if (Test-EmptyDirectory -Path $path) { Write-Output "Windows CNI plugins does not exist at $Path or the directory is empty" return diff --git a/containers-toolkit/Public/ContainerdTools.psm1 b/containers-toolkit/Public/ContainerdTools.psm1 index 0e2f007..fe52116 100644 --- a/containers-toolkit/Public/ContainerdTools.psm1 +++ b/containers-toolkit/Public/ContainerdTools.psm1 @@ -42,18 +42,18 @@ function Install-Containerd { # Check if Containerd is alread installed $isInstalled = -not (Test-EmptyDirectory -Path $InstallPath) - $WhatIfMessage = "Containerd will be installed" + $WhatIfMessage = "Containerd will be installed at $InstallPath" if ($isInstalled) { - $WhatIfMessage = "Containerd will be uninstalled and reinstalled" + $WhatIfMessage = "Containerd will be uninstalled from and reinstalled at $InstallPath" } if ($Setup) { <# Action when this condition is true #> - $WhatIfMessage = "Containerd will be installed and containerd service will be registered and started" + $WhatIfMessage = "Containerd will be installed at $InstallPath and containerd service will be registered and started" } } process { - if ($PSCmdlet.ShouldProcess($InstallPath, $WhatIfMessage)) { + if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { # Check if tool already exists at specified location if ($isInstalled) { $errMsg = "Containerd already exists at $InstallPath or the directory is not empty" @@ -142,7 +142,7 @@ function Start-ContainerdService { param() process { - if ($PSCmdlet.ShouldProcess($InstallPath, "")) { + if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, "Starts containerd service")) { Invoke-ServiceAction -Service 'Containerd' -Action 'Start' } else { @@ -160,7 +160,7 @@ function Stop-ContainerdService { param() process { - if ($PSCmdlet.ShouldProcess($InstallPath, "")) { + if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, "Stop containerd service")) { Invoke-ServiceAction -Service 'Containerd' -Action 'Stop' } else { @@ -200,7 +200,7 @@ function Register-ContainerdService { } process { - if ($PSCmdlet.ShouldProcess($containerdExecutable, $WhatIfMessage)) { + if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { if (Test-EmptyDirectory -Path $ContainerdPath) { Throw "Containerd does not exist at $ContainerdPath or the directory is empty" } @@ -233,7 +233,7 @@ function Register-ContainerdService { Write-Debug "Containerd config file: $containerdConfigFile" $output = Invoke-ExecutableCommand -Executable $containerdExecutable -Arguments "config default" - $output.StandardOutput.ReadToEnd() | Out-File -FilePath $containerdConfigFile -Encoding ascii -Force + $output.StandardOutput.ReadToEnd() | Out-File -FilePath $containerdConfigFile -Encoding ascii -Force # Check config file is not empty $isEmptyConfig = Test-ConfFileEmpty -Path "$containerdConfigFile" @@ -294,11 +294,11 @@ function Uninstall-Containerd { $Path = Get-DefaultInstallPath -Tool $tool } - $WhatIfMessage = "Containerd will be uninstalled and containerd service will be stopped and unregistered" + $WhatIfMessage = "Containerd will be uninstalled from $path and containerd service will be stopped and unregistered" } process { - if ($PSCmdlet.ShouldProcess($Path, $WhatIfMessage)) { + if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { if (Test-EmptyDirectory -Path $path) { Write-Output "$tool does not exist at $Path or the directory is empty" return diff --git a/containers-toolkit/Public/NerdctlTools.psm1 b/containers-toolkit/Public/NerdctlTools.psm1 index 32c32ad..6d95cc1 100644 --- a/containers-toolkit/Public/NerdctlTools.psm1 +++ b/containers-toolkit/Public/NerdctlTools.psm1 @@ -89,9 +89,9 @@ function Install-Nerdctl { $toInstall += $dependencies } - $WhatIfMessage = "nerdctl will be installed" + $WhatIfMessage = "nerdctl will be installed at $installPath" if ($isInstalled) { - $WhatIfMessage = "nerdctl will be uninstalled and reinstalled" + $WhatIfMessage = "nerdctl will be uninstalled from and reinstalled at $installPath" } if ($dependencies) { <# Action when this condition is true #> @@ -100,7 +100,7 @@ function Install-Nerdctl { } process { - if ($PSCmdlet.ShouldProcess($InstallPath, $WhatIfMessage)) { + if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { # Check if tool already exists at specified location if ($isInstalled) { $errMsg = "nerdctl already exists at $InstallPath or the directory is not empty" @@ -194,11 +194,11 @@ function Uninstall-Nerdctl { $Path = Get-DefaultInstallPath -Tool "nerdctl" } - $WhatIfMessage = "nerdctl will be uninstalled" + $WhatIfMessage = "nerdctl will be uninstalled from $Path" } process { - if ($PSCmdlet.ShouldProcess($Path, $WhatIfMessage)) { + if ($PSCmdlet.ShouldProcess($env:COMPUTERNAME, $WhatIfMessage)) { if (Test-EmptyDirectory -Path $path) { Write-Output "$tool does not exist at $Path or the directory is empty" return diff --git a/containers-toolkit/containers-toolkit.psd1 b/containers-toolkit/containers-toolkit.psd1 index 44b10f1..3a33e10 100644 --- a/containers-toolkit/containers-toolkit.psd1 +++ b/containers-toolkit/containers-toolkit.psd1 @@ -21,7 +21,16 @@ Copyright = '(c) Microsoft Corporation. All rights reserved.' # Description of the functionality provided by this module - Description = 'PowerShell functions that allow you to download, install, and configure Containerd, Buildkit, nerdctl, and Windows CNI plugins. Requires modules ThreadJob and HNS. If HostNetworkingService module exists, the commands from the HostNetworkingService will be used instead of HNS.' + Description = @" +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. + +Configurations done with these functions are default configurations that allow you to get started with interacting with the tools. Further configurations may be necessary. +You can find documentation for these functions here: [Containers-Toolkit Documentation](https://github.com/microsoft/containers-toolkit/tree/main/docs/command-reference.md) + +This module requires the ThreadJob module. Additionally, it 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. + +Note that the HostNetworkingService module is available only when the Hyper-V Windows feature is enabled. +"@ # Minimum version of the PowerShell engine required by this module PowerShellVersion = '5.0' @@ -42,7 +51,7 @@ # ProcessorArchitecture = '' # Modules that must be imported into the global environment prior to importing this module - RequiredModules = @( 'ThreadJob', "HNS" ) + RequiredModules = @( 'ThreadJob' ) # Assemblies that must be loaded prior to importing this module # RequiredAssemblies = @() @@ -148,7 +157,7 @@ RequireLicenseAcceptance = $true # External dependent modules of this module - ExternalModuleDependencies = @('HNS', 'ThreadJob') + ExternalModuleDependencies = @('ThreadJob') } # End of PSData hashtable diff --git a/containers-toolkit/en-US/about_containers-toolkit.help.txt b/containers-toolkit/en-US/about_containers-toolkit.help.txt index 6c95118..a00c994 100644 --- a/containers-toolkit/en-US/about_containers-toolkit.help.txt +++ b/containers-toolkit/en-US/about_containers-toolkit.help.txt @@ -20,6 +20,9 @@ LONG DESCRIPTION configurations may be necessary. You can find documentation for these functions here: https://github.com/microsoft/containers-toolkit/tree/main/docs/command-reference.md + This module requires the ThreadJob and HNS modules. To install these modules, refer to + https://github.com/microsoft/containers-toolkit/tree/main/docs/README.md#prerequisites + KEYWORDS - Containerd @@ -28,4 +31,3 @@ KEYWORDS - Windows CNI - Windows Containers - Microsoft Windows - diff --git a/docs/About/Show-ContainerTools.md b/docs/About/Show-ContainerTools.md index c365eb2..860975e 100644 --- a/docs/About/Show-ContainerTools.md +++ b/docs/About/Show-ContainerTools.md @@ -77,4 +77,7 @@ Returns an array of [PSCustomObject](https://learn.microsoft.com/en-us/dotnet/ap ## RELATED LINKS -- [Container Tools For Windows](Containers-Toolkit.md) +- [Get-BuildkitLatestVersion](./Get-BuildkitLatestVersion.md) +- [Get-ContainerdLatestVersion](./Get-ContainerdLatestVersion.md) +- [Get-NerdctlLatestVersion](./Get-NerdctlLatestVersion.md) +- [Get-WinCNILatestVersion](./Get-WinCNILatestVersion.md) diff --git a/docs/FAQs.md b/docs/FAQs.md index e7e75ca..1dd11a6 100644 --- a/docs/FAQs.md +++ b/docs/FAQs.md @@ -2,17 +2,17 @@ ## Table of Contents -- [Uninstallation Error (Access to path denied)](#resolving-uninstallation-error-access-to-path-denied) +- [Uninstall Error (Access to path denied)](#resolving-uninstall-error-access-to-path-denied)
-## Resolving uninstallation error (Access to path denied) +## Resolving uninstall error (Access to path denied)
-Resolving uninstallation error (Access to path denied) +Resolving uninstall error (Access to path denied) -If you encounter an Access to path denied error during the uninstallation 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. +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. Example: @@ -22,7 +22,7 @@ takeown /f "C:\ProgramData\containerd" /r /d Y After successfully changing the ownership, you can proceed to remove the folder manually. -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 subfolders and files within it. +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. ![alt text](../assets/child-object-permission.png) diff --git a/linkerrors.txt b/linkerrors.txt new file mode 100644 index 0000000..5e6b809 --- /dev/null +++ b/linkerrors.txt @@ -0,0 +1,2 @@ +(node:48456) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead. +(Use `node --trace-deprecation ...` to show where the warning was created)