From 1cae69d080466511158115f36692fbdd295dd564 Mon Sep 17 00:00:00 2001 From: Bader Boland Date: Fri, 24 Jan 2020 13:06:26 -0500 Subject: [PATCH] Updated documentation --- cmd/polaris/audit.go | 3 +- cmd/polaris/dashboard.go | 5 +++ cmd/polaris/root.go | 1 + cmd/polaris/webhook.go | 2 +- docs/usage.md | 93 +++++++++++++++++++++++----------------- 5 files changed, 61 insertions(+), 43 deletions(-) diff --git a/cmd/polaris/audit.go b/cmd/polaris/audit.go index 4758b889..46ecb1b6 100644 --- a/cmd/polaris/audit.go +++ b/cmd/polaris/audit.go @@ -35,7 +35,6 @@ var minScore int var auditOutputURL string var auditOutputFile string var auditOutputFormat string -var displayName string func init() { @@ -45,7 +44,7 @@ func init() { auditCmd.PersistentFlags().IntVar(&minScore, "set-exit-code-below-score", 0, "Set an exit code of 4 when the score is below this threshold (1-100).") auditCmd.PersistentFlags().StringVar(&auditOutputURL, "output-url", "", "Destination URL to send audit results.") auditCmd.PersistentFlags().StringVar(&auditOutputFile, "output-file", "", "Destination file for audit results.") - auditCmd.PersistentFlags().StringVar(&auditOutputFormat, "output-format", "json", "Output format for results - json, yaml, or score.") + auditCmd.PersistentFlags().StringVarP(&auditOutputFormat, "format", "f", "json", "Output format for results - json, yaml, or score.") auditCmd.PersistentFlags().StringVar(&displayName, "display-name", "", "An optional identifier for the audit.") } diff --git a/cmd/polaris/dashboard.go b/cmd/polaris/dashboard.go index 4e6e3271..cd86471e 100644 --- a/cmd/polaris/dashboard.go +++ b/cmd/polaris/dashboard.go @@ -35,6 +35,7 @@ func init() { dashboardCmd.PersistentFlags().StringVar(&basePath, "base-path", "/", "Path on which the dashboard is served.") dashboardCmd.PersistentFlags().StringVar(&loadAuditFile, "load-audit-file", "", "Runs the dashboard with data saved from a past audit.") dashboardCmd.PersistentFlags().StringVar(&auditPath, "audit-path", "", "If specified, audits one or more YAML files instead of a cluster.") + dashboardCmd.PersistentFlags().StringVar(&displayName, "display-name", "", "An optional identifier for the audit.") } @@ -43,6 +44,10 @@ var dashboardCmd = &cobra.Command{ Short: "Runs the webserver for Polaris dashboard.", Long: `Runs the webserver for Polaris dashboard.`, Run: func(cmd *cobra.Command, args []string) { + if displayName != "" { + c.DisplayName = displayName + } + var auditDataPtr *validator.AuditData if loadAuditFile != "" { auditData := validator.ReadAuditFromFile(loadAuditFile) diff --git a/cmd/polaris/root.go b/cmd/polaris/root.go index a10d9da4..d0a0b194 100644 --- a/cmd/polaris/root.go +++ b/cmd/polaris/root.go @@ -29,6 +29,7 @@ var configPath string var disallowExemptions bool var logLevel string var auditPath string +var displayName string var ( version string diff --git a/cmd/polaris/webhook.go b/cmd/polaris/webhook.go index 9d8b94ac..f31f2a17 100644 --- a/cmd/polaris/webhook.go +++ b/cmd/polaris/webhook.go @@ -35,7 +35,7 @@ var disableWebhookConfigInstaller bool func init() { rootCmd.AddCommand(webhookCmd) - webhookCmd.PersistentFlags().IntVarP(&webhookPort, "port", "p", 8080, "Port for the dashboard webserver.") + webhookCmd.PersistentFlags().IntVarP(&webhookPort, "port", "p", 9876, "Port for the dashboard webserver.") webhookCmd.PersistentFlags().BoolVar(&disableWebhookConfigInstaller, "disable-webhook-config-installer", false, "disable the installer in the webhook server, so it won't install webhook configuration resources during bootstrapping.") } diff --git a/docs/usage.md b/docs/usage.md index 7e59be0f..48ba9653 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -95,8 +95,8 @@ 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 +helm repo add fairwinds-stable https://charts.fairwinds.com/stable +helm upgrade --install polaris fairwinds-stable/polaris --namespace polaris kubectl port-forward --namespace polaris svc/polaris-dashboard 8080:80 ``` @@ -108,7 +108,7 @@ or can be installed with [Homebrew](https://brew.sh/): ```bash brew tap reactiveops/tap brew install reactiveops/tap/polaris -polaris --dashboard --dashboard-port 8080 +polaris dashboard --port 8080 ``` ## Webhook @@ -119,8 +119,8 @@ kubectl apply -f https://github.com/fairwindsops/polaris/releases/latest/downloa ### Helm ```bash -helm repo add reactiveops-stable https://charts.reactiveops.com/stable -helm upgrade --install polaris reactiveops-stable/polaris --namespace polaris \ +helm repo add fairwindsops-stable https://charts.fairwinds.com/stable +helm upgrade --install polaris fairwindsops-stable/polaris --namespace polaris \ --set webhook.enable=true --set dashboard.enable=false ``` @@ -129,29 +129,29 @@ helm upgrade --install polaris reactiveops-stable/polaris --namespace polaris \ 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 +brew tap FairwindsOps/homebrew-tap +brew install FairwindsOps/homebrew-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 +polaris audit --format yaml > report.yaml +polaris audit --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/ +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/ \ +polaris audit --audit-path ./deploy/ \ --set-exit-code-on-error \ --set-exit-code-below-score 90 ``` @@ -161,50 +161,63 @@ For more on exit code meanings, see [exit-code docs](exit-codes.md). #### CLI Options ``` -# high-level flags --version +# top-level commands +audit + Runs a one-time audit. +dashboard + Runs the webserver for Polaris dashboard. +help + Prints help, if you give it a command then it will print help for that command. Same as -h +version Prints the version of Polaris --config string +webhook + Runs the webhook webserver + +# high-level flags +-c, --config string Location of Polaris configuration file --kubeconfig string +--disallow-exemptions + Disallow any exemptions from configuration file. +-h, --help + Help for Polaris (same as help command) +--kubeconfig string Path to a kubeconfig. Only required if out-of-cluster. --log-level string +--log-level string Logrus log level (default "info") --master string +--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 +--audit-path string + If specified, audits one or more YAML files instead of a cluster +--base-path string Path on which the dashboard is served (default "/") --dashboard-port int - Port for the dashboard webserver (default 8080) --display-name string +--display-name string An optional identifier for the audit +--load-audit-file string + Runs the dashboard with data saved from a past audit. +-p, --port int + Port for the dashboard webserver (default 8080) # audit flags --audit - Runs a one-time audit. --audit-path string +--audit-path string If specified, audits one or more YAML files instead of a cluster --output-file string +--display-name string + An optional identifier for the audit +--output-file string Destination file for audit results --output-format string +--output-format string Output format for results - json, yaml, or score (default "json") --output-url string +--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. +--set-exit-code-below-score int + Set an exit code of 4 when the score is below this threshold (1-100) +--set-exit-code-on-error + 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-webhook-config-installer disable the installer in the webhook server, so it won't install webhook configuration resources during bootstrapping +-p, --port int + Port for the webhook webserver (default 9876) ``` -