5.2 KiB
Rules
Rules apply a schema fragment to a set of nodes selected from the original data.
This is a descriptive standard for rules. The enforced meta-rules for rules are located here.
From File
Rules may be loaded from YAML or JSON files, using any extension.
YAML Schema
The default YAML schema has been extended with some custom types.
Env Type
An environment variable by name.
This can be used in CI environments to compare resources against the current job's branch, commit, or tag.
foo: !env CI_COMMIT_SHA
Include Type
Include another file as a child of this key. The file must be a single document.
Relative paths are resolved from __dirname, but no path sanitization is done to prevent ../. Include paths should
not be taken from user input.
Regexp Type
A regular expression in a string.
Uses standard JS syntax. Flags are supported.
foo: !regexp /a.*b/gu
Stream Type
A process stream by name (key in process).
One of stderr, stdin, or stdout.
logger:
streams:
- level: error
stream: !stream stderr
File Name
A unique name, used for logging and as the schema $id for definitions.
This should be truly unique, but must be unique within the set of --rules loaded.
name: foo-rules
Schema Definitions
A dict of schema definitions in objects with string keys.
These are added to the Ajv schema and may be referenced by the file name and key:
name: foo
definitions:
bar:
type: object
rules:
- name: foobar
check:
type: object
properties:
bin:
$ref: "foo#/definitions/bar"
Rule Definitions
A list of rules.
name: foo
rules:
- name: foobar
check:
type: object
Rule Name
The rule name, used for logging and inclusion.
Must be unique within the file or module.
rules:
- name: foo
Rule Description
The rule description, used for error messages.
Some descriptive string.
rules:
- name: foo
desc: foos must not overfoo
Rule Level
The rule's log level, used for inclusion.
TODO: use for log messages
One of debug, info, warn, or error in a string.
rules:
- name: foo
level: debug
Rule Tags
A list of tags for the rule, used for inclusion.
rules:
- name: foo
tags:
- important
- foo-related
- definitely-not-bar
Rule Selector
JSON path used to select nodes from the data.
This selects a list of potential nodes to be filtered and checked. The default ($) selects the root of each
document. Selecting a subset of children allows the check schema to cover a small fragment of the document.
Uses jsonpath-plus syntax in a string.
rules:
- name: foo
select: '$.spec.template.spec.containers[*]'
Rule Filter
Schema used to filter selected nodes.
If a node was selected but but does not match this schema, it will be skipped and the rule will move on to the next
node.
Uses ajv syntax in an object.
rules:
- name: foo
filter:
# only check objects with the property bar
type: object
required: [bar]
Rule Check
Schema used to check selected nodes.
This is the body of the rule. If a node does not match this schema, the rule will fail.
Uses ajv syntax in an object.
rules:
- name: foo
check:
type: string
From Module
Rules may be loaded from an external module. Any module that can be required can be used by name,
using normal Node require rules.
To load a module: --rule-module salty-dog-oot-example
The default export from a rule module must match the schema for rule files:
const { RuleOne, RuleTwo } = require('./rules');
module.exports = {
name: 'module-name',
definitions: {
snippet: {},
},
rules: [
new RuleOne(),
new RuleTwo(),
],
};
An example rule module is available here.
From Path
Rules may be loaded from a directory. Files with .json and .yaml/.yml extensions will be loaded,
with file names converted to lowercase before being checked.
To load a directory: --rule-path rules/
Each file will be loaded as an individual rule file. Schema definitions and rules will be loaded normally.