en-GB/about_PSRule_Expressions.help.txt
|
TOPIC
about_psrule_expressions SHORT DESCRIPTION Describes PSRule expressions and how to use them. LONG DESCRIPTION PSRule expressions are used within YAML-based rules or selectors to evaluate an object. Expressions are comprised of nested conditions, operators, and comparison properties. The following conditions are available: - Contains - Count - Equals - EndsWith - Exists - Greater - GreaterOrEquals - HasDefault - HasSchema - HasValue - In - IsLower - IsString - IsUpper - Less - LessOrEquals - Match - NotEquals - NotIn - NotMatch - SetOf - StartsWith - Subset - Version The following operators are available: - AllOf - AnyOf - Not The following comparison properties are available: - Field - Name - Type ALLOF The `allOf` operator is used to require all nested expressions to match. When any nested expression does not match, `allOf` does not match. This is similar to a logical and operation. Syntax: allOf: <expression[]> For example: ```yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleAllOf' spec: condition: allOf: # Both Name and Description must exist. - field: 'Name' exists: true - field: 'Description' exists: true --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleAllOf' spec: if: allOf: # Both Name and Description must exist. - field: 'Name' exists: true - field: 'Description' exists: true ### AnyOf The `anyOf` operator is used to require one or more nested expressions to match. When any nested expression matches, `allOf` matches. This is similar to a logical _or_ operation. Syntax: yaml anyOf: <expression[]> For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleAnyOf' spec: condition: anyOf: # Name and/ or AlternativeName must exist. - field: 'Name' exists: true - field: 'AlternativeName' exists: true --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleAnyOf' spec: if: anyOf: # Name and/ or AlternativeName must exist. - field: 'Name' exists: true - field: 'AlternativeName' exists: true ### Contains The `contains` condition can be used to determine if the operand contains a specified sub-string. One or more strings to compare can be specified. Syntax: yaml contains: <string | array> - If the operand is a field, and the field does not exist, _contains_ always returns `false`. For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleContains' spec: condition: anyOf: - field: 'url' contains: '/azure/' - field: 'url' contains: - 'github.io' - 'github.com' --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleContains' spec: if: anyOf: - field: 'url' contains: '/azure/' - field: 'url' contains: - 'github.io' - 'github.com' ### Count The `count` condition is used to determine if the operand contains a specified number of items. Syntax: yaml count: <int> For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleCount' spec: condition: field: 'items' count: 2 --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleCount' spec: if: field: 'items' count: 2 ### Equals The `equals` condition can be used to compare if the operand is equal to a supplied value. Syntax: yaml equals: <string | int | bool> For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleEquals' spec: condition: field: 'Name' equals: 'TargetObject1' --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleEquals' spec: if: field: 'Name' equals: 'TargetObject1' ### EndsWith The `endsWith` condition can be used to determine if the operand ends with a specified string. One or more strings to compare can be specified. Syntax: yaml endsWith: <string | array> - If the operand is a field, and the field does not exist, _endsWith_ always returns `false`. For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleEndsWith' spec: condition: anyOf: - field: 'hostname' endsWith: '.com' - field: 'hostname' endsWith: - '.com.au' - '.com' --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleEndsWith' spec: if: anyOf: - field: 'hostname' endsWith: '.com' - field: 'hostname' endsWith: - '.com.au' - '.com' ### Exists The `exists` condition determines if the specified field exists. Syntax: yaml exists: <bool> - When `exists: true`, exists will return `true` if the field exists. - When `exists: false`, exists will return `true` if the field does not exist. For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleExists' spec: condition: field: 'Name' exists: true --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleExists' spec: if: field: 'Name' exists: true ### Field The comparison property `field` is used with a condition to determine field of the object to evaluate. A field can be: - A property name. - A key within a hashtable or dictionary. - An index in an array or collection. - A nested path through an object. Syntax: yaml field: <string> For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleField' spec: condition: field: 'Properties.securityRules[0].name' exists: true --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleField' spec: if: field: 'Properties.securityRules[0].name' exists: true ### Greater The `greater` condition determines if the operand is greater than a supplied value. The field value can either be an integer, float, array, or string. When the field value is: - An integer or float, a numerical comparison is used. - An array, the number of elements is compared. - A string, the length of the string is compared. - A DateTime, the number of days from the current time is compared. Syntax: yaml greater: <int> For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleGreater' spec: condition: field: 'Name' greater: 3 --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleGreater' spec: if: field: 'Name' greater: 3 ### GreaterOrEquals The `greaterOrEquals` condition determines if the operand is greater or equal to the supplied value. The field value can either be an integer, float, array, or string. When the field value is: - An integer or float, a numerical comparison is used. - An array, the number of elements is compared. - A string, the length of the string is compared. - A DateTime, the number of days from the current time is compared. Syntax: yaml greaterOrEquals: <int> For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleGreaterOrEquals' spec: condition: field: 'Name' greaterOrEquals: 3 --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleGreaterOrEquals' spec: if: field: 'Name' greaterOrEquals: 3 ### HasDefault The `hasDefault` condition determines if the field exists that it is set to the specified value. If the field does not exist, the condition will return `true`. The following properties are accepted: - `caseSensitive` - Optionally, a case-sensitive comparison can be performed for string values. By default, case-insensitive comparison is performed. Syntax: yaml hasDefault: <string | int | bool> caseSensitive: <bool> For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleHasDefault' spec: condition: field: 'enabled' hasDefault: true --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleHasDefault' spec: if: field: 'enabled' hasDefault: true ### HasSchema The `hasSchema` condition determines if the operand has a `$schema` property defined. If the `$schema` property is defined, it must match one of the specified schemas. If a trailing `#` is specified it is ignored. The following properties are accepted: - `caseSensitive` - Optionally, a case-sensitive comparison can be performed. By default, case-insensitive comparison is performed. - `ignoreScheme` - Optionally, the URI scheme is ignored in the comparison. By default, the scheme is compared. When `true`, the schema will match if either `http://` or `https://` is specified. Syntax: yaml hasSchema: <array> caseSensitive: <bool> ignoreScheme: <bool> - When `hasSchema: []`, hasSchema will return `true` if any non-empty `$schema` property is defined. For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleHasSchema' spec: condition: field: '.' hasSchema: - https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json# --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleHasSchema' spec: if: field: '.' hasSchema: - https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json# - https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json# ignoreScheme: true --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleHasAnySchema' spec: if: field: '.' hasSchema: [] ### HasValue The `hasValue` condition determines if the field exists and has a non-empty value. Syntax: yaml hasValue: <bool> - When `hasValue: true`, hasValue will return `true` if the field is not empty. - When `hasValue: false`, hasValue will return `true` if the field is empty. For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleHasValue' spec: condition: field: 'Name' hasValue: true --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleHasValue' spec: if: field: 'Name' hasValue: true ### In The `in` condition can be used to compare if a field contains one of the specified values. Syntax: yaml in: <array> For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleIn' spec: condition: field: 'Name' in: - 'Value1' - 'Value2' --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleIn' spec: if: field: 'Name' in: - 'Value1' - 'Value2' ### IsLower The `isLower` condition determines if the operand is a lowercase string. Syntax: yaml isLower: <bool> - When `isLower: true`, _isLower_ will return `true` if the operand is a lowercase string. Non-letter characters are ignored. - When `isLower: false`, _isLower_ will return `true` if the operand is not a lowercase string. - If the operand is a field, and the field does not exist _isLower_ always returns `false`. For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleIsLower' spec: condition: field: 'Name' isLower: true --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleIsLower' spec: if: field: 'Name' isLower: true ### IsString The `isString` condition determines if the operand is a string or other type. Syntax: yaml isString: <bool> - When `isString: true`, _isString_ will return `true` if the operand is a string. - When `isString: false`, _isString_ will return `true` if the operand is not a string or is null. - If the operand is a field, and the field does not exist _isString_ always returns `false`. For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleIsString' spec: condition: field: 'Name' isString: true --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleIsString' spec: if: field: 'Name' isString: true ### IsUpper The `isUpper` condition determines if the operand is an uppercase string. Syntax: yaml isUpper: <bool> - When `isUpper: true`, _isUpper_ will return `true` if the operand is an uppercase string. Non-letter characters are ignored. - When `isUpper: false`, _isUpper_ will return `true` if the operand is not an uppercase string. - If the operand is a field, and the field does not exist _isUpper_ always returns `false`. For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleIsUpper' spec: condition: field: 'Name' isUpper: true --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleIsUpper' spec: if: field: 'Name' isUpper: true ### Less The `less` condition determines if the operand is less than a supplied value. The field value can either be an integer, float, array, or string. When the field value is: - An integer or float, a numerical comparison is used. - An array, the number of elements is compared. - A string, the length of the string is compared. - A DateTime, the number of days from the current time is compared. Syntax: yaml less: <int> For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleLess' spec: condition: field: 'Name' less: 3 --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleLess' spec: if: field: 'Name' less: 3 ### LessOrEquals The `lessOrEquals` condition determines if the operand is less or equal to the supplied value. The field value can either be an integer, float, array, or string. When the field value is: - An integer or float, a numerical comparison is used. - An array, the number of elements is compared. - A string, the length of the string is compared. - A DateTime, the number of days from the current time is compared. Syntax: yaml lessOrEquals: <int> For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleLessOrEquals' spec: condition: field: 'Name' lessOrEquals: 3 --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleLessOrEquals' spec: if: field: 'Name' lessOrEquals: 3 ### Match The `match` condition can be used to compare if a field matches a supplied regular expression. Syntax: yaml match: <string> For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleMatch' spec: condition: field: 'Name' match: '$(abc|efg)$' --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleMatch' spec: if: field: 'Name' match: '$(abc|efg)$' ### Name The comparison property `name` is used with a condition to evaluate the target name of the object. The `name` property must be set to `.`. Any other value will cause the condition to evaluate to `false`. Syntax: yaml name: '.' For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleName' spec: condition: name: '.' equals: 'TargetObject1' --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleName' spec: if: name: '.' in: - 'TargetObject1' - 'TargetObject2' ### Not The `any` operator is used to invert the result of the nested expression. When a nested expression matches, `not` does not match. When a nested expression does not match, `not` matches. Syntax: yaml not: <expression> For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleNot' spec: condition: not: # The AlternativeName field must not exist. field: 'AlternativeName' exists: true --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleNot' spec: if: not: # The AlternativeName field must not exist. field: 'AlternativeName' exists: true ### NotEquals The `notEquals` condition can be used to compare if a field is equal to a supplied value. Syntax: yaml notEquals: <string | int | bool> For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleNotEquals' spec: condition: field: 'Name' notEquals: 'TargetObject1' --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleNotEquals' spec: if: field: 'Name' notEquals: 'TargetObject1' ### NotIn The `notIn` condition can be used to compare if a field does not contains one of the specified values. Syntax: yaml notIn: <array> For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleNotIn' spec: condition: field: 'Name' notIn: - 'Value1' - 'Value2' --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleNotIn' spec: if: field: 'Name' notIn: - 'Value1' - 'Value2' ### NotMatch The `notMatch` condition can be used to compare if a field does not matches a supplied regular expression. Syntax: yaml notMatch: <string> For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleNotMatch' spec: condition: field: 'Name' notMatch: '$(abc|efg)$' --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleNotMatch' spec: if: field: 'Name' notMatch: '$(abc|efg)$' ### SetOf The `setOf` condition can be used to determine if the operand is a set of specified values. Additionally the following properties are accepted: - `caseSensitive` - Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed. Syntax: yaml setOf: <array> caseSensitive: <bool> For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleSetOf' spec: condition: field: 'zones' setOf: - 1 - 2 - 3 caseSensitive: false --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleSetOf' spec: if: field: 'zones' setOf: - 1 - 2 - 3 caseSensitive: false ### StartsWith The `startsWith` condition can be used to determine if the operand starts with a specified string. One or more strings to compare can be specified. Syntax: yaml startsWith: <string | array> - If the operand is a field, and the field does not exist, _startsWith_ always returns `false`. For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleStartsWith' spec: condition: anyOf: - field: 'url' startsWith: 'http' - field: 'url' startsWith: - 'http://' - 'https://' --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleStartsWith' spec: if: anyOf: - field: 'url' startsWith: 'http' - field: 'url' startsWith: - 'http://' - 'https://' ### Subset The `subset` condition can be used to determine if the operand is a set of specified values. The following properties are accepted: - `caseSensitive` - Optionally, a case-sensitive comparison can be performed. By default, case-insensitive comparison is performed. - `unique` - Optionally, the operand must not contain duplicates. By default, duplicates are allowed. Syntax: yaml subset: <array> caseSensitive: <bool> unique: <bool> For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleSubset' spec: condition: field: 'logs' subset: - 'cluster-autoscaler' - 'kube-apiserver' - 'kube-scheduler' caseSensitive: true unique: true --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleSubset' spec: if: field: 'logs' subset: - 'cluster-autoscaler' - 'kube-apiserver' - 'kube-scheduler' caseSensitive: true unique: true ### Type The comparison property `type` is used with a condition to evaluate the target type of the object. The `type` property must be set to `.`. Any other value will cause the condition to evaluate to `false`. Syntax: yaml type: '.' For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleType' spec: condition: type: '.' equals: 'CustomType' --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleType' spec: if: type: '.' in: - 'Microsoft.Storage/storageAccounts' - 'Microsoft.Storage/storageAccounts/blobServices' ### Version The `version` condition determines if the operand is a valid semantic version. A constraint can optionally be provided to require the semantic version to be within a range. Supported version constraints for expression are the same as the `$Assert.Version` assertion helper. Syntax: yaml version: <string> includePrerelease: <bool> For example: yaml apiVersion: github.com/microsoft/PSRule/v1 kind: Rule metadata: name: 'ExampleVersion' spec: condition: field: 'engine.version' version: '^1.2.3' --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleAnyVersion' spec: if: field: 'engine.version' version: '' --- apiVersion: github.com/microsoft/PSRule/v1 kind: Selector metadata: name: 'ExampleVersionIncludingPrerelease' spec: if: field: 'engine.version' version: '>=1.5.0' includePrerelease: true ``` NOTE An online version of this document is available at https://microsoft.github.io/PSRule/v1/concepts/PSRule/en-US/about_PSRule_Expressions/. SEE ALSO - Invoke-PSRule KEYWORDS - Rules - Expressions - PSRule |