Baselines#
Describes usage of baselines within PSRule.
Description#
PSRule lets you define a baseline. A baseline includes a set of rule and configuration options that are used for evaluating objects.
The following baseline options can be configured:
Baseline options can be:
- Included as a baseline spec within a YAML or JSON file.
- When using this method, multiple baseline specs can be defined within the same YAML/JSON file.
- Each YAML baseline spec is separated using
---
. - Each JSON baseline spec is separated by JSON objects in a JSON array.
- Set within a workspace options file like
ps-rule.yaml
orps-rule.json
.- Only a single baseline can be specified.
- See about_PSRule_Options for details on using this method.
Baseline specs#
YAML baseline specs are saved within a YAML file with a .Rule.yaml
or .Rule.yml
extension, for example Baseline.Rule.yaml
.
JSON baseline specs are saved within a file with a .Rule.json
or .Rule.jsonc
extension, for example Baseline.Rule.json
.
Use .jsonc
to view JSON with Comments in Visual Studio Code.
To define a YAML baseline spec use the following structure:
---
# Synopsis: <synopsis>
apiVersion: github.com/microsoft/PSRule/v1
kind: Baseline
metadata:
name: <name>
annotations: { }
spec:
# One or more baseline options
rule: { }
configuration: { }
For example:
---
# Synopsis: This is an example baseline
apiVersion: github.com/microsoft/PSRule/v1
kind: Baseline
metadata:
name: Baseline1
spec:
rule:
include:
- Rule1
- Rule2
configuration:
allowedLocations:
- 'Australia East'
- 'Australia South East'
---
# Synopsis: This is an example baseline
apiVersion: github.com/microsoft/PSRule/v1
kind: Baseline
metadata:
name: Baseline2
spec:
rule:
include:
- Rule1
- Rule3
configuration:
allowedLocations:
- 'Australia East'
To define a JSON baseline spec use the following structure:
[
{
// Synopsis: <synopsis>
"apiVersion": "github.com/microsoft/PSRule/v1",
"kind": "Baseline",
"metadata": {
"name": "<name>",
"annotations": {}
},
"spec": {
"rule": {},
"configuration": {}
}
}
]
For example:
[
{
// Synopsis: This is an example baseline
"apiVersion": "github.com/microsoft/PSRule/v1",
"kind": "Baseline",
"metadata": {
"name": "Baseline1"
},
"spec": {
"rule": {
"include": [
"Rule1",
"Rule2"
]
},
"configuration": {
"allowedLocations": [
"Australia East",
"Australia South East"
]
}
}
},
{
// Synopsis: This is an example baseline
"apiVersion": "github.com/microsoft/PSRule/v1",
"kind": "Baseline",
"metadata": {
"name": "Baseline2"
},
"spec": {
"rule": {
"include": [
"Rule1",
"Rule3"
]
},
"configuration": {
"allowedLocations": [
"Australia East"
]
}
}
}
]
Baseline scopes#
When baseline options are set, PSRule uses the following order to determine precedence.
- Parameter -
-Name
and-Tag
. - Explicit - A named baseline specified with
-Baseline
. - Workspace - Included in
ps-rule.yaml
or specified on the command line with-Option
. - Module - A baseline object included in a
.Rule.yaml
or.Rule.json
file.
After precedence is determined, baselines are merged and null values are ignored, such that:
Annotations#
Additional baseline annotations can be provided as key/ value pairs.
Annotations can be used to provide additional information that is available in Get-PSRuleBaseline
output.
The following reserved annotation exists:
obsolete
- Marks the baseline as obsolete when set totrue
. PSRule will generate a warning when an obsolete baseline is used.
YAML example:
---
# Synopsis: This is an example baseline that is obsolete
apiVersion: github.com/microsoft/PSRule/v1
kind: Baseline
metadata:
name: ObsoleteBaseline
annotations:
obsolete: true
spec: { }
JSON example:
[
{
// Synopsis: This is an example baseline that is obsolete
"apiVersion": "github.com/microsoft/PSRule/v1",
"kind": "Baseline",
"metadata": {
"name": "ObsoleteBaseline",
"annotations": {
"obsolete": true
}
},
"spec": {}
}
]
Examples#
Example Baseline.Rule.yaml#
# Example Baseline.Rule.yaml
---
# Synopsis: This is an example baseline
apiVersion: github.com/microsoft/PSRule/v1
kind: Baseline
metadata:
name: TestBaseline1
spec:
rule:
include:
- 'WithBaseline'
configuration:
key1: value1
---
# Synopsis: This is an example baseline
apiVersion: github.com/microsoft/PSRule/v1
kind: Baseline
metadata:
name: TestBaseline2
spec:
rule:
include:
- 'WithBaseline'
configuration:
key1: value1
Example Baseline.Rule.json#
// Example Baseline.Rule.json
[
{
// Synopsis: This is an example baseline
"apiVersion": "github.com/microsoft/PSRule/v1",
"kind": "Baseline",
"metadata": {
"name": "TestBaseline1"
},
"spec": {
"rule": {
"include": [
"WithBaseline"
]
},
"configuration": {
"key1": "value1"
}
}
},
{
// Synopsis: This is an example baseline
"apiVersion": "github.com/microsoft/PSRule/v1",
"kind": "Baseline",
"metadata": {
"name": "TestBaseline2"
},
"spec": {
"rule": {
"include": [
"WithBaseline"
]
},
"configuration": {
"key1": "value1"
}
}
}
]