Skip to content

Selectors#

Describes PSRule Selectors including how to use and author them.

Description#

PSRule executes rules to validate an object from input. When evaluating an object from input, PSRule can use selectors to perform complex matches of an object.

  • A selector is a YAML/JSON based expression that evaluates an object.
  • Each selector is comprised of nested conditions, operators, and comparison properties.
  • Selectors must use one or more available conditions with a comparison property to evaluate the object.
  • Optionally a condition can be nested in an operator.
  • Operators can be nested within other operators.

The following conditions are available:

The following operators are available:

The following comparison properties are available:

To learn more about conditions, operators, and properties see about_PSRule_Expressions.

Currently the following limitations apply:

  • Selectors can evaluate:
    • Fields of the target object.
    • Type and name binding of the target object by using name and type comparison properties.
  • State variables such has $PSRule can not be evaluated.
  • Bound fields can not be evaluated.

Using selectors as pre-conditions#

Selectors can be referenced by name as a rule pre-condition by using the -With parameter. For example:

Rule 'RuleWithSelector' -With 'BasicSelector' {
    # Rule condition
}

Selector pre-conditions can be used together with type and script block pre-conditions. If one or more selector pre-conditions are used, they are evaluated before type or script block pre-conditions.

Defining selectors#

Selectors can be defined with either YAML or JSON format, and can be included with a module or standalone .Rule.yaml or .Rule.jsonc file. In either case, define a selector within a file ending with the .Rule.yaml or .Rule.jsonc extension. A selector can be defined side-by-side with other resources such as baselines or module configurations.

Selectors can also be defined within .json files. We recommend using .jsonc to view JSON with Comments in Visual Studio Code.

Use the following template to define a selector:

---
# Synopsis: {{ Synopsis }}
apiVersion: github.com/microsoft/PSRule/v1
kind: Selector
metadata:
  name: '{{ Name }}'
spec:
  if: { }

[
  {
    // Synopsis: {{ Synopsis }}
    "apiVersion": "github.com/microsoft/PSRule/v1",
    "kind": "Selector",
    "metadata": {
      "name": "{{ Name }}"
    },
    "spec": {
      "if": {}
    }
  }
]

Within the if object, one or more conditions or logical operators can be used.

Examples#

Example Selectors.Rule.yaml#

# Example Selectors.Rule.yaml
---
# Synopsis: Require the CustomValue field.
apiVersion: github.com/microsoft/PSRule/v1
kind: Selector
metadata:
  name: RequireCustomValue
spec:
  if:
    field: 'CustomValue'
    exists: true

---
# Synopsis: Require a Name or AlternativeName.
apiVersion: github.com/microsoft/PSRule/v1
kind: Selector
metadata:
  name: RequireName
spec:
  if:
    anyOf:
    - field: 'AlternateName'
      exists: true
    - field: 'Name'
      exists: true

---
# Synopsis: Require a specific CustomValue
apiVersion: github.com/microsoft/PSRule/v1
kind: Selector
metadata:
  name: RequireSpecificCustomValue
spec:
  if:
    field: 'CustomValue'
    in:
    - 'Value1'
    - 'Value2'

Example Selectors.Rule.jsonc#

// Example Selectors.Rule.jsonc
[
  {
    // Synopsis: Require the CustomValue field.
    "apiVersion": "github.com/microsoft/PSRule/v1",
    "kind": "Selector",
    "metadata": {
      "name": "RequireCustomValue"
    },
    "spec": {
      "if": {
        "field": "CustomValue",
        "exists": true
      }
    }
  },
  {
    // Synopsis: Require a Name or AlternativeName.
    "apiVersion": "github.com/microsoft/PSRule/v1",
    "kind": "Selector",
    "metadata": {
      "name": "RequireName"
    },
    "spec": {
      "if": {
        "anyOf": [
          {
            "field": "AlternateName",
            "exists": true
          },
          {
            "field": "Name",
            "exists": true
          }
        ]
      }
    }
  },
  {
    // Synopsis: Require a specific CustomValue
    "apiVersion": "github.com/microsoft/PSRule/v1",
    "kind": "Selector",
    "metadata": {
      "name": "RequireSpecificCustomValue"
    },
    "spec": {
      "if": {
        "field": "CustomValue",
        "in": [
          "Value1",
          "Value2"
        ]
      }
    }
  }
]

Comments