Add README and documentation (#5)

Author: viswajithiii

.circleci/config.yml

@@ -16,6 +16,21 @@ jobs:
         command: |
           make lint
 
+    - run:
+        name: Ensure generated docs are up-to-date
+        command: |
+          make generated-docs
+          git diff --exit-code HEAD
+
+  test:
+    executor: custom
+    steps:
+    - checkout
+    - run:
+        name: Run unit tests
+        command: |
+          make test
+
 workflows:
   version: 2
   build:
@@ -24,3 +39,7 @@ workflows:
         filters:
           tags:
             only: /.*/
+    - test:
+        filters:
+          tags:
+            only: /.*/

.golangci.yml

@@ -54,6 +54,7 @@ linters-settings:
       - unnecessaryDefer
       - importShadow
       - emptyStringTest
+      - hugeParam
   nolintlint:
     allow-leading-space: false # require machine-readable nolint directives (i.e. with no leading space)
     allow-unused: false # report any unused nolint directives

Makefile

@@ -60,14 +60,33 @@ staticcheck: $(STATICCHECK_BIN)
 .PHONY: lint
 lint: golangci-lint staticcheck
 
-#############
-## Compile ##
-#############
+####################
+## Code generation #
+####################
+
+.PHONY: generated-docs
+generated-docs: build
+	./bin/kube-linter templates list --format markdown > docs/generated/templates.md
+	./bin/kube-linter checks list --format markdown > docs/generated/checks.md
 
 .PHONY: packr
 packr: $(PACKR_BIN)
 	packr
 
+#############
+## Compile ##
+#############
+
+
 .PHONY: build
 build: packr
-	go build -o kube-linter ./cmd/kubelinter
+	go build -o ./bin/kube-linter ./cmd/kube-linter
+
+##########
+## Test ##
+##########
+
+.PHONY: test
+test: packr
+	go test ./...
+

README.md

@@ -1 +1,33 @@
 # kube-linter
+
+kube-linter is a static analysis tool that checks Kubernetes YAML files to ensure the applications represented in them
+adhere to best practices.
+
+In detail, `kube-linter` is a binary that takes in paths to YAML files, and runs a list of checks
+against them. If any lint errors are found, they are printed to standard error, and `kube-linter` returns a non-zero 
+exit code.
+
+The list of checks that is run is configurable. `kube-linter` comes with several built-in checks, only some of which
+are enabled by default. Users can also create custom checks.
+
+## Install
+
+If you have `go` installed, you can run `go get golang.stackrox.io/kube-linter/cmd/kube-linter`.
+
+Alternatively, `kube-linter` binaries can be downloaded from [the Releases page](https://github.com/stackrox/kube-linter/releases).
+Download the `kube-linter` binary, and add it to your PATH.
+
+You can also build `kube-linter` from source by cloning the repo, and running `make build`. This will compile a `kube-linter`
+binary into the `bin` folder inside the repo.
+
+Note that you will need to have the `go` command installed for this to work.
+To install the Go command, follow the instructions [here](https://golang.org/doc/install).
+
+## Usage
+
+See the [documentation](./docs) for details on how to get started.
+
+# WARNING: Breaking changes possible
+
+kube-linter is currently in a very early stage of development. There may be breaking changes to the command usage, flags
+and config file formats.

bin/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

cmd/kubelinter/kube-linter.go renamed to cmd/kube-linter/kube-linter.go

@@ -0,0 +1,18 @@
+# customChecks defines custom checks.
+customChecks:
+- name: "required-label-app"
+  template: "required-label"
+  params:
+    key: "app"
+checks:
+  # if doNotAutoAddDefaults is true, default checks are not automatically added.
+  doNotAutoAddDefaults: false
+
+  # include explicitly adds checks, by name. You can reference any of the built-in checks.
+  # Note that customChecks defined above are included automatically.
+  include:
+  - "required-label-owner"
+  # exclude explicitly excludes checks, by name. exclude has the highest priority: if a check is
+  # in exclude, then it is not considered, even if it is in include as well.
+  exclude:
+  - "privileged"

config.yaml.example

@@ -0,0 +1,38 @@
+
+# Documentation
+
+Welcome to the `kube-linter` documentation. Read on for more detailed information about using and configuring the tool.
+
+## Exploring the CLI
+
+You can run `kube-linter --help` to see a list of supported commands and flags. For each subcommand, you can
+run `kube-linter <subcommand> --help` to see detailed help text and flags for it.
+
+## Running the linter
+
+To lint directories or files, simply run `./kube-linter lint files_or_dirs ...`. If a directory is passed, all files
+with `.yaml` or `.yml` extensions are parsed, and Kubernetes objects are loaded from them. If a file is passed,
+it is parsed irrespective of extension.
+
+Users can pass a config file using the `--config` flag to control which checks are executed, and to configure custom checks.
+An example config file is provided [here](../config.yaml.example).
+
+## Built-in checks 
+
+`kube-linter` comes with a list of built-in checks, which you can find [here](generated/checks.md). Only some
+built-in checks are enabled by default -- others must be explicitly enabled in the config.
+
+## Custom checks
+
+### Check Templates
+
+In `kube-linter`, checks are concrete realizations of check templates. A check template describes a class of check -- it
+contains logic (written in Go code) that would execute the check, and lays out (zero or more) parameters that it takes.
+
+The list of supported check templates, along with their metadata, can be found [here](generated/templates.md).
+
+### Custom checks
+
+All checks in `kube-linter` are defined by referencing a check template, passing parameters to it, and adding additional
+check specific metadata (like check name and description). Users can configure custom checks the same way built-in checks
+are configured, and add them to the config file. The built-in checks are specified [here](../internal/builtinchecks).

docs/README.md

@@ -0,0 +1,7 @@
+The following table enumerates built-in checks:
+
+| Name | Enabled by default | Description | Template | Parameters |
+| ---- | ------------------ | ----------- | -------- | ---------- |
+ | env-var-secret | No | Alert on objects using a secret in an environment variable | env-var |- `name`: `.*secret.*` <br />|
+ | privileged-container | Yes | Alert on deployments with containers running in privileged mode | privileged | none |
+ | required-label-owner | No | Alert on objects without the 'owner' label | required-label |- `key`: `owner` <br />|

docs/generated/checks.md

@@ -0,0 +1,7 @@
+The following table enumerates supported check templates:
+
+| Name | Description | Supported Objects | Parameters |
+| ---- | ----------- | ----------------- | ---------- |
+ | env-var | Flag environment variables that match the provided patterns | DeploymentLike |- `name` (required): A regex for the env var name <br />- `value`: A regex for the env var value <br />|
+ | privileged | Flag privileged containers | DeploymentLike | none |
+ | required-label | Flag objects not carrying at least one label matching the provided patterns | Any |- `key` (required): A regex for the key of the required label <br />- `value`: A regex for the value of the required label <br />|