Better support for CI/CD use case (#127)

add score to output

add output-format option

update README with more use cases

change YAML marshal strategy

fix webhook install instructions

README.md

@@ -21,6 +21,14 @@ Polaris helps keep your cluster healthy. It runs a variety of checks to ensure t
 
 **Want to learn more?** ReactiveOps 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@reactiveops.com`
 
+## Quickstart
+
+```
+kubectl apply -f https://raw.githubusercontent.com/reactiveops/polaris/master/deploy/dashboard.yaml
+kubectl port-forward --namespace polaris svc/polaris-dashboard 8080:80
+```
+With the port forwarding in place, you can open http://localhost:8080 in your browser to view the dashboard.
+
 ## 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.
@@ -31,63 +39,84 @@ The Polaris dashboard is a way to get a simple visual overview of the current st
 
 Our default standards in Polaris are rather high, so don’t be surprised if your score is lower than you might expect. A key goal for Polaris was to set a high standard and aim for great configuration by default. If the defaults we’ve included are too strict, it’s easy to adjust the configuration as part of the deployment configuration to better suit your workloads.
 
-### Deploying
-
-To deploy Polaris with kubectl:
-
-```
-kubectl apply -f https://raw.githubusercontent.com/reactiveops/polaris/master/deploy/dashboard.yaml
-```
-
-Polaris can also be deployed with Helm:
-
-```
-helm upgrade --install polaris deploy/helm/polaris/ --namespace polaris
-```
-
-### Viewing the Dashboard
-
-Once the dashboard is deployed, it can be viewed by using kubectl port-forward:
-
-```
-kubectl port-forward --namespace polaris svc/polaris-dashboard 8080:80
-```
-
-With the port forwarding in place, you can open http://localhost:8080 in your browser to view the dashboard.
-
-### Using a Binary Release
-
-If you'd prefer to run Polaris locally, binary releases are available on the [releases page](https://github.com/reactiveops/polaris/releases) or can be installed with [Homebrew](https://brew.sh/):
-
-```
-brew tap reactiveops/tap
-brew install reactiveops/tap/polaris
-```
-
-When running as a binary, Polaris will use your local kubeconfig to connect to a cluster. There are a variety of options available, but the most common usage will likely be to view the dashboard:
-
-```
-polaris --dashboard
-```
-
 ## 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 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.*
 
 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.
 
-### Deploying
-
-The Polaris webhook can be deployed with kubectl:
+## 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.
 
+### kubectl
+#### Dashboard
+```
+kubectl apply -f https://raw.githubusercontent.com/reactiveops/polaris/master/deploy/dashboard.yaml
+kubectl port-forward --namespace polaris svc/polaris-dashboard 8080:80
+```
+#### Webhook
 ```
 kubectl apply -f https://raw.githubusercontent.com/reactiveops/polaris/master/deploy/webhook.yaml
 ```
 
-Alternatively, the webhook can be enabled with Helm by setting `webhook.enable` to true:
+### Helm
+#### Dashboard
+```
+git clone https://github.com/reactiveops/polaris && cd polaris
+helm upgrade --install polaris deploy/helm/polaris/ --namespace polaris
+kubectl port-forward --namespace polaris svc/polaris-dashboard 8080:80
+```
+#### Webhook
+```
+git clone https://github.com/reactiveops/polaris && cd polaris
+helm upgrade --install polaris deploy/helm/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/reactiveops/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.
 
 ```
-helm upgrade --install polaris deploy/helm/polaris/ --namespace polaris --set webhook.enable=true
+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 whenever the Polaris score drops below 90%:
+```bash
+score=`polaris --audit --audit-path ./deploy/ --output-format score`
+if [[ $score -lt 90 ]]; then
+  exit 1
+else
+  exit 0
+fi
 ```
 
 ## Configuration

main.go

@@ -29,7 +29,6 @@ import (
 	"github.com/reactiveops/polaris/pkg/validator"
 	fwebhook "github.com/reactiveops/polaris/pkg/webhook"
 	"github.com/sirupsen/logrus"
-	"gopkg.in/yaml.v2"
 	appsv1 "k8s.io/api/apps/v1"
 	extensionsv1beta1 "k8s.io/api/extensions/v1beta1"
 	apitypes "k8s.io/apimachinery/pkg/types"
@@ -38,6 +37,7 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/manager"
 	"sigs.k8s.io/controller-runtime/pkg/runtime/signals"
 	"sigs.k8s.io/controller-runtime/pkg/webhook"
+	"sigs.k8s.io/yaml"
 )
 
 const (
@@ -55,6 +55,7 @@ func main() {
 	webhookPort := flag.Int("webhook-port", 9876, "Port for the webhook webserver")
 	auditOutputURL := flag.String("output-url", "", "Destination URL to send audit results")
 	auditOutputFile := flag.String("output-file", "", "Destination file for audit results")
+	auditOutputFormat := flag.String("output-format", "json", "Output format for results - json, yaml, or score")
 	configPath := flag.String("config", "", "Location of Polaris configuration file")
 	logLevel := flag.String("log-level", logrus.InfoLevel.String(), "Logrus log level")
 	version := flag.Bool("version", false, "Prints the version of Polaris")
@@ -90,7 +91,7 @@ func main() {
 	} else if *dashboard {
 		startDashboardServer(c, *auditPath, *dashboardPort, *dashboardBasePath)
 	} else if *audit {
-		runAudit(c, *auditPath, *auditOutputFile, *auditOutputURL)
+		runAudit(c, *auditPath, *auditOutputFile, *auditOutputURL, *auditOutputFormat)
 	}
 }
 
@@ -175,7 +176,7 @@ func startWebhookServer(c conf.Configuration, disableWebhookConfigInstaller bool
 	}
 }
 
-func runAudit(c conf.Configuration, auditPath string, outputFile string, outputURL string) {
+func runAudit(c conf.Configuration, auditPath string, outputFile string, outputURL string, outputFormat string) {
 	k, err := kube.CreateResourceProvider(auditPath)
 	if err != nil {
 		logrus.Errorf("Error fetching Kubernetes resources %v", err)
@@ -187,33 +188,39 @@ func runAudit(c conf.Configuration, auditPath string, outputFile string, outputU
 		panic(err)
 	}
 
-	if outputURL == "" && outputFile == "" {
-		yamlBytes, err := yaml.Marshal(auditData)
-
-		if err != nil {
-			logrus.Errorf("Error marshalling YAML: %v", err)
-			os.Exit(1)
+	var outputBytes []byte
+	if outputFormat == "score" {
+		outputBytes = []byte(fmt.Sprint(auditData.ClusterSummary.Score))
+	} else if outputFormat == "yaml" {
+		jsonBytes, err := json.Marshal(auditData)
+		if err == nil {
+			outputBytes, err = yaml.JSONToYAML(jsonBytes)
 		}
-
-		os.Stdout.Write(yamlBytes)
-
 	} else {
-		jsonData, err := json.MarshalIndent(auditData, "", "  ")
-
-		if err != nil {
-			logrus.Errorf("Error marshalling JSON: %v", err)
-			os.Exit(1)
-		}
-
+		outputBytes, err = json.MarshalIndent(auditData, "", "  ")
+	}
+	if err != nil {
+		logrus.Errorf("Error marshalling audit: %v", err)
+		os.Exit(1)
+	}
+	if outputURL == "" && outputFile == "" {
+		os.Stdout.Write(outputBytes)
+	} else {
 		if outputURL != "" {
-			req, err := http.NewRequest("POST", outputURL, bytes.NewBuffer(jsonData))
+			req, err := http.NewRequest("POST", outputURL, bytes.NewBuffer(outputBytes))
 
 			if err != nil {
 				logrus.Errorf("Error building request for output: %v", err)
 				os.Exit(1)
 			}
 
-			req.Header.Set("Content-Type", "application/json")
+			if outputFormat == "json" {
+				req.Header.Set("Content-Type", "application/json")
+			} else if outputFormat == "yaml" {
+				req.Header.Set("Content-Type", "application/x-yaml")
+			} else {
+				req.Header.Set("Content-Type", "text/plain")
+			}
 			client := &http.Client{}
 			resp, err := client.Do(req)
 
@@ -235,7 +242,7 @@ func runAudit(c conf.Configuration, auditPath string, outputFile string, outputU
 		}
 
 		if outputFile != "" {
-			err := ioutil.WriteFile(outputFile, []byte(jsonData), 0644)
+			err := ioutil.WriteFile(outputFile, []byte(outputBytes), 0644)
 			if err != nil {
 				logrus.Errorf("Error writing output to file: %v", err)
 				os.Exit(1)

pkg/dashboard/dashboard.go

@@ -92,7 +92,6 @@ func GetBaseTemplate(name string) (*template.Template, error) {
 		"getWeatherIcon":  getWeatherIcon,
 		"getWeatherText":  getWeatherText,
 		"getGrade":        getGrade,
-		"getScore":        getScore,
 		"getIcon":         getIcon,
 		"getCategoryLink": getCategoryLink,
 		"getCategoryInfo": getCategoryInfo,

pkg/dashboard/helpers.go

@@ -29,7 +29,7 @@ func getSuccessWidth(counts validator.CountSummary, fullWidth int) uint {
 }
 
 func getGrade(counts validator.CountSummary) string {
-	score := getScore(counts)
+	score := counts.GetScore()
 	if score >= 97 {
 		return "A+"
 	} else if score >= 93 {
@@ -59,13 +59,8 @@ func getGrade(counts validator.CountSummary) string {
 	}
 }
 
-func getScore(counts validator.CountSummary) uint {
-	total := (counts.Successes * 2) + counts.Warnings + (counts.Errors * 2)
-	return uint((float64(counts.Successes*2) / float64(total)) * 100)
-}
-
 func getWeatherIcon(counts validator.CountSummary) string {
-	score := getScore(counts)
+	score := counts.GetScore()
 	if score >= 90 {
 		return "fa-sun"
 	} else if score >= 80 {
@@ -80,7 +75,7 @@ func getWeatherIcon(counts validator.CountSummary) string {
 }
 
 func getWeatherText(counts validator.CountSummary) string {
-	score := getScore(counts)
+	score := counts.GetScore()
 	if score >= 90 {
 		return "Smooth sailing"
 	} else if score >= 80 {

pkg/dashboard/templates/dashboard.gohtml

@@ -7,7 +7,7 @@
           <div class="weather"><i class="fas {{ getWeatherIcon .AuditData.ClusterSummary.Results.Totals }}"></i></div>
           <div class="sailing">{{ getWeatherText .AuditData.ClusterSummary.Results.Totals }}</div>
           <div class="scores"><span>Grade: </span><strong>{{ getGrade .AuditData.ClusterSummary.Results.Totals }}</strong></div>
-          <div class="scores"><span>Score: </span><strong>{{ getScore .AuditData.ClusterSummary.Results.Totals }}%</strong></div>
+          <div class="scores"><span>Score: </span><strong>{{ .AuditData.ClusterSummary.Results.Totals.GetScore }}%</strong></div>
         </div>
       </div>
       <div class="graph">
@@ -60,7 +60,7 @@
               </div>
             </div>
           </div>
-          <div class="name"><span class="caret-expander"></span>{{ $category }}<span class="category-score">Score: <strong>{{ getScore $summary }}%</strong></span></div>
+          <div class="name"><span class="caret-expander"></span>{{ $category }}<span class="category-score">Score: <strong>{{ $summary.GetScore }}%</strong></span></div>
             <div class="result-messages expandable-content">
             <p class="category-info">{{ getCategoryInfo $category }} Refer to the <a href="details/{{ getCategoryLink $category }}">Polaris documentation about {{ $category }}</a> for more information.</p>
           </div>

pkg/validator/fullaudit.go

@@ -7,7 +7,7 @@ import (
 
 const (
 	// PolarisOutputVersion is the version of the current output structure
-	PolarisOutputVersion = "0.0"
+	PolarisOutputVersion = "0.1"
 )
 
 // ClusterSummary contains Polaris results as well as some high-level stats
@@ -18,6 +18,7 @@ type ClusterSummary struct {
 	Pods        int
 	Namespaces  int
 	Deployments int
+	Score       uint
 }
 
 // AuditData contains all the data from a full Polaris audit
@@ -58,6 +59,7 @@ func RunAudit(config conf.Configuration, kubeResources *kube.ResourceProvider) (
 			Namespaces:  len(kubeResources.Namespaces),
 			Deployments: len(kubeResources.Deployments),
 			Results:     clusterResults,
+			Score:       clusterResults.Totals.GetScore(),
 		},
 		NamespacedResults: nsResults,
 	}

pkg/validator/types.go

@@ -45,6 +45,12 @@ type CountSummary struct {
 	Errors    uint
 }
 
+// GetScore returns an overall score in [0, 100] for the CountSummary
+func (cs *CountSummary) GetScore() uint {
+	total := (cs.Successes * 2) + cs.Warnings + (cs.Errors * 2)
+	return uint((float64(cs.Successes*2) / float64(total)) * 100)
+}
+
 func (cs *CountSummary) appendCounts(toAppend CountSummary) {
 	cs.Errors += toAppend.Errors
 	cs.Warnings += toAppend.Warnings