polaris/docs/usage.md

Installation and Usage

Polaris can be installed on your cluster using kubectl or Helm. It can also be run as a local binary, which will use your kubeconfig to connect to the cluster or run against local YAML files.

Configuration

Polaris supports a wide range of validations covering a number of Kubernetes best practices. Here's a sample configuration file that includes all currently supported checks. The default configuration contains a number of those checks. This repository also includes a sample full configuration file that enables all available checks.

Each check can be assigned a severity. Only checks with a severity of error or warning will be validated. The results of these validations are visible on the dashboard. In the case of the validating webhook, only failures with a severity of error will result in a change being rejected.

Polaris validation checks fall into several different categories:

• Health Checks
• Images
• Networking
• Resources
• Security

CLI Options

# high-level flags
-version
      Prints the version of Polaris
-config string
      Location of Polaris configuration file
-kubeconfig string
      Path to a kubeconfig. Only required if out-of-cluster.
-log-level string
      Logrus log level (default "info")
-master string
      The address of the Kubernetes API server. Overrides any value in kubeconfig. Only required if out-of-cluster.

# dashboard flags
-dashboard
      Runs the webserver for Polaris dashboard.
-dashboard-base-path string
      Path on which the dashboard is served (default "/")
-dashboard-port int
      Port for the dashboard webserver (default 8080)
-display-name string
      An optional identifier for the audit

# audit flags
-audit
      Runs a one-time audit.
-audit-path string
      If specified, audits one or more YAML files instead of a cluster
-output-file string
      Destination file for audit results
-output-format string
      Output format for results - json, yaml, or score (default "json")
-output-url string
      Destination URL to send audit results
-set-exit-code-below-score int
      When running with --audit, set an exit code of 4 when the score is below this threshold (1-100)
-set-exit-code-on-error
      When running with --audit, set an exit code of 3 when the audit contains error-level issues.

# webhook flags
-webhook
      Runs the webhook webserver.
-webhook-port int
      Port for the webhook webserver (default 9876)
-disable-webhook-config-installer
      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 or can be installed with Homebrew:

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%:

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.