1
0
Fork 0
Schema analysis, linting, and transformation for YAML
Go to file
ssube 0129221f7a fix(build): validate rules during build 2019-06-24 23:47:29 -05:00
config feat: list mode, fix version option 2019-06-24 23:47:12 -05:00
docs feat: add rules to image, doc 2019-06-17 09:11:26 -05:00
examples feat: support multiple documents per source (#11) 2019-06-24 22:50:46 -05:00
rules docs: clean up readme 2019-06-24 22:32:39 -05:00
scripts fix(build): add github status script, remove coverage jobs 2019-06-15 23:10:24 -05:00
src feat: list mode, fix version option 2019-06-24 23:47:12 -05:00
vendor/jsonpath-plus feat: make node selectors work 2019-06-15 17:53:07 -05:00
.gitignore docs: include some examples, explicitly state success 2019-06-15 18:56:42 -05:00
.gitlab-ci.yml fix(build): validate rules during build 2019-06-24 23:47:29 -05:00
.npmignore build: omit cache from npm bundle 2019-06-16 16:48:58 -05:00
CHANGELOG.md docs: fix changelog 2019-06-16 16:44:29 -05:00
Dockerfile feat: add rules to image, doc 2019-06-17 09:11:26 -05:00
LICENSE.md docs: add repo url, fix example command 2019-06-15 18:33:50 -05:00
Makefile feat: load definitions from rules (fixes #2) 2019-06-22 12:26:11 -05:00
README.md feat: support multiple documents per source (#11) 2019-06-24 22:50:46 -05:00
package.json feat: display diff when rule modifies data (fixes #3) 2019-06-22 11:48:41 -05:00
tsconfig.json feat: project, build, and bundle 2019-06-15 15:20:04 -05:00
yarn.lock feat: display diff when rule modifies data (fixes #3) 2019-06-22 11:48:41 -05:00

README.md

SALTY DOG

Rule-based YAML validator using JSON schemas. Capable of filtering elements to validate partial documents, inserting defaults, and other magic.

Usage

To run with Docker (recommended): docker run -v ${HOME}:/root:ro --rm -i ssube/salty-dog:master

To download, validate, and apply a Kubernetes resource:

> curl https://raw.githubusercontent.com/ssube/k8s-shards/master/roles/apps/gitlab/server/templates/ingress.yml | salty-dog \
    --rules rules/kubernetes.yml \
    --source - \
    --tag important | kubectl apply --dry-run -f -

...
{"name":"salty-dog","hostname":"cerberus","pid":7860,"level":30,"msg":"all rules passed","time":"2019-06-16T02:04:37.797Z","v":0}
ingress.extensions/gitlab created (dry run)

Docker

The latest semi-stable image is ssube/salty-dog:master.

The Docker container is published for each branch and git tag, tagged with the version slug (. replaced with -, mostly).

Rules are baked into the image in /rules. To use custom rules, mount them with -v $(pwd)/rules:/rules:ro and load with --rules /rules/foo.yml.

Check Mode

By default, salty-dog will validate the structure and contents of the --source document. If all rules pass, the document will be printed to --dest.

> cat examples/kubernetes-resources-pass.yml | salty-dog \
    --rules rules/kubernetes.yml \
    --tag important

...
[2019-06-15T23:53:34.223Z]  INFO: salty-dog/19839 on cerberus: all rules passed

> cat examples/kubernetes-resources-fail.yml | salty-dog \
    --rules rules/kubernetes.yml \
    --tag important

...
[2019-06-15T23:56:04.764Z] ERROR: salty-dog/22211 on cerberus: some rules failed (errors=1)

The --source and --dest default to stdin and stdout, respectively, but a path may be provided:

> salty-dog \
    --rules rules/kubernetes.yml \
    --tag important \
    --source examples/kubernetes-resources-pass.yml \
    --dest /tmp/kubernetes-resource.yml

...
[2019-06-15T23:53:34.223Z]  INFO: salty-dog/19839 on cerberus: all rules passed

Fix Mode

salty-dog can also add default values to missing properties with --mode fix. If a rule does not immediately pass with the --source document, but defaults are provided in the schema, the defaults will be inserted before printing to --dest.

Default Values

Properties that appear in the schema with a default provided will be added to each element as it is checked. Rules apply in order, as do their defaults.

Coercing Values

Properties that appear in the document with a different type than they have in the schema may be coerced, if the value is compatible with the schema type. The full matrix of valid type coercions is documented by Ajv.

Rules

Rules combine a jsonpath expression and JSON schema to select and validate the document.

The rule's select expression is used to select nodes that should be validated, which are filtered, then checked.

The structure of rule files and the rules within them are documented here.

Enabling Rules

All rules are disabled by default and must be enabled by name or tag.

To enable a single rule by name, --include-name foo-rule.

To enable a group of rules by tag, --include-tag foo.

Validate Rules

To validate the rules in the rules/ directory using the meta-rules:

> make run-rules

...
{"name":"salty-dog","hostname":"cerberus","pid":29403,"level":30,"msg":"all rules passed","time":"2019-06-16T00:56:55.132Z","v":0}

Build

This project is written in Typescript and requires node and yarn to build.

> git clone git@github.com:ssube/salty-dog.git
> cd salty-dog
> make

After building, run with: node out/bundle.js

make targets are provided for some common arguments:

> curl https://raw.githubusercontent.com/ssube/k8s-shards/master/roles/apps/gitlab/server/templates/ingress.yml | make run-stream 2> >(./node_modules/.bin/bunyan) > >(kubectl apply --dry-run -f -)

...
[2019-06-16T03:23:56.645Z]  INFO: salty-dog/8015 on cerberus: all rules passed
ingress.extensions/gitlab created (dry run)