Skip to content

Upgrade notes#

This document contains notes to help upgrade from previous versions of PSRule.

Upgrading to v3.0.0#

Unbound object names#

When an object is processed by PSRule, it is assigned a name. This name is used to identify the object in the output and to suppress the object from future processing.

Prior to v3.0.0, the name was generated using a SHA-1 hash of the object. The SHA-1 algorithm is no longer considered secure and has been replaced with SHA-512.

From v3.0.0, if the name of an object can not be determined, the SHA-512 hash of the object will be used. Any objects that have previously been suppressed with a name based on a SHA-1 hash will no longer be suppressed.

To resolve any issue caused by this change, you can:

  1. Configure binding by setting the Binding.TargetName option to set an alternative property to use as the name. OR

  2. Update any existing keys set with the Suppression option to use the new SHA-512 hash.

Using PowerShell 7.4 or later#

From v3.0.0, PSRule requires:

  • Windows PowerShell 5.1 for running as a PowerShell module. OR
  • PowerShell 7.4 or later for development, building locally, or running as a PowerShell module.

Support for Windows PowerShell 5.1 is deprecated and will be removed in a future release of PSRule (v4). We recommend upgrading to PowerShell 7.4 or later.

Changes to CLI commands#

From v3.0.0, the CLI command names have been renamed to simplify usage. The following changes have been made:

  • To run rules, use run instead of analyze. i.e. ps-rule run.
  • To restore modules for a workspace, use module restore instead of restore. i.e. ps-rule module restore.

The run command provides similar output to the Assert-PSRule cmdlet in PowerShell.

Previously the restore command installed modules based on the configuration of the Requires option. From v3.0.0, the module restore command installs modules based on:

  • The module lock file ps-rule.lock.json if set. Use module CLI commands to manage the lock file. AND

  • Modules defined in the Include.Module option, if set. Additionally the Requires option is used to constrain the version of modules installed.

Version and APIVersion accept stable#

Prior to v3.0.0, some usage of version and apiVersion accepted pre-release versions by default. For example:

---
# Synopsis: Any version example
apiVersion: github.com/microsoft/PSRule/v1
kind: Selector
metadata:
  name: PreviousAnyVersionExample
spec:
  if:
    field: dateVersion
    apiVersion: ''

When apiVersion is empty any version is accepted including pre-releases.

From v3.0.0 pre-release versions are not accepted by default. Set the includePrerelease property to true.

---
# Synopsis: Test comparison with apiVersion.
apiVersion: github.com/microsoft/PSRule/v1
kind: Selector
metadata:
  name: AnyVersion
spec:
  if:
    field: dateVersion
    apiVersion: ''
    includePrerelease: true

Upgrading to v2.0.0#

Resources naming restrictions#

When naming resources such as rules or selectors, the following restrictions apply:

  • Use between 3 and 128 characters — This is the minimum and maximum length of a resource name.
  • Only use allowed characters — To preserve consistency between file systems, some characters are not permitted. Dots, hyphens, and underscores are not permitted at the start and end of the name. Additionally some characters are restricted for future use. The following characters are not permitted:
    • < (less than)
    • > (greater than)
    • : (colon)
    • / (forward slash)
    • \ (backslash)
    • | (vertical bar or pipe)
    • ? (question mark)
    • * (asterisk)
    • " (double quote)
    • ' (single quote)
    • ` (backtick)
    • + (plus)
    • @ (at sign)
    • Integer value zero, sometimes referred to as the ASCII NUL character.
    • Characters whose integer representations are in the range from 1 through 31.

Prior to v2.0.0, there was no specific naming restriction for resources. However functionally PSRule and downstream components could not support all resource names. To avoid confusion, we have decided to restrict resource names to a specific set of characters.

From v2.0.0, resource names that do not meet the naming restrictions will generate an error.

Regular expression for valid resource names
^[^<>:/\\|?*"'`+@._\-\x00-\x1F][^<>:/\\|?*"'`+@\x00-\x1F]{1,126}[^<>:/\\|?*"'`+@._\-\x00-\x1F]$

Setting default module baseline#

When packaging rules in a module, you can set the default baseline. The default baseline from the module will be automatically used unless overridden.

Prior to v1.9.0 the default baseline was set by configuring the module manifest .psd1 file. From v1.9.0 the default baseline can be configured by within a module configuration. Using module configuration is the recommended method. Setting the default baseline from module manifest and has been removed from v2.0.0.

A module configuration can be defined in YAML.

Example

---
# Synopsis: Example module configuration for Enterprise.Rules module.
apiVersion: github.com/microsoft/PSRule/v1
kind: ModuleConfig
metadata:
  name: Enterprise.Rules
spec:
  rule:
    baseline: Enterprise.Default

Setting resource API version#

When creating YAML and JSON resources you define a resource by specifying the apiVersion and kind. An apiVersion was added as a requirement from v1.2.0. For compatibility, resources without an apiVersion were supported however deprecated for removal. This has now been removed from v2.0.0.

When defining resource specify an apiVersion. Currently this must be set to github.com/microsoft/PSRule/v1.

---
# Synopsis: An example rule to require TLS.
apiVersion: github.com/microsoft/PSRule/v1
kind: Rule
metadata:
  name: 'Local.YAML.RequireTLS'
spec:
  condition:
    field: 'configure.supportsHttpsTrafficOnly'
    equals: true

[
    {
        // Synopsis: An example rule to require TLS.
        "apiVersion": "github.com/microsoft/PSRule/v1",
        "kind": "Rule",
        "metadata": {
            "name": "Local.JSON.RequireTLS"
        },
        "spec": {
            "condition": {
                "field": "configure.supportsHttpsTrafficOnly",
                "equals": true
            }
        }
    }
]

Change in source file discovery for Get-PSRuleHelp#

Previously in PSRule v1.11.0 and prior versions, rules would show up twice when running Get-PSRuleHelp in the context of a module and in the same working directory of the module. This behavior has now been removed from v2.0.0.

Module files are now preferred over loose files, and rules are only shown once in the output. Any duplicate rule names from loose files are outputted as a warning instead.

The old behavior:

Name                                ModuleName               Synopsis
----                                ----------               --------
M1.Rule1                                                     This is the default
M1.Rule2                                                     This is the default
M1.Rule1                            TestModule               Synopsis en-AU.
M1.Rule2                            TestModule               This is the default

The new behavior:

WARNING: A rule with the same name 'M1.Rule1' already exists.
WARNING: A rule with the same name 'M1.Rule2' already exists.

Name                                ModuleName               Synopsis
----                                ----------               --------
M1.Rule1                            TestModule               Synopsis en-AU.
M1.Rule2                            TestModule               This is the default

Require source discovery from current working directory to be explicitly included#

Previously in PSRule v1.11.0 and prior versions, rule sources from the current working directory without the -Path and -Module parameters were automatically included. This behavior has now been removed from v2.0.0.

Rules sources in the current working directory are only included if -Path . or -Path $PWD is specified.

The old behavior:

PowerShell
Set-Location docs\scenarios\azure-resources
Get-PSRule

RuleName                            ModuleName                 Synopsis
--------                            ----------                 --------
appServicePlan.MinInstanceCount                                App Service Plan has multiple instances
appServicePlan.MinPlan                                         Use at least a Standard App Service Plan
appServiceApp.ARRAffinity                                      Disable client affinity for stateless services
appServiceApp.UseHTTPS                                         Use HTTPS only
storageAccounts.UseHttps                                       Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB
storageAccounts.UseEncryption                                  Use at-rest storage encryption

The new behavior:

PowerShell
Set-Location docs\scenarios\azure-resources
Get-PSRule

# No output, need to specify -Path explicitly

Get-PSRule -Path $PWD

RuleName                            ModuleName                 Synopsis
--------                            ----------                 --------
appServicePlan.MinInstanceCount                                App Service Plan has multiple instances
appServicePlan.MinPlan                                         Use at least a Standard App Service Plan
appServiceApp.ARRAffinity                                      Disable client affinity for stateless services
appServiceApp.UseHTTPS                                         Use HTTPS only
storageAccounts.UseHttps                                       Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB
storageAccounts.UseEncryption

Upgrading to v1.4.0#

Follow these notes to upgrade to PSRule v1.4.0 from previous versions.

Change in default output styles#

Previously in PSRule v1.3.0 and prior the default style when using Assert-PSRule was Client. From v1.4.0 PSRule now defaults to Detect.

The Detect output style falls back to Client however may detect one of the following styles instead:

  • AzurePipelines - Output is written for integration Azure Pipelines.
  • GitHubActions - Output is written for integration GitHub Actions.
  • VisualStudioCode - Output is written for integration with Visual Studio Code.

Detect uses the following logic:

  1. If the TF_BUILD environment variable is set to true, AzurePipelines will be used.
  2. If the GITHUB_ACTIONS environment variable is set to true, GitHubActions will be used.
  3. If the TERM_PROGRAM environment variable is set to vscode, VisualStudioCode will be used.
  4. Use Client.

To force usage of the Client output style set the Output.Style option. For example:

ps-rule.yaml
# YAML: Using the output/style property
output:
  style: Client

# Bash: Using environment variable
export PSRULE_OUTPUT_STYLE=Client
GitHub Actions
# GitHub Actions: Using environment variable
env:
  PSRULE_OUTPUT_STYLE: Client
Azure Pipelines
# Azure Pipelines: Using environment variable
variables:
- name: PSRULE_OUTPUT_STYLE
  value: Client

Upgrading to v1.0.0#

Follow these notes to upgrade to PSRule v1.0.0 from previous versions.

Replaced $Rule target properties#

Previously in PSRule v0.22.0 and prior the $Rule automatic variable had the following properties:

  • TargetName
  • TargetType
  • TargetObject

For example:

PowerShell rules
Rule 'Rule1' {
    $Rule.TargetName -eq 'Name1';
    $Rule.TargetType -eq '.json';
    $Rule.TargetObject.someProperty -eq 1;
}

In v1.0.0 these properties have been removed after being deprecated in v0.12.0. These properties are instead available on the $PSRule variable. Rules referencing the deprecated properties of $Rule must be updated.

For example:

PowerShell rules
Rule 'Rule1' {
    $PSRule.TargetName -eq 'Name1';
    $PSRule.TargetType -eq '.json';
    $PSRule.TargetObject.someProperty -eq 1;
}