Frequently Asked Questions (FAQ)#

Continue reading for FAQ relating to PSRule for Azure. For general FAQ see PSRule - Frequently Asked Questions (FAQ), including:

Note

If you have a question that is not answered here, please join or start a discussion. For common issues and workarounds, please see troubleshooting.

What is a rule?#

A rule is a named set of checks and documentation. Each rule is tests a specific aspect of an Azure resource or deployment to determine if it is aligned with the Microsoft Azure Well-Architected Framework. You can find the documentation for each rule under reference.

What is a baseline?#

A baseline combines rules and configuration. PSRule for Azure provides several baselines that can be referenced when running PSRule. Quarterly baselines provide a stable checkpoint of rules when you need to stagger adoption of new rules.

Continue reading working with baselines for a detailed breakdown.

What is expansion?#

Expansion is a feature of PSRule for Azure that converts Azure Infrastructure as Code (IaC) to a testable Azure resource. IaC format such as Bicep and ARM templates, support dynamic capabilities such parameters, variables, and conditions... These dynamic capabilities allow customers to create modular reusable code that can scale across an organization. However, to determine if a specific Azure resource meets the requirements of an organization the final state must be known.

Expansion resolves these dynamic capabilities so that a final state for each resource can be tested by rules. Noting the final expanded state provided by PSRule for Azure is a close approximation. This close approximation allows testing of Azure resources offline directly from code before deployment to Azure.

Continue reading Expanding source files.

Is Terraform supported?#

Currently PSRule for Azure supports testing Azure resources from IaC with:

Azure Resource Manager (ARM) templates.
Azure Bicep deployments.

Checking Terraform from HashiCorp Configuration Language (HCL) is not supported at this time. If this feature is important to you, please upvote 👍 the issue on GitHub.

What is supported? After resources are deployed to Azure, PSRule for Azure can be used to check the Azure resources in-flight.

This methods works for Azure resources regardless of how they are deployed. Use this method for analyzing resources deployed via the Azure Portal, Terraform, Pulumi, or other tools.

For instructions on how to do this see Exporting rule data.

What methods are supported for checking resources?#

PSRule for Azure supports two methods for analyzing Azure resources:

Pre-flight — Before resources are deployed from an ARM template or Bicep. Use pre-flight analysis to:
- Implement checks within Pull Requests (PRs).
- Improve alignment of resources to WAF recommendations.
- Identify issues that prevent successful resource deployments on Azure.
- Integrate continual improvement and standardization of Azure resource configurations.
- Implement release gates between environments.
- For more information see Creating your pipeline.
In-flight — After resources are deployed to an Azure subscription. Use in-flight analysis to:
- Implement release gates between environments for non-native tools such as Terraform.
- Performing offline analysis in split-environments.
- For more information see Exporting rule data.

How do I create a custom rule to enforce resource group tagging?#

PSRule for Azure covers common use cases that align to the Microsoft Azure Well-Architected Framework. Use of resource and resource group tags is recommended in the WAF, however implementation may vary. You may want to use PSRule to enforce tagging or something similar early in a DevOps pipeline.

We have a walk through scenario Enforcing custom tags to get you started.

How do I create a custom rule to enforce code ownership?#

GitHub, Azure DevOps, and other DevOps platforms may implement code ownership. This process involves assigning a team or an individual review and approval responsibility. In GitHub or Azure DevOps implementation, ownership is linked to the file path.

When a repository contains resources that different teams would approve how do you:

Ensure resources are created in a path that triggers the correct approval?

We have a walk through scenario Enforcing code ownership to get you started.

Do you have sample code?#

In addition to the walk through scenarios, we have a quick start template here. The repository contains sample ARM templates, Bicep, and pipeline code to get you started.

In GitHub you can simply use the repository as a template for your own project.

Do I need PowerShell experience to start using PSRule for Azure?#

No. You can start using built-in rules and CI with Azure Pipelines or GitHub Actions. If we didn't tell you, you might not even know that PowerShell runs under the covers.

To perform local validation, some PowerShell setup is required but we step you through that. See How to install PSRule for Azure for details.

To start writing your own custom rules you can use YAML, JSON, or PowerShell. PowerShell experience is required for some scenarios. We have a walk through scenario Enforcing custom tags to get you started.

What permissions do I need to export rule data?#

When exporting data for in-flight analysis, the default built-in Reader role to a subscription is required for:

Exporting rule data with Export-AzRuleData.
Exporting rule data from templates with Export-AzRuleTemplateData when online features are used.
- Optionally -ResourceGroupName and -Subscription parameter can be used; these require access Reader access.

What permissions do I need to analyze exported rule data?#

When exporting data for in-flight analysis, no access to Azure is required after data has been exported to JSON.

Should I continue to use Azure Advisor, Defender for Cloud, or Azure Policy?#

Absolutely. PSRule for Azure does not replace Azure Advisor, Microsoft Defender for Cloud, or Azure Policy.

PSRule complements Azure Advisor, Microsoft Defender for Cloud, and Azure Policy features by:

Recommending turning on and using features of Azure Advisor, Microsoft Defender for Cloud, or Azure Policy.
Providing offline analysis in split environments where the analyst has no access to Azure subscriptions. Rule data for analysis can be exported out to a JSON file.
Providing the ability to analyze resources in Azure Resource Manager templates before deployment. Additionally, analysis can be performed in a CI process.
Providing the ability to layer on organization specific rules, as required.
Data collection requires limited permissions and requires no additional configuration.

What do the different severity and levels for rules means?#

PSRule for Azure annotates rules with three (3) severities which indicate how you should prioritize remediation. The following severities are defined:

Critical — Consider addressing these first, ideally within the next thirty (30) days. Rules identified as critical often have high impact and are highly likely to affect your services.
Important — Consider addressing these next, ideally within the next sixty (60) days. Rules identified as important often have a significant impact and are likely to affect your services.
Awareness — Consider addressing these last, ideally within the next ninety (90) days. Rules identified as awareness often have a moderate or low impact to the operation of your services.

Tip

Severities and suggested time frames are an indicator only. They may affect your environment, compliance, or security differently based on your specific requirements. If you feel the severity for a rule is broadly incorrect then please let as know. You can do this by joining or starting a discussion.

Additionally, PSRule for Azure uses three (3) rule levels. These levels determine how PSRule provides feedback about failing cases. The following levels are defined:

Error — Rules defined as error will stop CI pipelines that are configured to break on error.
Warning — Rules defined as warning will not stop CI pipelines and will produce a warning.
Information — Rules defined as information will not stop CI pipelines.

How often are releases shipped?#

PSRule for Azure uses semantic versioning to declare breaking changes.

Major releases are infrequent in nature, but created on an as-needed basis. You can check the upgrade notes to plan for the changes of the next major release.
Minor releases are shipped normally each month.
Patch releases for the most recent minor version are released on an as-needed basis.

The latest module version can be installed from the PowerShell Gallery and NuGet. For a list of module changes please see the change log.

For more information on how we handles versioning and changes see Changes and versioning.

Traditional unit testing vs PSRule for Azure?#

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?

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 Azure 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.

For detailed examples see:

Collection of telemetry#

PSRule and PSRule for Azure currently do not collect any telemetry during installation or execution.

PowerShell (used by PSRule for Azure) does collect basic telemetry by default. Collection of telemetry in PowerShell and how to opt-out is explained in about_Telemetry.