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

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

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

Helm

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 or can be installed with Homebrew:

brew tap reactiveops/tap
brew install reactiveops/tap/polaris
polaris --dashboard --dashboard-port 8080

Webhook

kubectl

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

Helm

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 or can be installed with Homebrew:

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:

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.

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