How to install PSRule for Azure

PSRule for Azure supports running within continuous integration (CI) systems or locally. It is shipped as a PowerShell module which makes it easy to install and distribute updates.

Task	Options
Run tests within CI pipelines	With GitHub Actions or Azure Pipelines or PowerShell
Run tests locally during development	With Visual Studio Code and PowerShell
Create custom tests for your organization	With Visual Studio Code and PowerShell

Tip

PSRule for Azure provides native integration to popular CI systems such as GitHub Actions and Azure Pipelines. If you are using a different CI system you can use the local install to run on MacOS, Linux, and Windows worker nodes.

With GitHub Actions

GitHub Action

Install and use PSRule for Azure with GitHub Actions by referencing the microsoft/ps-rule action.

StablePre-release

Install the latest stable version of PSRule for Azure.

GitHub Actions

- name: Analyze Azure template files
  uses: microsoft/ps-rule@v2.9.0
  with:
    modules: 'PSRule.Rules.Azure'

Install the latest stable or pre-release version of PSRule for Azure.

GitHub Actions

- name: Analyze Azure template files
  uses: microsoft/ps-rule@v2.9.0
  with:
    modules: 'PSRule.Rules.Azure'
    prerelease: true

This will automatically install compatible versions of all dependencies.

Note

For additional examples on commonly configured parameters see Creating your pipeline.

With Azure Pipelines

Extension

Install and use PSRule for Azure with Azure Pipeline by using extension tasks. Install the extension from the marketplace, then use the ps-rule-assert task in pipeline steps.

StablePre-release

Install the latest stable version of PSRule for Azure.

Azure Pipelines

- task: ps-rule-assert@2
  displayName: Analyze Azure template files
  inputs:
    modules: 'PSRule.Rules.Azure'

Install the latest stable or pre-release version of PSRule for Azure.

Azure Pipelines

- task: ps-rule-install@2
  displayName: Install PSRule for Azure (pre-release)
  inputs:
    module: PSRule.Rules.Azure
    prerelease: true

- task: ps-rule-assert@2
  displayName: Analyze Azure template files
  inputs:
    modules: 'PSRule.Rules.Azure'

This will automatically install compatible versions of all dependencies.

Note

For additional examples on commonly configured parameters see Creating your pipeline.

With Visual Studio Code

Extension

An extension for Visual Studio Code is available. The Visual Studio Code extension includes a built-in task to test locally and configuration schemas.

To learn about Visual Studio Code support see the marketplace extension.

For best results, configure the PSRule.Rules.Azure module using ps-rule.yaml by setting requires and include options.

ps-rule.yaml

requires:
  PSRule.Rules.Azure: '>=1.29.0'

include:
  module:
  - PSRule.Rules.Azure

Note

Currently the Visual Studio Code extension relies on PSRule for Azure installed by PowerShell.

With PowerShell

PSRule for Azure can be installed locally from the PowerShell Gallery using PowerShell. You can also use this option to install on CI workers that are not natively supported.

Prerequisites

Operating System	Tool	Installation Link
Windows	Windows PowerShell 5.1 with .NET Framework 4.7.2 or greater.	link
Windows, MacOS, Linux	PowerShell version 7.3.x or greater.	link

To use PSRule for Azure, PSRule a separate PowerShell module must be installed. The required version will automatically be installed along-side PSRule for Azure.

Additionally, the exporting data from a subscription functionality requires the additional PowerShell modules:

• Az.Accounts
• Az.Resources

Note

Azure PowerShell modules are not installed automatically when installing PSRule for Azure. This has been changed from v1.16.0 due to module dependency chains in Azure DevOps. In most cases these modules will be pre-installed on the CI worker. For private CI workers, consider pre-installing these modules in a previous step.

Installing PowerShell

PowerShell 7.x can be installed on MacOS, Linux, and Windows but is not installed by default. For a list of platforms that PowerShell 7.3 is supported on and install instructions see Get PowerShell.

Getting the modules

Module

PSRule for Azure can be installed or updated from the PowerShell Gallery. Use the following command line examples from a PowerShell terminal to install or update PSRule for Azure.

For the current userFor all users

To install PSRule for Azure for the current user use:

Install-Module -Name 'PSRule.Rules.Azure' -Repository PSGallery -Scope CurrentUser

To update PSRule for Azure for the current user use:

Update-Module -Name 'PSRule.Rules.Azure' -Scope CurrentUser

This will automatically install compatible versions of all dependencies.

To install PSRule for Azure for all users (requires admin/ root permissions) use:

Install-Module -Name 'PSRule.Rules.Azure' -Repository PSGallery -Scope AllUsers

To update PSRule for Azure for all users (requires admin/ root permissions) use:

Update-Module -Name 'PSRule.Rules.Azure' -Scope AllUsers

This will automatically install compatible versions of all dependencies.

Pre-release versions

To use a pre-release version of PSRule for Azure add the -AllowPrerelease switch when calling Install-Module, Update-Module, or Save-Module cmdlets.

Tip

To install pre-release module versions, the latest version of PowerShellGet may be required.

# Install the latest PowerShellGet version
Install-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force

Tip

To install a pre-release version of PSRule and PSRule for Azure, install each in separate steps.

For the current userFor all users

To install PSRule for Azure for the current user use:

Install-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force
Install-Module -Name PSRule -Repository PSGallery -Scope CurrentUser -AllowPrerelease
Install-Module -Name PSRule.Rules.Azure -Repository PSGallery -Scope CurrentUser -AllowPrerelease

Open PowerShell with Run as administrator on Windows or sudo pwsh on Linux.

To install PSRule for Azure for all users (requires admin/ root permissions) use:

Install-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force
Install-Module -Name PSRule -Repository PSGallery -Scope AllUsers -AllowPrerelease
Install-Module -Name PSRule.Rules.Azure -Repository PSGallery -Scope AllUsers -AllowPrerelease

Building from source

Source

PSRule for Azure is provided as open source on GitHub. To build PSRule for Azure from source code:

1. Clone the GitHub repository.
2. Run ./build.ps1 from a PowerShell terminal in the cloned path.

This build script will compile the module and documentation then output the result into out/modules/PSRule.Rules.Azure.

Development dependencies

Operating System	Tool	Overview	Installation Link
Windows	Windows PowerShell	Support for version 5.1 with .NET Framework 4.7.2 or greater.	link
Windows, MacOS, Linux	PowerShell	Version 7.4 or greater is support.	link
-	-	Multiple PowerShell modules are required (PlatyPS, Pester, PSScriptAnalyzer, PowerShellGet, PackageManagement, InvokeBuild, PSRule).	Installed when you run the build.ps1 script
-	.NET	.NET SDK v8 is required.	link
-	Bicep CLI	PSRule depends on the Bicep CLI to expand Bicep modules to ARM	link

The following dependencies will be automatically installed if the required versions are not present:

• PowerShell modules:
  • PlatyPS
  • Pester
  • PSScriptAnalyzer
  • PowerShellGet
  • PackageManagement
  • InvokeBuild
• Bicep CLI

These dependencies are only required for building and running tests for PSRule for Azure.

Troubleshooting

If the ./build.ps1 script fails, you can start troubleshooting this by:

• Checking the prerequisites are installed installed (and the specific versions)
  • Check the PowerShell version enter the following statement in the PowerShell terminal: $PSVersionTable.PSVersion
  • Check the installed .NET version by entering the dotnet --list-sdks command in your terminal.
• Check if your .NET setup is connected to any Nuget repositories and if there's any connectivity or authentication issues.
• Installation of some pre-reqs may require admin privileges.

Limited access networks

If you are on a network that does not permit Internet access to the PowerShell Gallery, download the required PowerShell modules on an alternative device that has access. PowerShell provides the Save-Module cmdlet that can be run from a PowerShell terminal to do this.

The following command lines can be used to download the required modules using a PowerShell terminal. After downloading the modules, copy the module directories to devices with restricted Internet access.

Runtime modulesDevelopment modules

To save PSRule for Azure for offline use:

$modules = @('PSRule', 'PSRule.Rules.Azure', 'Az.Accounts', 'Az.Resources')
Save-Module -Name $modules -Path '.\modules'

This will save PSRule for Azure and all dependencies into the modules sub-directory.

To save PSRule for Azure development module dependencies for offline use:

$modules = @('PSRule', 'Az.Accounts', 'Az.Resources', 'PlatyPS', 'Pester',
  'PSScriptAnalyzer', 'PowerShellGet', 'PackageManagement', 'InvokeBuild')
Save-Module -Name $modules -Repository PSGallery -Path '.\modules';

This will save required developments dependencies into the modules sub-directory.

Comments