Skip to content

Commit

Permalink
Update docs (#186)
Browse files Browse the repository at this point in the history
  • Loading branch information
Bobby Brennan authored Aug 5, 2019
1 parent f03f97a commit dddeeb3
Show file tree
Hide file tree
Showing 2 changed files with 101 additions and 88 deletions.
34 changes: 23 additions & 11 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,19 +14,20 @@
[circleci-image]: https://circleci.com/gh/FairwindsOps/polaris.svg?style=svg
[circleci-link]: https://circleci.com/gh/FairwindsOps/polaris.svg

Polaris helps keep your cluster healthy. It runs a variety of checks to ensure that
Kubernetes deployments are configured using best practices, helping you avoid
Fairwinds' Polaris keeps your clusters sailing smoothly. It runs a variety of checks to ensure that
Kubernetes pods and controllers are configured using best practices, helping you avoid
problems in the future. Polaris can be run in a few different modes:

- A dashboard that provides an overview of how well current deployments are configured within a cluster.
- An experimental validating webhook that can prevent any future deployments that do not live up to a configured standard.
- A command-line audit that can be incorporated into your CI/CD pipeline
Polaris can be run in three different modes:
* As a [dashboard](#dashboard), so you can audit what's running inside your cluster.
* As a [validating webhook](#webhook), so you can automatically reject workloads that don't adhere to your organization's policies.
* As a [command-line tool](#cli), so you can test local YAML files, e.g. as part of a CI/CD process.

**Want to learn more?** Fairwinds holds [office hours on Zoom](https://zoom.us/j/242508205) the first Friday of every month, at 12pm Eastern. You can also reach out via email at `opensource@fairwinds.com`

# Dashboard Quickstart

```
```bash
kubectl apply -f https://github.com/FairwindsOps/polaris/releases/latest/download/dashboard.yaml
kubectl port-forward --namespace polaris svc/polaris-dashboard 8080:80
```
Expand All @@ -35,9 +36,11 @@ With the port forwarding in place, you can open http://localhost:8080 in your br
* * *

# Components

## Dashboard
> [View installation instructions](docs/usage.md#dashboard)
The Polaris dashboard is a way to get a simple visual overview of the current state of your Kubernetes deployments as well as a roadmap for what can be improved. The dashboard provides a cluster wide overview as well as breaking out results by category, namespace, and deployment.
The Polaris dashboard is a way to get a simple visual overview of the current state of your Kubernetes workloads as well as a roadmap for what can be improved. The dashboard provides a cluster wide overview as well as breaking out results by category, namespace, and workload.

<p align="center">
<img src="/dashboard-screenshot.png" alt="Polaris Dashboard" />
Expand All @@ -47,13 +50,22 @@ Our default standards in Polaris are rather high, so don’t be surprised if you


## Webhook
> [View installation instructions](docs/usage.md#webhook)
Polaris includes experimental support for an optional validating webhook. This accepts the same configuration as the dashboard, and can run the same validations. This webhook will reject any workloads that trigger a validation error. This is indicative of the greater goal of Polaris, not just to encourage better configuration through dashboard visibility, but to actually enforce it with this webhook. *Although we are working towards greater stability and better test coverage, we do not currently consider this webhook component production ready.*

Unfortunately we have not found a way to display warnings as part of `kubectl` output unless we are rejecting a workload altogether. That means that any checks with a severity of `warning` will still pass webhook validation, and the only evidence of that warning will either be in the Polaris dashboard or the Polaris webhook logs.

Polaris includes experimental support for an optional validating webhook. This accepts the same configuration as the dashboard, and can run the same validations. This webhook will reject any deployments that trigger a validation error. This is indicative of the greater goal of Polaris, not just to encourage better configuration through dashboard visibility, but to actually enforce it with this webhook. *Although we are working towards greater stability and better test coverage, we do not currently consider this webhook component production ready.*
## CLI
> [View installation instructions](docs/usage.md#cli)
Unfortunately we have not found a way to display warnings as part of `kubectl` output unless we are rejecting a deployment altogether. That means that any checks with a severity of `warning` will still pass webhook validation, and the only evidence of that warning will either be in the Polaris dashboard or the Polaris webhook logs.
Polaris can also be used on the command line, either to audit local files or a running cluster.
This is particularly helpful for running Polaris against your infrastructure-as-code as part of a
CI/CD pipeline. Use the available [command line flags](docs/usage.md#running-with-ci-cd)
to cause CI/CD to fail if your Polaris score drops below a certain threshold, or if any errors arise.

# Usage Documentation
See the [Usage Guide](/docs/usage.md) in the docs folder.
# Installation and Usage
See the [Usage Guide](/docs/usage.md) for details on different methods for installing and using Polaris.

# Contributing
PRs welcome! Check out the [Contributing Guidelines](CONTRIBUTING.md),
Expand Down
155 changes: 78 additions & 77 deletions docs/usage.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,84 @@ Polaris validation checks fall into several different categories:
- [Resources](check-documentation/resources.md)
- [Security](check-documentation/security.md)

## CLI Options
# Installing
There are several ways to install and use Polaris. Below outline ways to install using `kubectl`, `helm` and `local binary`.

## Dashboard
The dashboard can be installed on a cluster using kubectl or Helm. It can also be run locally,
connecting to your cluster using the credentials stored in your `KUBECONFIG`.

### kubectl
```bash
kubectl apply -f https://github.com/fairwindsops/polaris/releases/latest/download/dashboard.yaml
kubectl port-forward --namespace polaris svc/polaris-dashboard 8080:80
```
### Helm
```bash
helm repo add reactiveops-stable https://charts.reactiveops.com/stable
helm upgrade --install polaris reactiveops-stable/polaris --namespace polaris
kubectl port-forward --namespace polaris svc/polaris-dashboard 8080:80
```

### Local Binary
You'll need a valid `KUBECONFIG` set up for the dashboard to connect to your cluster.

Binary releases can be dowloaded from the [releases page](https://github.com/fairwindsops/polaris/releases)
or can be installed with [Homebrew](https://brew.sh/):
```bash
brew tap reactiveops/tap
brew install reactiveops/tap/polaris
polaris --dashboard --dashboard-port 8080
```

## Webhook
### kubectl
```bash
kubectl apply -f https://github.com/fairwindsops/polaris/releases/latest/download/webhook.yaml
```

### Helm
```bash
helm repo add reactiveops-stable https://charts.reactiveops.com/stable
helm upgrade --install polaris reactiveops-stable/polaris --namespace polaris \
--set webhook.enable=true --set dashboard.enable=false
```

## CLI
### Installation
Binary releases can be downloaded from the [releases page](https://github.com/fairwindsops/polaris/releases)
or can be installed with [Homebrew](https://brew.sh/):
```bash
brew tap reactiveops/tap
brew install reactiveops/tap/polaris
polaris --version
```

You can run audits on the command line and see the output as JSON, YAML, or a raw score:
```bash
polaris --audit --output-format yaml > report.yaml
polaris --audit --output-format score
# 92
```

Both the dashboard and audits can run against a local directory or YAML file
rather than a cluster:
```bash
polaris --audit --audit-path ./deploy/
```

#### Running with CI/CD
You can integrate Polaris into CI/CD for repositories containing infrastructure-as-code.
For example, to fail if polaris detects *any* error-level issues, or if the score drops below 90%:
```bash
polaris --audit --audit-path ./deploy/ \
--set-exit-code-on-error \
--set-exit-code-below-score 90
```

For more on exit code meanings, see [exit-code docs](exit-codes.md).

#### CLI Options

```
# high-level flags
Expand Down Expand Up @@ -67,79 +144,3 @@ Polaris validation checks fall into several different categories:
disable the installer in the webhook server, so it won't install webhook configuration resources during bootstrapping
```

# Installing
There are several ways to install and use Polaris. Below outline ways to install using `kubectl`, `helm` and `local binary`.

## kubectl
### Dashboard
```
kubectl apply -f https://github.com/fairwindsops/polaris/releases/latest/download/dashboard.yaml
kubectl port-forward --namespace polaris svc/polaris-dashboard 8080:80
```

### Webhook
```
kubectl apply -f https://github.com/fairwindsops/polaris/releases/latest/download/webhook.yaml
```

## Helm
Start by adding the ReactiveOps Helm repo:
```
helm repo add reactiveops-stable https://charts.reactiveops.com/stable
```

### Dashboard
```
helm upgrade --install polaris reactiveops-stable/polaris --namespace polaris
kubectl port-forward --namespace polaris svc/polaris-dashboard 8080:80
```

### Webhook
```
helm upgrade --install polaris reactiveops-stable/polaris --namespace polaris \
--set webhook.enable=true --set dashboard.enable=false
```

## Local Binary
### Installation
Binary releases are available on the [releases page](https://github.com/fairwindsops/polaris/releases) or can be installed with [Homebrew](https://brew.sh/):
```
brew tap reactiveops/tap
brew install reactiveops/tap/polaris
polaris --version
```

You can run `polaris --help` to see a full list of options.

### Dashboard
The dashboard can be run on your local machine, without installing anything on the cluster.
Polaris will use your local kubeconfig to connect to the cluster.

```
polaris --dashboard --dashboard-port 8080
```

### Audits
You can also run audits on the command line and see the output as JSON, YAML, or a raw score:
```
polaris --audit --output-format yaml > report.yaml
polaris --audit --output-format score
# 92
```

Both the dashboard and audits can run against a local directory or YAML file
rather than a cluster:
```
polaris --audit --audit-path ./deploy/
```

### Running with CI/CD
You can integrate Polaris into CI/CD for repositories containing infrastructure-as-code.
For example, to fail if polaris detects *any* error-level issues, or if the score drops below 90%:
```bash
polaris --audit --audit-path ./deploy/ \
--set-exit-code-on-error \
--set-exit-code-below-score 90
```

For more on exit code meanings, see [exit-code docs](exit-codes.md).

0 comments on commit dddeeb3

Please sign in to comment.