adding resource and security documentation, updating webhook document…

…ation
FairwindsOps · Apr 19, 2019 · 240c223 · 240c223
1 parent 7662068
commit 240c223
Show file tree

Hide file tree

Showing 4 changed files with 72 additions and 16 deletions.
diff --git a/README.md b/README.md
@@ -39,7 +39,7 @@ If you'd prefer to run Fairwinds locally, binary releases are available on the [
 
 ## Webhook
 
-The Fairwinds Webhook can run the same checks as the dashboard, but can be deployed and configured separately. When running, the webhook will validate any new or updated deployments in the cluster, and reject any that fail a check with an `error` severity.
+Fairwinds 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 Fairwinds, 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 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.
 

diff --git a/docs/resources.md b/docs/resources.md
@@ -0,0 +1,43 @@
+# Resources
+
+Fairwinds supports a number of checks related to CPU and Memory requests and limits.
+
+## Presence Checks
+
+To simplify ensure that these values have been set, the following attributes are available:
+
+key | default | description
+----|---------|------------
+`resources.cpuRequestsMissing` | `warning` | Fails when `resources.requests.cpu` attribute is not configured.
+`resources.memoryRequestsMissing` | `warning` | Fails when `resources.requests.memory` attribute is not configured.
+`resources.cpuLimitsMissing` | `warning` | Fails when `resources.limits.cpu` attribute is not configured.
+`resources.memoryLimitsMissing` | `warning` | Fails when `resources.limits.memory` attribute is not configured.
+
+## Range Checks
+
+Fairwinds can also verify that those values fall within a certain range. These checks are not enabled by default, and as such do not have default values. The `cpuRequestRanges`, `cpuLimitRanges`, `memoryRequestRanges`, and `memoryLimitRanges` all support the following attributes:
+
+key | description
+----|------------
+`warning.below` | Warn when resource is below this value (or not defined)
+`warning.above` | Warn when resource is above this value
+`error.below` | Error when resource is below this value (or not defined)
+`error.above` | Error when resource is above this value
+
+## Background
+
+Configuring resource requests and limits for containers running in Kubernetes is an important best practice to follow. Setting appropriate resource requests will ensure that all your applications have sufficient compute resources. Setting appropriate resource limits will ensure that your applications do not consume too many resources.
+
+Having these values appropriately configured ensures that:
+
+* Cluster autoscaling can function as intended. New nodes are scheduled once pods are unable to be scheduled on an existing node due to insufficient resources. This will not happen if resource requests are not configured.
+
+* Each container has sufficient access to compute resources. Without resource requests, a pod may be scheduled on a node that is already overutilized. Without resource limits, a single poorly behaving pod could utilize the majority of resources on a node, significantly impacting the performance of other pods on the same node.
+
+## Further Reading
+
+- [Kubernetes Docs: Managing Compute Resources for Containers](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/)
+
+- [Kubernetes best practices: Resource requests and limits](https://cloud.google.com/blog/products/gcp/kubernetes-best-practices-resource-requests-and-limits)
+
+- [Vertical Pod Autoscaler (can automatically set resource requests and limits)](https://github.com/kubernetes/autoscaler/tree/master/vertical-pod-autoscaler)
diff --git a/docs/security-capabilities.md b/docs/security-capabilities.md
@@ -0,0 +1,22 @@
+# Security Capabilities
+
+Fairwinds supports a number of checks 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: 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)
diff --git a/docs/security.md b/docs/security.md
@@ -13,24 +13,15 @@ key | default | description
 
 ## 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.
+Additional validations are available to ensure pods are running with a limited set of capabilities. More information is available in our [Security Capabilities documentation](security-capabilities.md).
 
 ## Background
 
-TODO
+Securing workloads in Kubernetes is an important part of overall cluster security. The overall goal should be to ensure that containers are running with as minimal privileges as possible. This includes avoiding privilege escalation, not running containers with a root user, and using read only file systems wherever possible.
+
+Much of this configuration can be found in the `securityContext` attribute for both Kubernetes pods and containers. Where configuration is available at both a pod and container level, Fairwinds validates both.
 
 ## 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)
+- [KubeCon 2018 Keynote: Running with Scissors](https://www.youtube.com/watch?v=ltrV-Qmh3oY)
+- [Kubernetes Security Book](https://kubernetes-security.info/)