Upgrade notes#
This document contains notes to help upgrade from previous versions of PSRule.
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.
^[^<>:/\\|?*"'`+@._\-\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:
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:
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:
- If the
TF_BUILDenvironment variable is set totrue,AzurePipelineswill be used. - If the
GITHUB_ACTIONSenvironment variable is set totrue,GitHubActionswill be used. - If the
TERM_PROGRAMenvironment variable is set tovscode,VisualStudioCodewill be used. - Use
Client.
To force usage of the Client output style set the Output.Style option.
For example:
# YAML: Using the output/style property
output:
style: Client
# Bash: Using environment variable
export PSRULE_OUTPUT_STYLE=Client
# GitHub Actions: Using environment variable
env:
PSRULE_OUTPUT_STYLE: Client
# 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:
TargetNameTargetTypeTargetObject
For example:
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:
Rule 'Rule1' {
$PSRule.TargetName -eq 'Name1';
$PSRule.TargetType -eq '.json';
$PSRule.TargetObject.someProperty -eq 1;
}