preflight

README

Jetstack Preflight

Preflight is a tool to automatically perform Kubernetes cluster configuration checks using Open Policy Agent (OPA).

Table of Contents

• Jetstack Preflight
  • Background
  • Preflight Application
  • Preflight Packages
  • Get Preflight
    • Download
    • Build
  • Use Preflight
    • Use Preflight Locally
    • Use Preflight Web UI
    • Use Preflight In-Cluster

Background

Preflight was originally designed to automate Jetstack's production readiness assessments. These are consulting sessions in which a Jetstack engineer inspects a customer's cluster to suggest improvements and identify configuration issues. The product of this assessment is a report which describes any problems and offers remediation advice.

While these assessments have provided a lot of value to many customers, with a complex system like Kubernetes it's hard to thoroughly check everything. Automating the checks allows them to be more comprehensive and much faster.

The automation also allows the checks to be run repeatedly, meaning they can be deployed in-cluster to provide continuous configuration checking. This enables new interesting use cases as policy compliance audits.

Preflight Application

The Preflight application uses data gatherers to collect required data in JSON format. Preflight then checks the gathered data against rules specified in Preflight packages and outputs rule violations with relevant information.

Preflight is designed to run both locally for one-off checking, and in-cluster to for continuous checking.

Preflight Packages

Policies for cluster configuration are encoded into Preflight packages. You can find some examples in ./preflight-packages.

Each package focuses on a different aspect of the cluster. For example, the gke_basic package provides rules for the configuration of a GKE cluster, and the pods package provides rules for the configuration of Kubernetes Pods.

A Preflight package consists of a Policy Manifest and a Rego package.

The Policy Manifest is a YAML file that specifies a package's rules. It gives descriptions of the rules and remediation advice, so the tool can display useful information when a rule doesn't pass.

Rego is OPA's high-level declarative language for specifying rules. Rego rules can be defined in multiples files grouped into logical Rego packages.

Anyone can create new Preflight packages to perform their own checks. The Preflight docs include a guide on how to write packages.

Get Preflight

Download

Preflight binaries and bundles, which include a binary and all the packages in this repo, can be downloaded from the releases page.

Build

You can compile Preflight by running make build. It will create the binary in builds/preflight.

Use Preflight

Create your preflight.yaml configuration file. There is full configuration documentation available, as well as several example files in ./examples.

Use Preflight Locally

By default Preflight looks for a configuration at ./preflight.yaml. Once this is set up, run a Preflight check like so:

preflight check

You can try the Pods example ./examples/pods.preflight.yaml without having to change a line, if your kubeconfig is located at ~/.kube/config and is pointing to a working cluster.

preflight check --config-file=./examples/pods.preflight.yaml

You will see a CLI formatted report if everything goes well. Also, you will get a JSON report in ./output.

Use Preflight Web UI

If you want to visualise the report in your browser, you can access the Preflight Web UI and load the JSON report. This is a static website. Your report is not being uploaded to any server. Everything happens in your browser.

You can give it a try without even running the tool, since we provide some report examples, gke.json, and pods.json, ready to be loaded into the Preflight Web UI.

Use Preflight In-Cluster

Preflight can be installed in-cluster to run continuous checks. See the Installation Manual: Preflight In-Cluster.