From ce75930a3c1a47a6d1ad4b0e291d9bf58420585d Mon Sep 17 00:00:00 2001 From: ssube Date: Sat, 15 Jun 2019 21:08:21 -0500 Subject: [PATCH] docs: expand examples --- README.md | 93 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 73 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index d880d41..be9aa72 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,21 @@ # SALTY DOG -JSON **s**chema **a**nalysis, **l**inting, and **t**ransformation for **Y**AML, featuring **d**efaults, **o**ptional -fields, and other **g**ood stuff. +YAML linter/validator. + +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) - [Build](#build) - [Usage](#usage) + - [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) @@ -22,6 +30,8 @@ fields, and other **g**ood stuff. ## Build +This project is written in Typescript and requires Node to be built. + ```shell > git clone git@github.com:ssube/salty-dog.git > make @@ -29,36 +39,60 @@ fields, and other **g**ood stuff. ## Usage -To validate the rules in the `rules/` directory: +### Validate -```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} -``` +`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 -> cat rules/examples/kubernetes-require-resources-fail.yml |\ - salty-dog \ - --rules rules/kubernetes.yml \ - --source - \ - --tag important |\ - ./node_modules/.bin/bunyan +> salty-dog \ + --rules rules/kubernetes.yml \ + --source rules/examples/kubernetes-require-resources-fail.yml \ + --tag important +... [2019-06-15T23:56:04.764Z] ERROR: salty-dog/22211 on cerberus: some rules failed (errors=1) -> cat rules/examples/kubernetes-require-resources-pass.yml |\ - salty-dog \ - --rules rules/kubernetes.yml \ - --source - \ - --tag important |\ - ./node_modules/.bin/bunyan +> cat rules/examples/kubernetes-require-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 @@ -67,6 +101,25 @@ To validate a file: 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.