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/markdown-lint.yml b/.github/workflows/markdown-lint.yml new file mode 100644 index 0000000..8b64e6a --- /dev/null +++ b/.github/workflows/markdown-lint.yml @@ -0,0 +1,81 @@ +########################################################################### +# # +# Copyright (c) Microsoft Corporation. All rights reserved. # +# # +# This code is licensed under the MIT License (MIT). # +# # +########################################################################### + +name: Markdown Lint + +on: + pull_request: + branches: + - main + - "releases/**" + paths: + - "docs/**" + - "README.md" + - en-US/**" + +permissions: + contents: read + +jobs: + markdown-check: + runs-on: windows-latest + continue-on-error: true + steps: + - uses: actions/checkout@v4 + + - name: Install npm dependencies + run: npm install -g markdown-link-check textlint textlint-rule-spelling dictionary-en textlint-filter-rule-comments + + - name: Markdown link check + shell: pwsh + run: | + # Check all markdown files in the repository + $mlc_error_file = "link-errors.txt" + Remove-Item -Path $mlc_error_file -Recurse -Force -ErrorAction SilentlyContinue + Get-ChildItem -Path "README.md", ".\docs\" -Filter "*.md" -Recurse | ` + ForEach-Object { & markdown-link-check $_.FullName -q 2>>$mlc_error_file } + + # Check if the error file exists + if (-not (Test-Path "$mlc_error_file")) { + return + } + + # Check if the error file file contains errors + if (Select-String -Path "$mlc_error_file" -Pattern "ERROR: ") { + $errormsg = "Broken links found. Please check the output for more information." + $Link_Check_Summary = ":x: [Markdown Link Check] $errormsg" + echo $Link_Check_Summary >> $env:GITHUB_STEP_SUMMARY + throw $errormsg + } + 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" + Remove-Item -Path $sc_error_file -Recurse -Force -ErrorAction SilentlyContinue + 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." + cat $sc_error_file + } + echo $Spell_Check_Summary >> $env:GITHUB_STEP_SUMMARY diff --git a/.textlintrc.json b/.textlintrc.json index 073e5e8..ecfc339 100644 --- a/.textlintrc.json +++ b/.textlintrc.json @@ -1,35 +1,54 @@ { - "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": { + "comments": true + }, + "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..0475613 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/containers-toolkit/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 f15b91c..4d330fc 100644 --- a/README.md +++ b/README.md @@ -14,83 +14,53 @@ ## Table of contents 1. [Introduction](#introduction) +1. [Prerequisites](#prerequisites) +1. [Installation and Setup](#installation-and-setup) 1. [Usage](#usage) - - [Installing and importing Containers-Toolkit module](#installing-and-importing-containers-toolkit-module) - - [Command reference](#command-reference) 1. [Important Notes](#important-notes) 1. [FAQs](#faqs) 1. [Contribution](#contribution) -1. [Related Projects](#related-projects) ## 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 - -**Option 1:** Clone containers-toolkit into one of the folder locations in the `$env:PSModulePath` environment variable. +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) -1. **To get a possible module path:** +## Prerequisites - ```PowerShell - $env:PSModulePath -split ";" - ``` +This module requires `ThreadJob` and `HNS` modules. -1. **Clone the repo** +1. `ThreadJob` module - ```PowerShell - cd - git clone https://github.com/microsoft/containers-toolkit.git + ```powershell + Install-Module -Name ThreadJob -Force ``` -1. **Import the module** +1. `HNS` module - ```PowerShell - Import-Module -Name containers-toolkit -Force - ``` - -**Option 2:** Clone containers-toolkit to a folder location of choice and add the new module location to the Windows PowerShell module path + To install the HNS module, follow the [instructions here](./docs/FAQs.md#2-new-hnsnetwork-command-does-not-exist) -1. **Clone the repo** + **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) - ```PowerShell - git clone https://github.com/microsoft/containers-toolkit.git - ``` +## Installation and Setup -1. **Add the directory to Windows PowerShell module path** +### Install Containers-Toolkit module from PowerShell Gallery - ```PowerShell - $env:PSModulePath += ";" - ``` - -1. **Install module dependencies** - - Install `ThreadJob` module +> COMING SOON: We are currently working on publishing this module to PS Gallery to make it easier to import the module - ```powershell - Install-Module -Name ThreadJob -Force - ``` +### Download signed source files - - Install `HNS` module +> Coming soon - To install the HNS module. follow the instructions here [instructions](./docs/FAQs.md#2-new-hnsnetwork-command-does-not-exist) +### 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 @@ -153,23 +123,37 @@ 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 -See [FAQs.md](./docs/FAQs.md) +Please visit the [FAQs.md](./docs/FAQs.md) to see the how to resolve common issues. ## Contribution -See [CONTRIBUTING.md](./CONTRIBUTING.md) +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. -## Related Projects +## Security Policy + +For any security issues, please see our [Security Policy](./SECURITY.md). + +## Attributions This project builds on the work of others to create a PowerShell module. Credits (in alphabetic order): -| Repo/ Author | Link | + + +| Author/Repository | Link | |------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Anthony Nandaa (@profnandaa) | [cni-setup-legacy.ps1](https://gist.github.com/profnandaa/33d65d85964181a42539bfd0b4f9561a) | | Gabriel Samfira (@gabriel-samfira) | [setup_buildkitd_on_windows.ps1](https://gist.github.com/gabriel-samfira/6e56238ad11c24f490ac109bdd378471) | @@ -180,6 +164,8 @@ Credits (in alphabetic order): | microsoft/Windows-Containers | [install-containerd-runtime.ps1](https://github.com/microsoft/Windows-Containers/blob/Main/helpful_tools/Install-ContainerdRuntime/install-containerd-runtime.ps1) | | Mirantis | [Install MCR on Windows Servers](https://docs.mirantis.com/mcr/20.10/install/mcr-windows.html) | + + ## Container tools installed with this module - [Containerd](https://github.com/containerd/containerd) 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/containers-toolkit.psd1 b/containers-toolkit/containers-toolkit.psd1 index 39e4826..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' @@ -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 2534c15..96d3fc3 100644 --- a/docs/FAQs.md +++ b/docs/FAQs.md @@ -3,7 +3,7 @@ ## Table of Contents - [`Import-Module` issues](#import-module-issues) -- [Uninstallation issues](#uninstallation-issues) +- [Tool uninstall issues](#tool-uninstall-issues) - [`Initialize-NatNetwork` issues](#initialize-natnetwork-issues) ## `Import-Module` issues @@ -12,7 +12,7 @@ - [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) -## Uninstallation issues +## Tool uninstall issues ### 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: @@ -31,7 +31,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) @@ -87,7 +87,7 @@ You can download it directly from the [microsoft/sdn](https://github.com/microso ```powershell $dirPath = (New-Item -Path "$(Split-Path $PROFILE.CurrentUserCurrentHost)/Modules/HNS" -ItemType Directory -Force).FullName -$Uri = 'https://raw.githubusercontent.com/microsoft/SDN/dd4e8708ed184b49d3fddd611b6027f1755c6edb/Kubernetes/windows/hns.psm1' +$Uri = 'https://raw.githubusercontent.com/microsoft/SDN/dd4e8708ed184b49d3fddd611b6027f1755c6edb/Kubernetes/windows/hns.v2.psm1' Invoke-WebRequest -Uri $Uri -OutFile "$dirPath/hns.psm1" ```