Skip to content

Commit dfaf7d0

Browse files
jetstack-botjetstack-bot
authored
Merge pull request #7 from j-fuentes/examples
Add documentation and examples
2 parents 0f62db2 + 5964959 commit dfaf7d0

File tree

25 files changed

+1205
-2
lines changed

25 files changed

+1205
-2
lines changed

‎Dockerfile‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# STAGE 1
2+
FROM golang:1.13.4 as builder
3+
4+
WORKDIR /go/github.com/jetstack/preflight
5+
6+
# Run a dependency resolve with just the go mod files present for
7+
# better caching
8+
COPY ./go.mod .
9+
COPY ./go.sum .
10+
11+
RUN go mod download
12+
13+
## Bring in everything else and build an amd64 image
14+
COPY . .
15+
RUN GOOS=linux GOARCH=amd64 go install .
16+
17+
# STAGE 2
18+
# Use a distroless nonroot base image for just our executable
19+
FROM gcr.io/distroless/base:nonroot
20+
COPY --from=builder /go/bin/preflight /bin/preflight
21+
ADD ./preflight-packages /preflight-packages
22+
ADD ./examples/pods.preflight.yaml /etc/preflight/preflight.yaml
23+
ENTRYPOINT ["preflight"]
24+
CMD ["check", "--config-file", "/etc/preflight/preflight.yaml"]

‎Makefile‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@ COMMIT:=$(shell git rev-list -1 HEAD)
55
DATE:=$(shell date -uR)
66
GOVERSION:=$(shell go version | awk '{print $$3 " " $$4}')
77

8+
IMAGE_NAME?=preflight:latest
9+
OVERLAY?=sample
10+
811
define LDFLAGS
912
-X "github.com/jetstack/preflight/cmd.PreflightVersion=$(VERSION)" \
1013
-X "github.com/jetstack/preflight/cmd.Platform=$(GOOS)/$(GOARCH)" \
@@ -33,3 +36,9 @@ lint: vet
3336

3437
clean:
3538
cd $(ROOT_DIR) && rm -rf ./builds
39+
40+
build-docker-image:
41+
docker build -t $(IMAGE_NAME) .
42+
43+
push-docker-image:
44+
docker push $(IMAGE_NAME)

‎README.md‎

Lines changed: 83 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,83 @@
1-
# preflight
2-
Automatically perform Kubernetes cluster configuration checks using Open Policy Agent (OPA)
1+
# Jetstack Preflight
2+
3+
Preflight is a tool to automatically perform Kubernetes cluster configuration checks using [Open Policy Agent (OPA)](https://www.openpolicyagent.org/).
4+
5+
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
6+
**Table of Contents**
7+
8+
- [Jetstack Preflight](#jetstack-preflight)
9+
- [Background](#background)
10+
- [Preflight Packages](#preflight-packages)
11+
- [Install Preflight](#install-preflight)
12+
- [Use Preflight locally](#use-preflight-locally)
13+
- [Get periodic reports by running Preflight as a CronJob](#get-periodic-reports-by-running-preflight-as-a-cronjob)
14+
15+
<!-- markdown-toc end -->
16+
17+
18+
## Background
19+
20+
Preflight was originally designed to automate Jetstack's
21+
production readiness assessments.
22+
These are consulting sessions in which a Jetstack engineer inspects a customer's
23+
cluster to suggest improvements and identify configuration issues.
24+
The product of this assessment is a report
25+
which describes any problems and offers remediation advice.
26+
27+
While these assessments have provided a lot of value to many customers,
28+
with a complex system like Kubernetes it's hard to thoroughly check everything.
29+
Automating the checks allows them to be more comprehensive and much faster.
30+
31+
The automation also allows the checks to be run repeatedly,
32+
meaning they can be deployed in-cluster to provide continuous configuration checking.
33+
34+
This enables new interesting use cases as policy compliance audits.
35+
36+
## Preflight Packages
37+
38+
Policies for cluster configuration are encoded into "Preflight Packages".
39+
40+
You can find some examples in [./preflight-packages](./preflight-packages) and you can also [write your own Preflight Packages](./docs/how_to_write_packages.md).
41+
42+
Preflight Packages are a very thin wrapper around OPA's policies. A package is made of [Rego](https://www.openpolicyagent.org/docs/latest/#rego) files (OPA's high-level declarative language) and a *Policy Manifest*.
43+
44+
The *Policy Manifest* is a YAML file intended to add metadata to the rules, so the tool can display useful information when a rule doesn't pass.
45+
46+
Since the logic in these packages is just Rego, you can add tests to your policies and use OPA's command line to run them (see [OPA Policy Testing tutorial](https://www.openpolicyagent.org/docs/latest/policy-testing/)).
47+
48+
Additionally, Preflight has a built-in linter for packages:
49+
50+
```
51+
preflight package lint <path to package>
52+
```
53+
54+
## Install Preflight
55+
56+
You can compile Preflight by running `make build`. It will create the binary in `builds/preflight`.
57+
58+
59+
## Use Preflight locally
60+
61+
Create your `preflight.yaml` configuration file (you can take inspiration from the ones in `./examples`).
62+
63+
Run Preflight (by default it looks for `./preflight.yaml`)
64+
65+
```
66+
preflight check
67+
```
68+
69+
You can try `./examples/pods.preflight.yaml` without having to change a line, if you have your *kubeconfig* (~/.kube/config) pointing to a working cluster.
70+
71+
```
72+
preflight check --config-file=./examples/pods.preflight.yaml
73+
```
74+
75+
You will see a CLI formatted report if everything goes well. Also, you will get a JSON report in `./output`.
76+
77+
If you want to visualice the report in your browser, you can access [preflight.jetstack.io](https://preflight.jetstack.io/) and load the JSON report. **This is a static website. Your report is not being uploaded to any server. Everything happens in your browser.**
78+
79+
You can give it a try without even running the tool, since we provide some report examples ([gke.json](./examples/reports/gke.json), [pods.json](./examples/reports/pods.json)) ready to be loaded in [preflight.jetstack.io](https://preflight.jetstack.io/).
80+
81+
## Get periodic reports by running Preflight as a CronJob
82+
83+
See [Run Preflight In-Cluster](./docs/preflight-in-cluster.md).

‎deployment/kubernetes/base/00-namespace.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
apiVersion: v1
2+
kind: Namespace
3+
metadata:
4+
name: preflight

‎deployment/kubernetes/base/01-rbac.yaml‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
apiVersion: policy/v1beta1
2+
kind: PodSecurityPolicy
3+
metadata:
4+
name: jetstack-preflight
5+
annotations:
6+
seccomp.security.alpha.kubernetes.io/allowedProfileNames: 'docker/default,runtime/default'
7+
apparmor.security.beta.kubernetes.io/allowedProfileNames: 'runtime/default'
8+
seccomp.security.alpha.kubernetes.io/defaultProfileName: 'runtime/default'
9+
apparmor.security.beta.kubernetes.io/defaultProfileName: 'runtime/default'
10+
spec:
11+
privileged: false
12+
# Required to prevent escalations to root.
13+
allowPrivilegeEscalation: false
14+
# This is redundant with non-root + disallow privilege escalation,
15+
# but we can provide it for defense in depth.
16+
requiredDropCapabilities:
17+
- ALL
18+
# Allow core volume types.
19+
volumes:
20+
- 'configMap'
21+
- 'secret'
22+
hostNetwork: false
23+
hostIPC: false
24+
hostPID: false
25+
runAsUser:
26+
# Require the container to run without root privileges.
27+
rule: 'MustRunAsNonRoot'
28+
seLinux:
29+
# This policy assumes the nodes are using AppArmor rather than SELinux.
30+
rule: 'RunAsAny'
31+
supplementalGroups:
32+
rule: 'MustRunAs'
33+
ranges:
34+
# Forbid adding the root group.
35+
- min: 1
36+
max: 65535
37+
fsGroup:
38+
rule: 'MustRunAs'
39+
ranges:
40+
# Forbid adding the root group.
41+
- min: 1
42+
max: 65535
43+
readOnlyRootFilesystem: true
44+
---
45+
apiVersion: v1
46+
kind: ServiceAccount
47+
metadata:
48+
namespace: preflight
49+
name: preflight
50+
---
51+
apiVersion: rbac.authorization.k8s.io/v1
52+
kind: ClusterRole
53+
metadata:
54+
name: list-pods-global
55+
rules:
56+
- apiGroups: [""]
57+
resources: ["pods"]
58+
verbs: ["list"]
59+
- apiGroups: ['policy']
60+
resources: ['podsecuritypolicies']
61+
verbs: ['use']
62+
resourceNames:
63+
- jetstack-preflight
64+
---
65+
apiVersion: rbac.authorization.k8s.io/v1
66+
kind: ClusterRoleBinding
67+
metadata:
68+
name: preflight-list-pods-global
69+
namespace: preflight
70+
subjects:
71+
- kind: ServiceAccount
72+
name: preflight
73+
namespace: preflight
74+
roleRef:
75+
kind: ClusterRole
76+
name: list-pods-global
77+
apiGroup: rbac.authorization.k8s.io

‎deployment/kubernetes/base/02-cronjob.yaml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
apiVersion: batch/v1beta1
2+
kind: CronJob
3+
metadata:
4+
name: preflight
5+
namespace: preflight
6+
labels:
7+
app.kubernetes.io/name: preflight
8+
app.kubernetes.io/version: master
9+
app.kubernetes.io/part-of: jetstack-subscription
10+
spec:
11+
schedule: "0 */1 * * *"
12+
concurrencyPolicy: Forbid
13+
jobTemplate:
14+
metadata:
15+
labels:
16+
app.kubernetes.io/name: preflight
17+
app.kubernetes.io/version: master
18+
spec:
19+
template:
20+
spec:
21+
serviceAccountName: preflight
22+
restartPolicy: Never
23+
containers:
24+
- name: preflight
25+
image: jetstack/preflight:latest
26+
imagePullPolicy: Always
27+
resources:
28+
requests:
29+
cpu: 100m
30+
memory: 50Mi
31+
limits:
32+
cpu: 100m
33+
memory: 50Mi
34+
volumeMounts:
35+
- name: config
36+
mountPath: /etc/preflight
37+
readOnly: true
38+
- name: gcs-credentials
39+
mountPath: /var/run/secrets/preflight
40+
readOnly: true
41+
volumes:
42+
- name: config
43+
configMap:
44+
name: preflight-config
45+
- name: gcs-credentials
46+
secret:
47+
secretName: gcs-credentials

‎deployment/kubernetes/base/kustomization.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
resources:
2+
- 00-namespace.yaml
3+
- 01-rbac.yaml
4+
- 02-cronjob.yaml

‎deployment/kubernetes/overlays/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
credentials.json

‎deployment/kubernetes/overlays/sample/custom-image.yaml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Change the CronJob to use a custom image
2+
apiVersion: batch/v1beta1
3+
kind: CronJob
4+
metadata:
5+
name: preflight
6+
spec:
7+
jobTemplate:
8+
spec:
9+
template:
10+
spec:
11+
containers:
12+
- name: preflight
13+
# You can change this to use an image of your choice.
14+
image: eu.gcr.io/jetstack-preflight/preflight-cli:latest

‎deployment/kubernetes/overlays/sample/kustomization.yaml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
bases:
2+
- ../../base/
3+
configMapGenerator:
4+
- name: preflight-config
5+
namespace: preflight
6+
files:
7+
- preflight.yaml
8+
secretGenerator:
9+
- name: gcs-credentials
10+
namespace: preflight
11+
files:
12+
- credentials.json
13+
patchesStrategicMerge:
14+
- custom-image.yaml

0 commit comments

Comments
 (0)