en-US/about_PSRule_Baseline.help.txt

TOPIC
    about_psrule_baseline
 
SHORT DESCRIPTION
    Describes usage of baselines within PSRule.
 
LONG 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:
    -
    Binding.Field
    -
    Binding.IgnoreCase
    -
    Binding.NameSeparator
    -
    Binding.PreferTargetInfo
    -
    Binding.TargetName
    -
    Binding.TargetType
    -
    Binding.UseQualifiedName
    -
    Configuration
    -
    Rule.Include
    -
    Rule.IncludeLocal
    -
    Rule.Exclude
    -
    Rule.Tag
    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` or `ps-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:
 
```yaml
SYNOPSIS: <SYNOPSIS>
    apiVersion: github.com/microsoft/PSRule/v1 kind: Baseline metadata: name:
    <name> annotations: { } spec: # One or more baseline options binding:
    { } rule: { } configuration: { }
 
    For example:
 
yaml
SYNOPSIS: THIS IS AN EXAMPLE BASELINE
    apiVersion: github.com/microsoft/PSRule/v1 kind: Baseline metadata: name:
    Baseline1 spec: binding: field: id: - ResourceId
    targetName: - Name - ResourceName - ResourceGroupName
    targetType: - ResourceType 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: binding: targetName: - Name - ResourceName
    - ResourceGroupName targetType: - ResourceType rule: include:
       - Rule1 - Rule3 configuration: allowedLocations: -
    'Australia East'
 
    To define a JSON baseline spec use the following structure:
 
    json [ { // Synopsis: <synopsis> "apiVersion":
    "github.com/microsoft/PSRule/v1", "kind": "Baseline", "metadata": {
         "name": "<name>", "annotations": {} }, "spec": {
    "binding": {}, "rule": {}, "configuration": {} } } ]
 
    For example:
 
    json [ { // Synopsis: This is an example baseline "apiVersion":
    "github.com/microsoft/PSRule/v1", "kind": "Baseline", "metadata": {
         "name": "Baseline1" }, "spec": { "binding": {
    "field": { "id": [ "ResourceId" ] },
            "targetName": [ "Name", "ResourceName",
     "ResourceGroupName" ], "targetType": [
    "ResourceType" ] }, "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": { "binding": { "targetName": [ "Name",
        "ResourceName", "ResourceGroupName" ],
    "targetType": [ "ResourceType" ] }, "rule": {
           "include": [ "Rule1", "Rule3" ] },
         "configuration": { "allowedLocations": [ "Australia
    East" ] } } } ]
 
    ### Baseline scopes
     
    When baseline options are set, PSRule uses the following order to determine precedence.
     
    1. Parameter - `-Name` and `-Tag`.
    2. Explicit - A named baseline specified with `-Baseline`.
    3. Workspace - Included in `ps-rule.yaml` or specified on the command line with `-Option`.
    4. 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 to `true`.
    PSRule will generate a warning when an obsolete baseline is used.
     
    YAML example:
 
yaml
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:
 
    json [ { // 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
 
    yaml
 
EXAMPLE BASELINE.RULE.YAML
    ---
 
SYNOPSIS: THIS IS AN EXAMPLE BASELINE
    apiVersion: github.com/microsoft/PSRule/v1 kind: Baseline metadata: name:
    TestBaseline1 spec: binding: targetName: - AlternateName
    targetType: - kind rule: include: - 'WithBaseline'
    configuration: key1: value1
    ---
 
SYNOPSIS: THIS IS AN EXAMPLE BASELINE
    apiVersion: github.com/microsoft/PSRule/v1 kind: Baseline metadata: name:
    TestBaseline2 spec: binding: targetName: - AlternateName
    targetType: - kind rule: include: - 'WithBaseline'
    configuration: key1: value1
 
    ### Example Baseline.Rule.json
 
    json // Example Baseline.Rule.json
    [ { // Synopsis: This is an example baseline "apiVersion":
    "github.com/microsoft/PSRule/v1", "kind": "Baseline", "metadata": {
         "name": "TestBaseline1" }, "spec": { "binding": {
    "targetName": [ "AlternateName" ], "targetType": [
              "kind" ] }, "rule": { "include": [
          "WithBaseline" ] }, "configuration": {
    "key1": "value1" } } }, { // Synopsis: This is an example
    baseline "apiVersion": "github.com/microsoft/PSRule/v1", "kind":
    "Baseline", "metadata": { "name": "TestBaseline2" },
    "spec": { "binding": { "targetName": [
    "AlternateName" ], "targetType": [ "kind"
    ] }, "rule": { "include": [ "WithBaseline"
        ] }, "configuration": { "key1": "value1" }
    } } ] ```
 
KEYWORDS
    - Options
- PSRule
- Baseline
- Binding