6.8 KiB
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.
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:
Custom Checks
If you'd like to create your own checks, you can use JSON Schema. For example, to disallow images from quay.io:
checks:
imageRegistry: warning
customChecks:
imageRegistry:
successMessage: Image comes from allowed registries
failureMessage: Image should not be from disallowed registry
category: Images
target: Container # target can be "Container" or "Pod"
schema:
'$schema': http://json-schema.org/draft-07/schema
type: object
properties:
image:
type: string
not:
pattern: ^quay.io
Schemas can also be specified as JSON strings instead of YAML, for easier copy/pasting:
customChecks:
foo:
jsonSchema: |
{
"$schema": "http://json-schema.org/draft-07/schema",
"type": "object"
}
We extend JSON Schema with resourceMinimum and resourceMaximum fields to help compare memory and CPU resource
strings like 1000m and 1G. You can see an example in the extended config
There are additional examples in the checks folder.
Exemptions
Exemptions can be added two ways: by annotating a controller, or editing the Polaris config.
To exempt a controller via annotations, use the annotation polaris.fairwinds.com/exempt=true, e.g.
kubectl annotate deployment my-deployment polaris.fairwinds.com/exempt=true
To exempt a controller via the config, you have to specify a list of controller names and a list of rules, e.g.
exemptions:
- controllerNames:
- dns-controller
rules:
- hostNetworkSet
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