Add README and documentation #5
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| * | ||
| !.gitignore |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| # 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. | ||
| # Otherwise, they are. | ||
|
There was a problem hiding this comment. Remove, this is pretty obvious based on the previous line There was a problem hiding this comment. Also, I think doNotAutoAddDefaults is backwards, should be autoAddDefaults that defaults to true There was a problem hiding this comment. it's also just a bit too verbose |
||
| 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" | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 />| |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 />| |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMHO a readme in an open source repository should always include custom build instructions and contributing guidelines (or references to these)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
👍
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added instructions for building from source. Contributing guidelines, will do in a follow-up -- we still need to iron those out.