Skip to content

Latest commit

 

History

History
190 lines (126 loc) · 6.16 KB

install-instructions.md

File metadata and controls

190 lines (126 loc) · 6.16 KB
Raw
author
BernieWhite

Installation

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.

!!! 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

:octicons-workflow-24: GitHub Action

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

- name: Analyze Azure template files
  uses: Microsoft/ps-rule@main
  with:
    modules: 'PSRule.Rules.Azure'

This will automatically install compatible versions of all dependencies.

With Azure Pipelines

:octicons-workflow-24: 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.

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

This will automatically install compatible versions of all dependencies.

Installing locally

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.

The following platforms are supported:

  • Windows PowerShell 5.1 with .NET Framework 4.7.2 or greater.
  • PowerShell 7.1 or greater on MacOS, Linux, and Windows.

The following modules are required for PSRule for Azure:

  • PSRule
  • Az.Accounts
  • Az.Resources

The required version of each module will automatically be installed along-side PSRule for Azure.

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.1 is supported on and install instructions see Get PowerShell.

Getting the modules

:octicons-download-24: 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 user" To install PSRule for Azure for the current user use:

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

To update PSRule for Azure for the current user use:

```powershell
Update-Module -Name 'PSRule.Rules.Azure' -Repository PSGallery -Scope CurrentUser
```

This will automatically install compatible versions of all dependencies.

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

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

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

```powershell
Update-Module -Name 'PSRule.Rules.Azure' -Repository PSGallery -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.

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

Building from source

:octicons-file-code-24: 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

The following PowerShell modules will be automatically install if the required versions are not present:

  • PlatyPS
  • Pester
  • PSScriptAnalyzer
  • PowerShellGet
  • PackageManagement
  • InvokeBuild

These additional modules are only required for building PSRule for Azure.

Additionally .NET Core SDK v3.1 is required. .NET Core will not be automatically downloaded and installed. To download and install the latest SDK see Download .NET Core 3.1.

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 modules" To save PSRule for Azure for offline use:

```powershell
$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.

=== "Development modules" To save PSRule for Azure development module dependencies for offline use:

```powershell
$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.

*[CI]: continuous integration