docs: getting started, list mode, badges
This commit is contained in:
parent
18a3321061
commit
2122516e09
103
README.md
103
README.md
|
|
@ -4,24 +4,37 @@ Rule-based YAML validator using JSON schemas. Capable of filtering elements to v
|
|||
multiple documents per stream or file, inserting defaults, and other magic.
|
||||
|
||||
- [SALTY DOG](#SALTY-DOG)
|
||||
- [Getting Started](#Getting-Started)
|
||||
- [Status](#Status)
|
||||
- [Releases](#Releases)
|
||||
- [Usage](#Usage)
|
||||
- [Docker](#Docker)
|
||||
- [Node](#Node)
|
||||
- [Global](#Global)
|
||||
- [Project](#Project)
|
||||
- [Modes](#Modes)
|
||||
- [Check Mode](#Check-Mode)
|
||||
- [Fix Mode](#Fix-Mode)
|
||||
- [Default Values](#Default-Values)
|
||||
- [Coercing Values](#Coercing-Values)
|
||||
- [List Mode](#List-Mode)
|
||||
- [Rules](#Rules)
|
||||
- [Enabling Rules](#Enabling-Rules)
|
||||
- [Validate Rules](#Validate-Rules)
|
||||
- [Build](#Build)
|
||||
|
||||
## Usage
|
||||
## Getting Started
|
||||
|
||||
`salty-dog` is distributed as a package or container.
|
||||
`salty-dog` is distributed as a package or container, and can be installed or pulled:
|
||||
|
||||
While the container is the preferred way of running `salty-dog`, it has a serious limitation: `docker run` combines
|
||||
`stdout` and `stderr`, making it impossible to separate logs and the output document. Writing either the logs or dest
|
||||
to a file works around this.
|
||||
```shell
|
||||
> docker pull ssube/salty-dog:master
|
||||
> yarn global add salty-dog
|
||||
```
|
||||
|
||||
**Note:** while the container is the preferred way of running `salty-dog`, it has a serious limitation: `docker run`
|
||||
combines `stdout` and `stderr`, making it impossible to separate logs and the output document. Writing either the logs
|
||||
or dest to a file works around this.
|
||||
|
||||
To download, validate, and apply a Kubernetes resource:
|
||||
|
||||
|
|
@ -36,6 +49,35 @@ To download, validate, and apply a Kubernetes resource:
|
|||
{"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)
|
||||
```
|
||||
## Status
|
||||
|
||||
[](https://git.apextoaster.com/ssube/salty-dog/commits/master)
|
||||
[](https://github.com/ssube/salty-dog/blob/master/LICENSE.md)
|
||||
|
||||
[](https://github.com/ssube/salty-dog/issues?q=is%3Aopen+is%3Aissue+label%3Atype%2Fbug)
|
||||
[](https://github.com/ssube/salty-dog/issues?q=is%3Aopen+is%3Aissue)
|
||||
[](https://github.com/ssube/salty-dog/issues?q=is%3Aissue+is%3Aclosed)
|
||||
|
||||
[](https://snyk.io/test/github/ssube/salty-dog)
|
||||
[](https://david-dm.org/ssube/salty-dog)
|
||||
[](https://david-dm.org/ssube/salty-dog?type=dev)
|
||||
|
||||
[](https://codeclimate.com/github/ssube/salty-dog/maintainability)
|
||||
[](https://codeclimate.com/github/ssube/salty-dog/trends/technical_debt)
|
||||
[](https://codeclimate.com/github/ssube/salty-dog/issues)
|
||||
|
||||
[](https://lgtm.com/projects/g/ssube/salty-dog/context:javascript)
|
||||
[](https://lgtm.com/projects/g/ssube/salty-dog/alerts/)
|
||||
|
||||
## Releases
|
||||
|
||||
[](https://github.com/ssube/salty-dog/releases)
|
||||
[](https://github.com/ssube/salty-dog/compare/v0.4.1...master)
|
||||
|
||||
[](https://www.npmjs.com/package/salty-dog)
|
||||
[](https://microbadger.com/images/ssube/salty-dog:master)
|
||||
|
||||
## Usage
|
||||
|
||||
### Docker
|
||||
|
||||
|
|
@ -50,6 +92,35 @@ mostly).
|
|||
Rules are baked into the image in `/salty-dog/rules`. To use custom rules, mount them with
|
||||
`-v $(pwd)/rules:/salty-dog/rules:ro` and load with `--rules /rules/foo.yml`.
|
||||
|
||||
### Node
|
||||
|
||||
#### Global
|
||||
|
||||
To install with Yarn as a global CLI tool: `yarn global add salty-dog`
|
||||
|
||||
To run with Node:
|
||||
|
||||
```shell
|
||||
> export PATH="${PATH}:$(yarn global bin)"
|
||||
> salty-dog --help
|
||||
```
|
||||
|
||||
#### Project
|
||||
|
||||
To install with Yarn for a single project: `yarn add -D salty-dog`
|
||||
|
||||
To run with Node:
|
||||
|
||||
```shell
|
||||
> export PATH="${PATH}:$(yarn bin)"
|
||||
> salty-dog --help
|
||||
```
|
||||
|
||||
### Modes
|
||||
|
||||
`salty-dog` can run in a few different modes: `check` mode will report errors, `fix` mode will attempt to modify the
|
||||
input document, and `list` mode will print the active set of rules.
|
||||
|
||||
### Check Mode
|
||||
|
||||
By default, `salty-dog` will validate the structure and contents of the `--source` document. If all rules pass, the
|
||||
|
|
@ -102,6 +173,28 @@ Properties that appear in the document with a different `type` than they have in
|
|||
value is compatible with the schema type. [The full matrix of valid type coercions](https://ajv.js.org/coercion.html)
|
||||
is documented by Ajv.
|
||||
|
||||
### List Mode
|
||||
|
||||
`salty-dog` can list the active set of rules, to help debug tags and inclusion.
|
||||
|
||||
```shell
|
||||
> salty-dog \
|
||||
--rules rules/kubernetes.yml \
|
||||
--tag important \
|
||||
--mode list
|
||||
|
||||
...
|
||||
[2019-06-30T18:39:11.930Z] INFO: salty-dog/26330 on cerberus: listing active rules
|
||||
rules: [
|
||||
{
|
||||
"desc": "resource limits are too low",
|
||||
"level": "debug",
|
||||
"name": "kubernetes-resources-minimum-cpu",
|
||||
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
Rules combine a jsonpath expression and JSON schema to select and validate the document.
|
||||
|
|
|
|||
Loading…
Reference in New Issue