en-GB/about_PSRule_Rules.help.txt

TOPIC
    about_psrule_rules
 
SHORT DESCRIPTION
    Describes PSRule rules including how to use and author them.
 
LONG DESCRIPTION
    PSRule executes rules to validate an object from input either from a file or
    PowerShell pipeline. The PowerShell pipeline only available when running
    PSRule directly. PSRule can also be run from a continuous integration (CI)
    pipeline or Visual Studio Code. When using these methods, the PowerShell
    pipeline is not available.
    To evaluate an object PSRule can use rules defined in script or YAML.
    When using script rules:
    - Each rule is defined PowerShell within a `.Rule.ps1` file by using a
    `Rule` block.
    - PowerShell variables, functions, and cmdlets can be used just like regular
    PowerShell scripts.
    - Built-in assertion helpers can be used to quickly build out rules.
    - Pre-conditions can be defined with using a script block, type binding, or
    YAML-based selector.
    To learn more about assertion helpers see
    about_PSRule_Assert
    .
    When using YAML rules:
    - Each rule is defined in a `.Rule.yaml` file by using the `Rule` resource.
    - YAML-based expressions can be used.
    - Pre-conditions can be defined with using a type binding, or YAML-based selector.
    To learn more about YAML-based expressions see
    about_PSRule_Expressions
    .
 
    USING PRE-CONDITIONS
    Pre-conditions are used to determine if a rule should be executed. While
    pre-conditions are not required for each rule, it is a good practice to
    define them. If a rule does not specify a pre-condition it may be executed
    against an object it does not expect.
    Pre-conditions come in three forms:
    - Script - A PowerShell script block that is executed and if true will cause
    the rule to be executed. Script block pre-conditions only work with script
    rules. To use a script block pre-condition, specify the `-If` script
    parameter on the `Rule` block. - Type - A type string that is compared
    against the bound object type. When the type matches the rule will be
    executed. To use a type pre-conditions, specify the `-Type` script
    parameter or `type` YAML/JSON property. - Selector - A YAML/JSON based
    expression that is evaluated against the object. When the expression
    matches the rule will be executed. To use a selector pre-conditions,
    specify the `-With` script parameter or `with` YAML/JSON property.
    Different forms of pre-conditions can be combined. When combining
    pre-conditions, different forms must be all true (logical AND). i.e. Script
    AND Type AND Selector must be all be true for the rule to be executed.
    Multiple Type and Selector pre-conditions can be specified. If multiple Type
    and Selector pre-conditions are specified, only one must be true (logical OR).
    For example:
 
    # Synopsis: An example script rule with pre-conditions.
    Rule 'ScriptRule' -If { $True } -Type 'CustomType1', 'CustomType2' -With 'Selector.1', 'Selector.2' {
        # Rule condition
    }
 
```yaml
SYNOPSIS: AN EXAMPLE YAML RULE WITH PRE-CONDITIONS.
    apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name:
    'YamlRule' spec: type: - 'CustomType1' - 'CustomType2' with: -
    'Selector.1' - 'Selector.2' condition: { }
 
     
 
    jsonc [ { // Synopsis: An example YAML rule with pre-conditions.
    "apiVersion": "github.com/microsoft/PSRule/v1", "kind": "Rule",
    "metadata": { "name": "YamlRule" }, "spec": { "type": [
           "CustomType1", "CustomType2" ], "with": [
    "Selector.1", "Selector.2" ], "condition": {} } }
    ]
 
    Pre-conditions are evaluated in the following order: Selector, Type, then Script.
     
    ### Defining script rules
     
    To define a script rule use the `Rule` keyword followed by a name and a pair of squiggly brackets `{`.
    Within the `{ }` one or more conditions can be used.
    Script rule must be defined within `.Rule.ps1` files.
    Multiple rules can be defined in a single file by creating multiple `Rule` blocks.
    Rule blocks can not be nested within each other.
     
    Within the `Rule` block, define one or more conditions to determine pass or fail of the rule.
     
    Syntax:
 
    text Rule [-Name] <string> [-Tag <hashtable>] [-When <string[]>] [-Type
    <string[]>] [-If <scriptBlock>] [-DependsOn <string[]>] [-Configure
    <hashtable>] [-ErrorAction <ActionPreference>] [-Body] { ... }
 
    Example:
 
    powershell
 
SYNOPSIS: USE A STANDARD LOAD-BALANCER WITH AKS CLUSTERS.
    Rule 'Azure.AKS.StandardLB' -Type
    'Microsoft.ContainerService/managedClusters' -Tag @{ release = 'GA'; ruleSet
    = '2020_06' } { $Assert.HasFieldValue($TargetObject,
    'Properties.networkProfile.loadBalancerSku', 'standard'); }
 
    ### Defining YAML rules
     
    To define a YAML rule use the `Rule` resource in a YAML file.
    Each rule must be defined within a `.Rule.yaml` file following a standard schema.
    Multiple rules can be defined in a single YAML file by separating each rule with a `---`.
     
    Within the `Rule` resource, the `condition` property specifies conditions to pass or fail the rule.
     
    Syntax:
 
yaml
SYNOPSIS: {{ SYNOPSIS }}
    apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: '{{
    Name }}' tags: { } spec: type: [ ] with: [ ] condition: { }
 
    Example:
 
yaml
SYNOPSIS: USE A STANDARD LOAD-BALANCER WITH AKS CLUSTERS.
    apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name:
    'Azure.AKS.StandardLB' tags: release: 'GA' ruleSet: '2020_06'
    spec: type: - Microsoft.ContainerService/managedClusters condition:
     field: 'Properties.networkProfile.loadBalancerSku' equals: 'standard'
 
    ### Defining JSON rules
     
    To define a JSON rule use the `Rule` resource in a JSON file.
    Each rule must be defined within a `.Rule.jsonc` file following a standard schema.
    One or more rules can be defined in a single JSON array separating each rule in a JSON object.
     
    Within the `Rule` resource, the `condition` property specifies conditions to pass or fail the rule.
     
    Rules can also be defined within `.json` files.
    We recommend using `.jsonc` to view [JSON with Comments](https://code.visualstudio.com/docs/languages/json#_json-with-comments) in Visual Studio Code.
     
    Syntax:
 
    jsonc [ { // Synopsis: {{ Synopsis }} "apiVersion":
    "github.com/microsoft/PSRule/v1", "kind": "Rule", "metadata": {
     "name": "{{ Name }}", "tags": {} }, "spec": { "type":
    [], "with": [], "condition": {} } } ]
 
    Example:
 
    jsonc [ { // Synopsis: Use a Standard load-balancer with AKS clusters.
        "apiVersion": "github.com/microsoft/PSRule/v1", "kind": "Rule",
    "metadata": { "name": "Azure.AKS.StandardLB", "tags": {
    "release": "GA", "ruleSet": "2020_06" } }, "spec": {
        "type": [ "Microsoft.ContainerService/managedClusters" ],
         "condition": { "field":
    "Properties.networkProfile.loadBalancerSku", "equals": "standard"
       } } } ] ```
 
NOTE
    An online version of this document is available at
    https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Rules/.
 
SEE ALSO
    -
    Invoke-PSRule
 
KEYWORDS
    - Rules
- Expressions
- PSRule