github/polaris
1
0
Fork 0
mirror of https://github.com/FairwindsOps/polaris.git synced 2026-08-23 22:26:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

adding a lot of documentation

Browse Source
This commit is contained in:
Rob Scott
2019-04-18 15:24:13 -04:00
parent 928ae30bc4
commit 7662068c45
7 changed files with 126 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+19 -14
View File
@@ -1,13 +1,3 @@
<<<<<<< HEAD
## Build locally
This package is best built using [packr](https://github.com/gobuffalo/packr), which provides
a thin wrapper around the go compiler in order to include static HTML/CSS/JS assets.
```bash
git clone https://github.com/reactiveops/fairwinds $GOPATH/src/github.com/reactiveops/fairwinds
go get -u github.com/gobuffalo/packr/v2/packr2
packr2 build -a -o fairwinds *.go
./fairwinds -h
=======
<p align="center">
<img src="/public/images/logo.png" alt="Fairwinds Logo" />
</p>
@@ -27,13 +17,12 @@ To deploy Fairwinds with kubectl:
```
kubectl apply -f deploy/all.yaml
>>>>>>> first run at readme updates
```
Fairwinds can also be deployed with Helm:
```
helm upgrade --install fairwinds deploy/helm/fairwinds/ --namespace fairwinds --recreate-pods
helm upgrade --install fairwinds deploy/helm/fairwinds/ --namespace fairwinds
```
### Viewing the Dashboard
@@ -54,7 +43,6 @@ The Fairwinds Webhook can run the same checks as the dashboard, but can be deplo
Unfortunately we have not found a way to disply 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 Fairwinds dashboard or the Fairwinds webhook logs.
## CLI Options
* `config`: Specify a location for the Fairwinds config
@@ -63,4 +51,21 @@ Unfortunately we have not found a way to disply warnings as part of `kubectl` ou
* `webhook`: Runs the webhook webserver.
* `webhook-port`: 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
* `kubeconfig`: Paths to a kubeconfig. Only required if out-of-cluster.
* `kubeconfig`: Paths to a kubeconfig. Only required if out-of-cluster.
## Configuration
Fairwinds 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](https://github.com/reactiveops/fairwinds/blob/master/config.yaml) contains a number of those checks. This repository also includes a sample [full configuration file](https://github.com/reactiveops/fairwinds/blob/master/config-full.yaml) that enables all available 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.
Fairwinds validation checks fall into several different categories:
- [Health Checks](docs/health-checks.md)
- [Images](docs/images.md)
- [Networking](docs/networking.md)
- [Resources](docs/resources.md)
- [Security](docs/security.md)
## License
Apache License 2.0
config-full.yaml
+1 -1
View File
@@ -57,7 +57,7 @@ security:
capabilities:
error:
ifAnyAdded:
- CAP_SYS_ADMIN
- SYS_ADMIN
- ALL
ifAnyNotDropped:
- ALL
config.yaml
+6 -7
View File
@@ -9,16 +9,15 @@ healthChecks:
readinessProbeMissing: warning
livenessProbeMissing: warning
networking:
hostAliasSet: error
hostIPCSet: error
hostNetworkSet: error
hostPIDSet: error
hostPortSet: error
hostNetworkSet: warning
hostPortSet: warning
security:
runAsRootAllowed: warning
runAsPrivileged: error
hostIPCSet: error
hostPIDSet: error
notReadOnlyRootFileSystem: warning
privilegeEscalationAllowed: error
runAsRootAllowed: warning
runAsPrivileged: error
capabilities:
error:
ifAnyAdded:
docs/health-checks.md
+22
View File
@@ -0,0 +1,22 @@
# Health Checks
Fairwinds supports validating the presence of readiness and liveness probes in pods.
key | default | description
----|---------|------------
`healthChecks.readinessProbeMissing` | `warning` | Fails when a readiness probe is not configured for a pod.
`healthChecks.livenessProbeMissing` | `warning` | Fails when a liveness probe is not configured for a pod.
## Background
Readiness and liveness probes can help maintain the health of applications running inside Kubernetes. By default, Kubernetes only knows whether or not a process is running, not if it's healthy. Properly configured readiness and liveness probes will also be able to ensure the health of an application.
Readiness probes are designed to ensure that an application has reached a "ready" state. In many cases there is a period of time between when a webserver process starts and when it is ready to receive traffic. A readiness probe can ensure the traffic is not sent to a pod until it is actually ready to receive traffic.
Liveness probes are designed to ensure that an application stays in a healthy state. When a liveness probe fails, the pod will be restarted.
## Further Reading
- [Kubernetes Docs: Configure Livenss and Readiness Probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/)
- [Utilizing Kubernetes Liveness and Readiness Probes to Automatically Recover From Failure](https://medium.com/spire-labs/utilizing-kubernetes-liveness-and-readiness-probes-to-automatically-recover-from-failure-2fe0314f2b2e)
- [Kubernetes Liveness and Readiness Probes: How to Avoid Shooting Yourself in the Foot](https://blog.colinbreck.com/kubernetes-liveness-and-readiness-probes-how-to-avoid-shooting-yourself-in-the-foot/)
docs/images.md
+20
View File
@@ -0,0 +1,20 @@
# Images
Fairwinds supports a number of checks related to the image specified by pods.
key | default | description
----|---------|------------
`images.tagNotSpecified` | `error` | Fails when an image tag is either not specified or `latest`.
`images.pullPolicyNotAlways` | `ignore` | Fails when an image pull policy is not `always`.
## Background
Docker's `latest` tag is applied by default to images where a tag hasn't been specified. Not specifying a specific version of an image can lead to a wide variety of problems. The underlying image could include unexpected breaking changes that break your application whenever the latest image is pulled. Reusing the same tag for multiple versions of an image can lead to different nodes in the same cluster having different versions of an image, even if the tag is identical.
Related to that, relying on cached versions of a Docker image can become a security vulnerability. By default, an image will be pulled if it isn't already cached on the node attempting to run it. This can result in variations in images that are running per node, or potentially provide a way to gain access to an image without having direct access to the ImagePullSecret. With that in mind, it's often better to ensure the a pod has `pullPolicy: Always` specified, so images are always pulled directly from their source. This is not a check enabled by default with Fairwinds as organizations may not wish to add the overhead involved with pulling images for each pod.
## Further Reading
- [What's Wrong With The Docker :latest Tag?](https://vsupalov.com/docker-latest-tag/)
- [Kubernetes’ AlwaysPullImages Admission Control — the Importance, Implementation, and Security Vulnerability in its Absence](https://medium.com/@trstringer/kubernetes-alwayspullimages-admission-control-the-importance-implementation-and-security-d83ff3815840)
docs/networking.md
+22
View File
@@ -0,0 +1,22 @@
# Networking
Fairwinds supports a number of checks related to pod networking.
key | default | description
----|---------|------------
`networking.hostNetworkSet` | `warning` | Fails when `hostNetwork` attribute is configured.
`networking.hostPortSet` | `warning` | Fails when `hostPort` attribute is configured.
## Background
Although Kubernetes allows you to deploy a pod with access to the host network namespace, it's rarely a good idea. A pod running with the `hostNetwork` attribute enabled will have access to the loopback device, services listening on localhost, and could be used to snoop on network activity of other pods on the same node. There are certain examples where setting `hostNetwork` to true is required, such as deploying a networking plugin like Flannel.
Setting the `hostPort` attribute on a container will ensure that it is accessible on that specific port on each node it is deployed to. Unfortunately when this is specified, it limits where a pod can actually be scheduled in a cluster.
## Further Reading
- [Kubernetes Docs: Configuration Best Practices](https://kubernetes.io/docs/concepts/configuration/overview/#services)
- [Accessing Kubernetes Pods from Outside of the Cluster](http://alesnosek.com/blog/2017/02/14/accessing-kubernetes-pods-from-outside-of-the-cluster/)
docs/security.md
+36
View File
@@ -0,0 +1,36 @@
# Security
Fairwinds supports a number of checks related to security.
key | default | description
----|---------|------------
`security.hostIPCSet` | `error` | Fails when `hostIPC` attribute is configured.
`security.hostPIDSet` | `error` | Fails when `hostPID` attribute is configured.
`security.notReadOnlyRootFileSystem` | `warning` | Fails when `securityContext.readOnlyRootFilesystem` is not true.
`security.privilegeEscalationAllowed` | `error` | Fails when `securityContext.allowPrivilegeEscalation` is true.
`security.runAsRootAllowed` | `error` | Fails when `securityContext.runAsNonRoot` is not true.
`security.runAsPrivileged` | `error` | Fails when `securityContext.privileged` is true.
## Security Capabilities
Additional validations are available to ensure pods are running with a limited set of capabilities. Under `security.capabilities`, there are `error` and `warning` sections indicating the severity of failures for the following checks.
key | default | description
----|---------|------------
`security.capabilities.error.ifAnyAdded` | [`SYS_ADMIN`, `NET_ADMIN`, `ALL`] | Fails when any of the listed capabilities have been added.
`security.capabilities.error.ifAnyAddedBeyond` | `nil` | Fails when any capabilities have been added beyond the specified list.
`security.capabilities.error.ifAnyNotDropped` | `nil` | Fails when any of the listed capabilities have not been dropped.
`security.capabilities.warning.ifAnyAdded` | `nil` | Fails when any of the listed capabilities have been added.
`security.capabilities.warning.ifAnyAddedBeyond` | [`CHOWN`, `DAC_OVERRIDE`, `FSETID`, `FOWNER`, `MKNOD`, `NET_RAW`, `SETGID`, `SETUID`, `SETFCAP`, `SETPCAP`, `NET_BIND_SERVICE`, `SYS_CHROOT`, `KILL`,`AUDIT_WRITE`] | Fails when any capabilities have been added beyond the specified list.
`security.capabilities.warning.ifAnyNotDropped` | `nil` | Fails when any of the listed capabilities have not been dropped.
## Background
TODO
## Further Reading
- [Kubernetes Docs: Configure a Security Context for a Pod or Container](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/)
- [Kubernetes Docs: Set capabilities for a Container](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-capabilities-for-a-container)
- [Linux Programmer's Manual: Capabilities](http://man7.org/linux/man-pages/man7/capabilities.7.html)