2019-04-30 02:02:02 +03:00
# PSRule for Azure
2024-06-10 08:36:18 +03:00
A suite of rules to test Azure resources and infrastructure as code (IaC) using PSRule.
2019-04-30 02:02:02 +03:00
2022-04-26 16:49:49 +03:00
[![Open in vscode.dev ](https://img.shields.io/badge/Open%20in-vscode.dev-blue )][1]
2019-04-30 02:02:02 +03:00
2019-12-07 15:38:05 +03:00
Features of PSRule for Azure include:
2023-02-12 17:00:53 +03:00
- [Learn by example][6] - Fix issues quickly, and learn how to improve your Infrastructure as Code..
- [Framework aligned][7] - Apply principals of Azure Well-Architected Framework to your workloads.
2023-10-01 06:26:33 +03:00
- [Start day one][2] - Leverage over 400 pre-built rules to test Azure resources.
2023-02-12 17:00:53 +03:00
- [DevOps integrated][3] - Test Azure infrastructure as code such as Bicep or Azure Resource Manager templates.
- [Cross-platform][4] - Run locally or in the cloud on MacOS, Linux, and Windows.
- [Open community][8] - Open source rules for the Azure community.
2022-04-26 16:49:49 +03:00
[1]: https://vscode.dev/github/Azure/PSRule.Rules.Azure
2023-02-12 17:00:53 +03:00
[2]: https://azure.github.io/PSRule.Rules.Azure/features/#start-day-one
[3]: https://azure.github.io/PSRule.Rules.Azure/features/#devops-integrated
2022-04-26 16:49:49 +03:00
[4]: https://azure.github.io/PSRule.Rules.Azure/features/#cross-platform
2023-02-12 17:00:53 +03:00
[6]: https://azure.github.io/PSRule.Rules.Azure/features/#learn-by-example
[7]: https://azure.github.io/PSRule.Rules.Azure/features/#framework-aligned
[8]: https://azure.github.io/PSRule.Rules.Azure/license-contributing/
2019-12-07 15:38:05 +03:00
2021-01-23 16:32:36 +03:00
## Project objectives
1. **Ready to go** :
2022-04-26 16:49:49 +03:00
- Provide a [Azure Well-Architected Framework][5] aligned suite of rules for validating Azure resources.
2021-01-23 16:32:36 +03:00
- Provide meaningful information to allow remediation.
2. **DevOps** :
2024-06-10 08:36:18 +03:00
- Resources and Azure code can be tested before deployment within DevOps workflows.
- Allow pull request (PR) validation to prevent invalid configuration from being merged.
2021-01-23 16:32:36 +03:00
3. **Enterprise ready** :
- Rules can be directly adopted and additional enterprise specific rules can be layed on.
- Provide regular baselines to allow progressive adoption.
2023-11-28 18:56:40 +03:00
[5]: https://learn.microsoft.com/azure/well-architected/
2022-04-26 16:49:49 +03:00
2020-09-20 07:14:17 +03:00
## Support
2019-04-30 02:02:02 +03:00
2020-09-20 07:14:17 +03:00
This project uses GitHub Issues to track bugs and feature requests.
2021-04-21 19:05:28 +03:00
Before logging an issue please see our [troubleshooting guide].
2020-09-20 07:14:17 +03:00
Please search the existing issues before filing new issues to avoid duplicates.
2019-04-30 02:02:02 +03:00
2021-01-08 04:35:01 +03:00
- For new issues, file your bug or feature request as a new [issue].
- For help, discussion, and support questions about using this project, join or start a [discussion].
2019-04-30 02:02:02 +03:00
2023-11-28 18:56:40 +03:00
If you have any problems with the [PSRule][engine] engine, please check the project GitHub [issues ](https://github.com/microsoft/PSRule/issues ) page instead.
2019-05-17 02:29:23 +03:00
2020-09-20 07:14:17 +03:00
Support for this project/ product is limited to the resources listed above.
2019-05-17 02:29:23 +03:00
## Getting the modules
2023-02-22 09:58:41 +03:00
This project requires the `PSRule` and `Az` PowerShell modules. For details on each see [install][10].
2019-05-17 02:29:23 +03:00
You can download and install these modules from the PowerShell Gallery.
Module | Description | Downloads / instructions
------ | ----------- | ------------------------
2023-02-22 09:58:41 +03:00
PSRule.Rules.Azure | Validate Azure resources and infrastructure as code using PSRule. | [latest][9] / [instructions][10]
For rule and integration modules see [related projects][11].
[9]: https://www.powershellgallery.com/packages/PSRule.Rules.Azure
2024-01-03 10:02:59 +03:00
[10]: https://azure.github.io/PSRule.Rules.Azure/install/
2023-02-22 09:58:41 +03:00
[11]: https://azure.github.io/PSRule.Rules.Azure/related-projects/
2019-05-17 02:29:23 +03:00
## Getting started
2019-12-07 15:38:05 +03:00
PSRule for Azure provides two methods for analyzing Azure resources:
- _Pre-flight_ - Before resources are deployed from Azure Resource Manager templates.
2021-07-14 05:36:05 +03:00
- _In-flight_ - After resources are deployed to an Azure subscription.
2019-12-07 15:38:05 +03:00
2021-01-08 04:35:01 +03:00
For specific use cases see [scenarios ](#scenarios ).
2023-07-11 15:46:55 +03:00
For additional details see the [FAQ][12].
To get started with a sample repository, see [PSRule for Azure Quick Start][13] on GitHub.
[12]: https://azure.github.io/PSRule.Rules.Azure/faq/
[13]: https://github.com/Azure/PSRule.Rules.Azure-quickstart
2019-12-07 15:38:05 +03:00
2021-01-08 04:35:01 +03:00
### Using with GitHub Actions
2021-08-29 12:43:13 +03:00
The following example shows how to setup GitHub Actions to validate templates pre-flight.
2021-01-08 04:35:01 +03:00
1. See [Creating a workflow file][create-workflow].
2024-06-10 08:36:18 +03:00
2. Reference `microsoft/ps-rule` with `modules: 'PSRule.Rules.Azure'` .
2021-01-08 04:35:01 +03:00
For example:
```yaml
# Example: .github/workflows/analyze-arm.yaml
#
# STEP 1: Template validation
#
name: Analyze templates
on:
2021-12-28 17:03:09 +03:00
push:
branches:
- main
pull_request:
branches:
- main
2021-01-08 04:35:01 +03:00
jobs:
analyze_arm:
name: Analyze templates
runs-on: ubuntu-latest
steps:
- name: Checkout
2022-03-26 09:40:38 +03:00
uses: actions/checkout@v3
2021-01-08 04:35:01 +03:00
2021-08-25 03:01:00 +03:00
# STEP 2: Run analysis against exported data
2021-01-08 04:35:01 +03:00
- name: Analyze Azure template files
2023-06-28 09:29:18 +03:00
uses: microsoft/ps-rule@v2.9.0
2021-01-08 04:35:01 +03:00
with:
modules: 'PSRule.Rules.Azure' # Analyze objects using the rules within the PSRule.Rules.Azure PowerShell module.
```
2019-05-17 02:29:23 +03:00
2021-01-08 04:35:01 +03:00
### Using with Azure Pipelines
2019-05-17 02:29:23 +03:00
2021-01-08 04:35:01 +03:00
The following example shows how to setup Azure Pipelines to validate templates pre-flight.
2019-06-05 16:51:59 +03:00
2021-01-08 04:35:01 +03:00
1. Install [PSRule extension][extension] for Azure DevOps marketplace.
2. Create a new YAML pipeline with the _Starter pipeline_ template.
3. Add the `Install PSRule module` task.
- Set module to `PSRule.Rules.Azure` .
2021-08-25 03:01:00 +03:00
4. Add the `PSRule analysis` task.
- Set input type to `repository` .
2021-01-08 04:35:01 +03:00
- Set modules to `PSRule.Rules.Azure` .
For example:
```yaml
# Example: .azure-pipelines/analyze-arm.yaml
#
# STEP 2: Template validation
#
jobs:
- job: 'analyze_arm'
displayName: 'Analyze templates'
pool:
2023-08-20 10:09:09 +03:00
vmImage: 'ubuntu-22.04'
2021-01-08 04:35:01 +03:00
steps:
# STEP 3: Install PSRule.Rules.Azure from the PowerShell Gallery
2022-06-03 03:29:13 +03:00
- task: ps-rule-install@2
2021-01-08 04:35:01 +03:00
displayName: Install PSRule.Rules.Azure
inputs:
module: 'PSRule.Rules.Azure' # Install PSRule.Rules.Azure from the PowerShell Gallery.
2021-08-25 03:01:00 +03:00
# STEP 4: Run analysis against exported data
2022-06-03 03:29:13 +03:00
- task: ps-rule-assert@2
2021-01-08 04:35:01 +03:00
displayName: Analyze Azure template files
inputs:
modules: 'PSRule.Rules.Azure' # Analyze objects using the rules within the PSRule.Rules.Azure PowerShell module.
```
### Using locally
The following example shows how to setup PSRule locally to validate templates pre-flight.
1. Install the `PSRule.Rules.Azure` module and dependencies from the PowerShell Gallery.
2021-08-25 03:01:00 +03:00
2. Run analysis against repository files.
2019-05-17 02:29:23 +03:00
For example:
```powershell
2021-01-08 04:35:01 +03:00
# STEP 1: Install PSRule.Rules.Azure from the PowerShell Gallery
Install-Module -Name 'PSRule.Rules.Azure' -Scope CurrentUser;
2021-08-25 03:01:00 +03:00
# STEP 2: Run analysis against exported data
Assert-PSRule -Module 'PSRule.Rules.Azure' -InputPath 'out/templates/' -Format File;
2019-05-17 02:29:23 +03:00
```
2021-01-08 04:35:01 +03:00
### Export in-flight resource data
The following example shows how to setup PSRule locally to validate resources running in a subscription.
2019-05-17 02:29:23 +03:00
2021-01-08 04:35:01 +03:00
1. Install the `PSRule.Rules.Azure` module and dependencies from the PowerShell Gallery.
2. Connect and set context to an Azure subscription from PowerShell.
3. Export the resource data with the `Export-AzRuleData` cmdlet.
4. Run analysis against exported data.
2019-05-17 02:29:23 +03:00
For example:
```powershell
2021-01-08 04:35:01 +03:00
# STEP 1: Install PSRule.Rules.Azure from the PowerShell Gallery
Install-Module -Name 'PSRule.Rules.Azure' -Scope CurrentUser;
# STEP 2: Authenticate to Azure, only required if not currently connected
Connect-AzAccount;
# Confirm the current subscription context
Get-AzContext;
# STEP 3: Exports a resource graph stored as JSON for analysis
Export-AzRuleData -OutputPath 'out/templates/';
# STEP 4: Run analysis against exported data
Assert-PSRule -Module 'PSRule.Rules.Azure' -InputPath 'out/templates/';
2019-05-17 02:29:23 +03:00
```
### Additional options
2021-01-08 04:35:01 +03:00
By default, resource data for the current subscription context will be exported.
2019-05-17 02:29:23 +03:00
2019-06-05 16:51:59 +03:00
To export resource data for specific subscriptions use:
2019-05-17 02:29:23 +03:00
- `-Subscription` - to specify subscriptions by id or name.
- `-Tenant` - to specify subscriptions within an Azure Active Directory Tenant by id.
For example:
```powershell
2019-07-01 04:45:04 +03:00
# Export data from two specific subscriptions
2021-01-08 04:35:01 +03:00
Export-AzRuleData -Subscription 'Contoso Production', 'Contoso Non-production';
2019-05-17 02:29:23 +03:00
```
2019-07-01 04:45:04 +03:00
To export specific resource data use:
- `-ResourceGroupName` - to filter resources by Resource Group.
- `-Tag` - to filter resources based on tag.
For example:
```powershell
# Export information from two resource groups within the current subscription context
2021-01-08 04:35:01 +03:00
Export-AzRuleData -ResourceGroupName 'rg-app1-web', 'rg-app1-db';
2019-07-01 04:45:04 +03:00
```
2019-06-05 16:51:59 +03:00
To export resource data for all subscription contexts use:
- `-All` - to export resource data for all subscription contexts.
For example:
```powershell
# Export data from all subscription contexts
Export-AzRuleData -All;
```
2019-11-09 09:19:07 +03:00
To filter results to only failed rules, use `Invoke-PSRule -Outcome Fail` .
Passed, failed and error results are shown by default.
2019-05-17 17:30:01 +03:00
For example:
```powershell
# Only show failed results
2021-01-08 04:35:01 +03:00
Invoke-PSRule -InputPath 'out/templates/' -Module 'PSRule.Rules.Azure' -Outcome Fail;
2019-05-17 17:30:01 +03:00
```
The output of this example is:
```text
TargetName: storage
2019-06-13 01:38:36 +03:00
RuleName Outcome Recommendation
-------- ------- --------------
2019-05-17 17:30:01 +03:00
Azure.Storage.UseReplication Fail Storage accounts not using GRS may be at risk
2019-05-19 10:57:11 +03:00
Azure.Storage.SecureTransferRequ... Fail Storage accounts should only accept secure traffic
Azure.Storage.SoftDelete Fail Enable soft delete on Storage Accounts
2019-05-17 17:30:01 +03:00
```
A summary of results can be displayed by using `Invoke-PSRule -As Summary` .
For example:
```powershell
# Display as summary results
2021-01-08 04:35:01 +03:00
Invoke-PSRule -InputPath 'out/templates/' -Module 'PSRule.Rules.Azure' -As Summary;
2019-05-17 17:30:01 +03:00
```
The output of this example is:
```text
RuleName Pass Fail Outcome
-------- ---- ---- -------
Azure.ACR.MinSku 0 1 Fail
Azure.AppService.PlanInstanceCount 0 1 Fail
Azure.AppService.UseHTTPS 0 2 Fail
Azure.Resource.UseTags 73 36 Fail
Azure.SQL.ThreatDetection 0 1 Fail
Azure.SQL.Auditing 0 1 Fail
Azure.Storage.UseReplication 1 7 Fail
Azure.Storage.SecureTransferRequ... 2 6 Fail
Azure.Storage.SoftDelete 0 8 Fail
```
2019-11-23 05:42:19 +03:00
## Scenarios
2021-08-15 16:26:28 +03:00
For walk through examples of PSRule for Azure module usage see:
2019-11-23 05:42:19 +03:00
2020-05-25 08:04:02 +03:00
- [Validate Azure resources from templates with Azure Pipelines ](docs/scenarios/azure-pipelines-ci/azure-pipelines-ci.md )
- [Validate Azure resources from templates with continuous integration (CI) ](docs/scenarios/azure-template-ci/azure-template-ci.md )
2021-08-15 16:26:28 +03:00
- [Create a custom rule to enforce Resource Group tagging ](https://azure.github.io/PSRule.Rules.Azure/customization/enforce-custom-tags/ )
- [Create a custom rule to enforce code ownership ](https://azure.github.io/PSRule.Rules.Azure/customization/enforce-codeowners/ )
2019-11-23 05:42:19 +03:00
2019-05-17 02:29:23 +03:00
## Rule reference
2022-04-26 16:49:49 +03:00
PSRule for Azure includes rules across five pillars of the [Microsoft Azure Well-Architected Framework][5].
2020-08-28 06:27:27 +03:00
2021-06-17 18:34:37 +03:00
- [Rules for architecture excellence ](https://azure.github.io/PSRule.Rules.Azure/en/rules/module/ )
- [Cost Optimization ](https://azure.github.io/PSRule.Rules.Azure/en/rules/module/#costoptimization )
- [Operational Excellence ](https://azure.github.io/PSRule.Rules.Azure/en/rules/module/#operationalexcellence )
- [Performance Efficiency ](https://azure.github.io/PSRule.Rules.Azure/en/rules/module/#performanceefficiency )
- [Reliability ](https://azure.github.io/PSRule.Rules.Azure/en/rules/module/#reliability )
- [Security ](https://azure.github.io/PSRule.Rules.Azure/en/rules/module/#security )
2020-08-28 06:27:27 +03:00
To view a list of rules by Azure resources see:
2019-05-17 02:29:23 +03:00
2021-06-17 18:34:37 +03:00
- [Rules by resource ](https://azure.github.io/PSRule.Rules.Azure/en/rules/resource/ )
2019-05-17 02:29:23 +03:00
2020-06-21 11:14:32 +03:00
## Baseline reference
2024-06-10 08:36:18 +03:00
For a list of baselines you can use in your configuration see [Baselines ](https://azure.github.io/PSRule.Rules.Azure/en/baselines/ ).
2020-06-21 11:14:32 +03:00
2019-05-17 02:29:23 +03:00
## Language reference
2020-06-21 11:14:32 +03:00
PSRule for Azure extends PowerShell with the following cmdlets.
2019-05-17 02:29:23 +03:00
### Commands
2021-12-28 17:03:09 +03:00
PSRule for Azure included the following cmdlets:
2019-05-17 02:29:23 +03:00
2021-06-17 16:55:40 +03:00
- [Export-AzRuleData ](docs/commands/Export-AzRuleData.md ) - Export resource configuration data from Azure subscriptions.
- [Export-AzRuleTemplateData ](docs/commands/Export-AzRuleTemplateData.md ) - Export resource configuration data from Azure templates.
2022-04-26 16:49:49 +03:00
- [Export-AzPolicyAssignmentData ](docs/commands/Export-AzPolicyAssignmentData.md ) - Export policy assignment data.
- [Export-AzPolicyAssignmentRuleData ](docs/commands/Export-AzPolicyAssignmentRuleData.md ) - Export JSON based rules from policy assignment data.
2021-06-17 16:55:40 +03:00
- [Get-AzRuleTemplateLink ](docs/commands/Get-AzRuleTemplateLink.md ) - Get a metadata link to a Azure template file.
2022-04-26 16:49:49 +03:00
- [Get-AzPolicyAssignmentDataSource ](docs/commands/Get-AzPolicyAssignmentDataSource.md ) - Get policy assignment sources.
2020-03-20 13:48:01 +03:00
2021-12-28 17:03:09 +03:00
## Concepts
2022-03-26 09:40:38 +03:00
To find out more, look at these conceptual topics:
2021-12-28 17:03:09 +03:00
- Getting started:
2023-07-11 15:46:55 +03:00
- [How to install PSRule for Azure ](https://azure.github.io/PSRule.Rules.Azure/install/ )
2021-12-28 17:03:09 +03:00
- [Creating your pipeline ](https://azure.github.io/PSRule.Rules.Azure/creating-your-pipeline/ )
- Testing infrastructure as code:
- [Expanding source files ](https://azure.github.io/PSRule.Rules.Azure/expanding-source-files/ )
- [Using templates ](https://azure.github.io/PSRule.Rules.Azure/using-templates/ )
2022-07-29 08:36:17 +03:00
- [Using Bicep source ](https://aka.ms/ps-rule-azure/bicep )
2021-12-28 17:03:09 +03:00
- [Working with baselines ](https://azure.github.io/PSRule.Rules.Azure/working-with-baselines/ )
- Setup:
2022-07-29 08:36:17 +03:00
- [Configuring options ](https://aka.ms/ps-rule-azure/options )
2021-12-28 17:03:09 +03:00
- [Configuring rule defaults ](https://azure.github.io/PSRule.Rules.Azure/setup/configuring-rules/ )
- [Configuring expansion ](https://azure.github.io/PSRule.Rules.Azure/setup/configuring-expansion/ )
- [Setup Bicep ](https://azure.github.io/PSRule.Rules.Azure/setup/setup-bicep/ )
2022-07-29 08:36:17 +03:00
- [Setup Azure Monitor logs ](https://aka.ms/ps-rule-azure/monitor )
2019-04-30 02:02:02 +03:00
2020-08-20 10:36:02 +03:00
## Related projects
2023-02-22 09:58:41 +03:00
For a list of projects and integrations see [Related projects][11].
2020-08-20 10:36:02 +03:00
2019-04-30 02:02:02 +03:00
## Changes and versioning
2021-05-02 17:28:53 +03:00
This repository uses [semantic versioning ](http://semver.org/ ) to declare breaking changes.
2023-02-22 09:58:41 +03:00
For details please see the [changes and versioning ](https://azure.github.io/PSRule.Rules.Azure/versioning/ ).
2019-04-30 02:02:02 +03:00
2020-02-06 14:22:54 +03:00
## Contributing
This project welcomes contributions and suggestions.
If you are ready to contribute, please visit the [contribution guide ](CONTRIBUTING.md ).
## Code of Conduct
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/ )
or contact [opencode@microsoft.com ](mailto:opencode@microsoft.com ) with any additional questions or comments.
2019-04-30 02:02:02 +03:00
## Maintainers
- [Bernie White ](https://github.com/BernieWhite )
## License
This project is [licensed under the MIT License ](LICENSE ).
2023-11-08 17:35:41 +03:00
## Trademarks
This project may contain trademarks or logos for projects, products, or services.
Authorized use of Microsoft trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines ](https://www.microsoft.com/legal/intellectualproperty/trademarks ).
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
Any use of third-party trademarks or logos are subject to those third-party's policies.
2021-06-17 17:14:44 +03:00
[issue]: https://github.com/Azure/PSRule.Rules.Azure/issues
[discussion]: https://github.com/Azure/PSRule.Rules.Azure/discussions
2023-02-22 09:58:41 +03:00
[engine]: https://github.com/microsoft/PSRule
2023-11-28 18:56:40 +03:00
[create-workflow]: https://docs.github.com/actions/using-workflows#creating-a-workflow-file
2021-01-08 04:35:01 +03:00
[extension]: https://marketplace.visualstudio.com/items?itemName=bewhite.ps-rule
2021-06-17 18:34:37 +03:00
[troubleshooting guide]: https://azure.github.io/PSRule.Rules.Azure/troubleshooting/