diff --git a/README.md b/README.md index 3d66cc2..7a82e9c 100644 --- a/README.md +++ b/README.md @@ -4,17 +4,26 @@ A suite of rules to validate Azure resources against the Cloud Adoption Framewor ![ci-badge] -**More to come soon.** +Features of PSRule for CAF include: -## Disclaimer +- [Ready to go](docs/features.md#ready-to-go) - Leverage configurable rules to validate Azure resources. +- [DevOps](docs/features.md#devops) - Validate resources and infrastructure code pre or post-deployment. +- [Cross-platform](docs/features.md#cross-platform) - Run on MacOS, Linux, and Windows. -This project is to be considered a **proof-of-concept** and **not a supported product**. +## Support -For issues with rules and documentation please check our GitHub [issues](https://github.com/Microsoft/PSRule.Rules.CAF/issues) page. -If you do not see your problem captured, please file a new issue and follow the provided template. +This project uses GitHub Issues to track bugs and feature requests. +Please search the existing issues before filing new issues to avoid duplicates. + +- For new issues, file your bug or feature request as a new [Issue]. +- For help and questions about using this project, we have a Gitter room which you can join below. + +[![Join the chat][chat-badge]][chat] If you have any problems with the [PSRule][engine] engine, please check the project GitHub [issues](https://github.com/Microsoft/PSRule/issues) page instead. +Support for this project/ product is limited to the resources listed above. + ## Getting the modules This project requires the `PSRule`, `PSRule.Rules.Azure` and `Az` PowerShell modules. For details on each see [install]. @@ -103,7 +112,10 @@ or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any addi This project is [licensed under the MIT License](LICENSE). -[install]: docs/scenarios/install-instructions.md +[issue]: https://github.com/Microsoft/PSRule.Rules.CAF/issues +[install]: docs/install-instructions.md [ci-badge]: https://dev.azure.com/bewhite/PSRule.Rules.CAF/_apis/build/status/PSRule.Rules.CAF-CI?branchName=main [module]: https://www.powershellgallery.com/packages/PSRule.Rules.CAF [engine]: https://github.com/Microsoft/PSRule +[chat]: https://gitter.im/PSRule/PSRule.Rules.CAF?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge +[chat-badge]: https://img.shields.io/static/v1.svg?label=chat&message=on%20gitter&color=informational&logo=gitter diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..b8748a1 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,18 @@ +# Support + +## How to file issues and get help + +This project uses GitHub Issues to track bugs and feature requests. +Please search the existing issues before filing new issues to avoid duplicates. +For new issues, file your bug or feature request as a new Issue. + +For help and questions about using this project, we have a Gitter room which you can join below. + +[![Join the chat][chat-badge]][chat] + +## Microsoft Support Policy + +Support for this project/ product is limited to the resources listed above. + +[chat]: https://gitter.im/PSRule/PSRule.Rules.CAF?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge +[chat-badge]: https://img.shields.io/static/v1.svg?label=chat&message=on%20gitter&color=informational&logo=gitter diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 0000000..4b76bc7 --- /dev/null +++ b/docs/features.md @@ -0,0 +1,85 @@ +# PSRule for Cloud Adoption Framework features + +The following sections describe key features of PSRule for Cloud Adoption Framework (CAF). + +- [Ready to go](#ready-to-go) +- [DevOps](#devops) +- [Cross-platform](#cross-platform) + +## Ready to go + +PSRule for CAF includes rules for validating resources against CAF recommendations. +Each rule includes additional information to help remediate issues. + +Use the built-in rules to start enforcing release processes quickly. +Rules can be configured to customize the implementation for your organization. +Custom rules can be implemented quickly and work side-by-side with built-in rules. + +As new built-in rules are added and improved, download the latest PowerShell module to start using them. + +## DevOps + +Azure resources can be validated throughout their lifecycle to support a DevOps culture. + +From as early as authoring an Azure Resource Manager (ARM) template, resources can be validated offline. +Pre-flight validation can be integrated into a continuous integration (CI) pipeline to: + +- **Shift-left:** Identify configuration issues and provide fast feedback in pull requests. +- **Quality gates:** Implement quality gates between environments such as development, test, and production. +- **Monitor continuously:** Perform ongoing checks for configuration optimization opportunities. + +## Cross-platform + +PSRule uses modern PowerShell libraries at its core, allowing it to go anywhere PowerShell can go. +The companion extension for Visual Studio Code provides snippets for authoring rules and documentation. +PSRule runs on MacOS, Linux and Windows. + +PowerShell makes it easy to integrate PSRule into popular CI systems. +Additionally, PSRule has extensions for: + +- [Azure Pipeline (Azure DevOps)][extension-pipelines] +- [GitHub Actions (GitHub)][extension-github] + +PSRule for CAF (`PSRule.Rules.CAF`) can be installed locally, within a container, or Azure Cloud Shell. +To install, use the `Install-Module` cmdlet within PowerShell. +For installation options see [install instructions](install-instructions.md). + +## Frequently Asked Questions (FAQ) + +Continue reading for FAQ relating to _PSRule for CAF_. +For general FAQ see [PSRule - Frequently Asked Questions (FAQ)][ps-rule-faq], including: + +- [How is PSRule different to Pester?][compare-pester] +- [How do I configure PSRule?][ps-rule-configure] +- [How do I ignore a rule?][ignore-rule] + +### Traditional unit testing vs PSRule for CAF? + +You may already be using a unit test framework such as Pester to test infrastructure code. +If you are, then you may have encountered the following challenges. + +For a general PSRule/ Pester comparison see [How is PSRule different to Pester?][compare-pester] + +#### Unit testing more than basic JSON structure + +Unit tests are unable to effectively test resources contained within Azure templates. +Templates should be reusable, but this creates problems for testing when functions, conditions and copy loops are used. +Template parameters could completely change the type, number of, or configuration of resources. + +PSRule resolves templates to allow analysis of the resources that would be deployed based on provided parameters. + +#### Standard library of tests + +When building unit tests for Azure resources, starting with an empty repository can be a daunting experience. +While there are several open source repositories and samples around to get you started, you need to integrate these yourself. + +_PSRule for CAF_ is distributed as a PowerShell module using the PowerShell Gallery. +Using a PowerShell module makes it easy to install and update. +The built-in rules allow you starting testing resources quickly, with minimal integration. + +[compare-pester]: https://github.com/microsoft/PSRule/blob/main/docs/features.md#how-is-psrule-different-to-pester +[ignore-rule]: https://github.com/microsoft/PSRule/blob/main/docs/features.md#how-do-i-ignore-a-rule +[ps-rule-configure]: https://github.com/microsoft/PSRule/blob/main/docs/features.md#how-do-i-configure-psrule +[ps-rule-faq]: https://github.com/microsoft/PSRule/blob/main/docs/features.md#frequently-asked-questions-faq +[extension-pipelines]: https://marketplace.visualstudio.com/items?itemName=bewhite.ps-rule +[extension-github]: https://github.com/marketplace/actions/psrule diff --git a/docs/scenarios/install-instructions.md b/docs/install-instructions.md similarity index 100% rename from docs/scenarios/install-instructions.md rename to docs/install-instructions.md diff --git a/src/PSRule.Rules.CAF/PSRule.Rules.CAF.psd1 b/src/PSRule.Rules.CAF/PSRule.Rules.CAF.psd1 index b3c9f63..c34325c 100644 --- a/src/PSRule.Rules.CAF/PSRule.Rules.CAF.psd1 +++ b/src/PSRule.Rules.CAF/PSRule.Rules.CAF.psd1 @@ -4,7 +4,6 @@ # # PSRule.Rules.CAF # - @{ # Script module or binary module file associated with this manifest. @@ -31,7 +30,7 @@ Copyright = '(c) Microsoft Corporation. All rights reserved.' # Description of the functionality provided by this module Description = 'A suite of rules to validate Azure resources against the Cloud Adoption Framework (CAF) using PSRule. -This project is to be considered a proof-of-concept and not a supported product.' +This project uses GitHub Issues to track bugs and feature requests. See GitHub project for more information.' # Minimum version of the Windows PowerShell engine required by this module PowerShellVersion = '5.1'