1
0
Fork 0
salty-dog/README.md

145 lines
4.4 KiB
Markdown
Raw Normal View History

2019-06-15 23:07:46 +00:00
# SALTY DOG
2019-06-25 03:32:39 +00:00
Rule-based YAML validator using JSON schemas. Capable of filtering elements to validate partial documents, inserting
defaults, and other magic.
- [SALTY DOG](#SALTY-DOG)
- [Usage](#Usage)
- [Docker](#Docker)
- [Check Mode](#Check-Mode)
- [Fix Mode](#Fix-Mode)
- [Default Values](#Default-Values)
- [Coercing Values](#Coercing-Values)
- [Rules](#Rules)
- [Enabling Rules](#Enabling-Rules)
- [Validate Rules](#Validate-Rules)
- [Build](#Build)
2019-06-15 23:07:46 +00:00
## Usage
To run with Docker (**recommended**): `docker run -v ${HOME}:/root:ro --rm -i ssube/salty-dog:master`
2019-06-25 03:32:39 +00:00
To download, validate, and apply a Kubernetes resource:
```shell
2019-06-25 03:32:39 +00:00
> 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 -
...
2019-06-25 03:32:39 +00:00
{"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)
```
2019-06-17 14:11:26 +00:00
### Docker
2019-06-25 03:32:39 +00:00
The latest semi-stable image is `ssube/salty-dog:master`.
2019-06-17 14:11:26 +00:00
2019-06-25 03:32:39 +00:00
The Docker container is published for each branch and git tag, tagged with the version slug (`.` replaced with `-`,
mostly).
2019-06-17 14:11:26 +00:00
2019-06-25 03:32:39 +00:00
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`.
2019-06-25 03:32:39 +00:00
### Check Mode
2019-06-16 02:08:21 +00:00
2019-06-25 03:32:39 +00:00
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`.
2019-06-15 23:07:46 +00:00
```shell
2019-06-16 02:21:42 +00:00
> cat examples/kubernetes-resources-pass.yml | salty-dog \
2019-06-16 02:08:21 +00:00
--rules rules/kubernetes.yml \
--tag important
2019-06-16 02:08:21 +00:00
...
[2019-06-15T23:53:34.223Z] INFO: salty-dog/19839 on cerberus: all rules passed
2019-06-16 02:08:21 +00:00
2019-06-25 03:32:39 +00:00
> cat examples/kubernetes-resources-fail.yml | salty-dog \
2019-06-16 02:08:21 +00:00
--rules rules/kubernetes.yml \
2019-06-25 03:32:39 +00:00
--tag important
2019-06-16 02:08:21 +00:00
...
2019-06-25 03:32:39 +00:00
[2019-06-15T23:56:04.764Z] ERROR: salty-dog/22211 on cerberus: some rules failed (errors=1)
2019-06-16 02:08:21 +00:00
2019-06-25 03:32:39 +00:00
```
2019-06-16 02:08:21 +00:00
2019-06-25 03:32:39 +00:00
The `--source` and `--dest` default to stdin and stdout, respectively, but a path may be provided:
2019-06-16 02:08:21 +00:00
```shell
2019-06-25 03:32:39 +00:00
> salty-dog \
--rules rules/kubernetes.yml \
--tag important \
--source examples/kubernetes-resources-pass.yml \
--dest /tmp/kubernetes-resource.yml
2019-06-16 02:08:21 +00:00
...
2019-06-25 03:32:39 +00:00
[2019-06-15T23:53:34.223Z] INFO: salty-dog/19839 on cerberus: all rules passed
2019-06-16 02:08:21 +00:00
```
2019-06-25 03:32:39 +00:00
### Fix Mode
2019-06-15 23:58:06 +00:00
2019-06-25 03:32:39 +00:00
`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`.
2019-06-15 23:58:06 +00:00
2019-06-25 03:32:39 +00:00
#### Default Values
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
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.
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
#### Coercing Values
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
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](https://ajv.js.org/coercion.html)
is documented by Ajv.
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
## Rules
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
Rules combine a jsonpath expression and JSON schema to select and validate the document.
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
The rule's `select` expression is used to select nodes that should be validated, which are `filter`ed, then `check`ed.
2019-06-15 23:58:06 +00:00
2019-06-25 03:32:39 +00:00
The structure of rule files and the rules within them [are documented here](docs/rules.md).
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
### Enabling Rules
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
All rules are disabled by default and must be enabled by name or tag.
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
To enable a single rule by name, `--include-name foo-rule`.
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
To enable a group of rules by tag, `--include-tag foo`.
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
### Validate Rules
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
To validate the rules in the `rules/` directory using the meta-rules:
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
```shell
> make run-rules
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
...
{"name":"salty-dog","hostname":"cerberus","pid":29403,"level":30,"msg":"all rules passed","time":"2019-06-16T00:56:55.132Z","v":0}
```
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
## Build
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
This project is written in Typescript and requires `node` and `yarn` to build.
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
```shell
> git clone git@github.com:ssube/salty-dog.git
> cd salty-dog
> make
```
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
After building, run with: `node out/bundle.js`
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
`make` targets are provided for some common arguments:
2019-06-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
```shell
> 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-15 23:07:46 +00:00
2019-06-25 03:32:39 +00:00
...
[2019-06-16T03:23:56.645Z] INFO: salty-dog/8015 on cerberus: all rules passed
ingress.extensions/gitlab created (dry run)
```