From 146bcc72681aa1d84838415dd4bf09cedf1d51bb Mon Sep 17 00:00:00 2001 From: ssube Date: Mon, 24 Jun 2019 22:32:39 -0500 Subject: [PATCH] docs: clean up readme --- README.md | 301 +++++++++++++++++-------------------------- rules/kubernetes.yml | 4 +- 2 files changed, 122 insertions(+), 183 deletions(-) diff --git a/README.md b/README.md index edf9767..5f395f0 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,125 @@ # SALTY DOG -YAML linter/validator. +Rule-based YAML validator using JSON schemas. Capable of filtering elements to validate partial documents, inserting +defaults, and other magic. -Or, as an acronym, JSON **s**chema **a**nalysis, **l**inting, and **t**ransformation for **Y**AML, featuring -**d**efaults, **o**ptional fields, and other **g**ood stuff. +- [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) -- [SALTY DOG](#salty-dog) - - [Build](#build) - - [Usage](#usage) - - [Docker](#docker) - - [Validate](#validate) - - [Validate File](#validate-file) - - [Validate URL](#validate-url) - - [Validate Rules](#validate-rules) - - [Options](#options) - - [Count](#count) - - [Dest](#dest) - - [Format](#format) - - [Exclude](#exclude) - - [Exclude Level](#exclude-level) - - [Exclude Name](#exclude-name) - - [Exclude Tag](#exclude-tag) - - [Include](#include) - - [Include Level](#include-level) - - [Include Name](#include-name) - - [Include Tag](#include-tag) - - [Mode](#mode) - - [Rules](#rules) - - [Source](#source) +## 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: + +```shell +> 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`. + +```shell +> 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: + +```shell +> 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](https://ajv.js.org/coercion.html) +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 `filter`ed, then `check`ed. + +The structure of rule files and the rules within them [are documented here](docs/rules.md). + +### 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: + +```shell +> 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 @@ -39,15 +131,9 @@ This project is written in Typescript and requires `node` and `yarn` to build. > make ``` -## Usage +After building, run with: `node out/bundle.js` -To run with Docker (**recommended**): `docker run -v ${HOME}:/root:ro --rm -i ssube/salty-dog:master` - -To run after `yarn global add` or `npm i -g`: `salty-dog` - -To run after building: `node out/bundle.js` - -To run with `make`, apply with `kubectl`, and format logs with `bunyan`: +`make` targets are provided for some common arguments: ```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 -) @@ -55,151 +141,4 @@ To run with `make`, apply with `kubectl`, and format logs with `bunyan`: ... [2019-06-16T03:23:56.645Z] INFO: salty-dog/8015 on cerberus: all rules passed ingress.extensions/gitlab created (dry run) - ``` - -### Docker - -The Docker container is published for each branch and tag, using the slug (`.` replaced with `-`, mostly). The latest -semi-stable image is `ssube/salty-dog:master`. - -Rules are located in `/rules` within the image. To add your own rules, mount them with -`-v ${HOME}/your-rules:/user-rules:ro` and include with `--rules /user-rules/rules.yml`. - -### Validate - -`salty-dog` can validate JSON and YAML from files and streams, and emit it to a file or stream (with logs going -elsewhere). - -#### Validate File - -To validate a file: - -```shell -> salty-dog \ - --rules rules/kubernetes.yml \ - --source examples/kubernetes-resources-fail.yml \ - --tag important - -... -[2019-06-15T23:56:04.764Z] ERROR: salty-dog/22211 on cerberus: some rules failed (errors=1) - -> cat examples/kubernetes-resources-pass.yml | salty-dog \ - --rules rules/kubernetes.yml \ - --source - \ - --tag important - -... -[2019-06-15T23:53:34.223Z] INFO: salty-dog/19839 on cerberus: all rules passed -``` - -#### Validate URL - -To validate a URL: - -```shell -> 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) -... -``` - -#### Validate Rules - -To validate the rules in the `rules/` directory using the meta-rules: - -```shell -> 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} -``` - -### Options - -#### Count - -- Alias: `c` - -Exit with the error count (max of 255) rather than `0` or `1`. - -#### Dest - -- Alias: `d` -- Default: `-` - -Path to write output data. - -Defaults to stdout (`-`). - -#### Format - -- Default: `yaml` - -Output format. - -Options: - -- `yaml` - -#### Exclude - -Excludes take priority over includes: a rule matching some of both will be excluded. - -##### Exclude Level - -Exclude rules by log level. - -##### Exclude Name - -Exclude rules by name. - -##### Exclude Tag - -Exclude rules by tag. - -#### Include - -##### Include Level - -Include rules by log level. - -##### Include Name - -Include rules by name. - -##### Include Tag - -- Alias: `t`, `tag` - -Include rules by tag. - -#### Mode - -- Alias: `m` -- Default: `check` - -The application mode. - -Options: - -- `check` runs each rule and exits with an indicative status -- `fix` runs each rule and updates the source data with any defaults before running the next rule - -#### Rules - -The path to a file containing some `rules`. - -#### Source - -- Alias: `s` -- Default: `-` - -The source file to validate. - -Defaults to stdin (`-`) to work with pipes: `cat file.yml | salty-dog --source -` diff --git a/rules/kubernetes.yml b/rules/kubernetes.yml index 6b90a59..a3b162b 100644 --- a/rules/kubernetes.yml +++ b/rules/kubernetes.yml @@ -56,7 +56,7 @@ rules: limits: type: object properties: - cpu: &resources-cpu + cpu: *resources-cpu # ensure the limits aren't *too* low check: @@ -99,4 +99,4 @@ rules: properties: replica: type: number - minimum: 1 \ No newline at end of file + minimum: 1