Merge pull request #2884 from weaveworks/issues/2794-kube-evict-docs

Add pod resources and eviction to weave-kube doc

site/kube-addon.md

@@ -9,6 +9,8 @@ The following topics are discussed:
 * [Installation](#install)
  * [Upgrading Kubernetes to version 1.6](#kube-1.6-upgrade)
  * [Upgrading the Daemon Sets](#daemon-sets)
+ * [CPU and Memory Requirements](#resources)
+ * [Pod Eviction](#eviction)
 * [Network Policy Controller](#npc)
  * [Troubleshooting Blocked Connections](#blocked-connections)
  * [Changing Configuration Options](#configuration-options)
@@ -35,7 +37,8 @@ After a few seconds, a Weave Net pod should be running on each
 Node and any further pods you create will be automatically attached to the Weave
 network.
 
-**Note:** This command requires Kubernetes 1.4 or later.
+**Note:** This command requires Kubernetes 1.4 or later, and we
+recommend your master node has at least two CPU cores.
 
 > CNI, the [_Container Network Interface_](https://github.com/containernetworking/cni),
 > is a proposed standard for configuring network interfaces for Linux
@@ -92,6 +95,64 @@ and so you will need to perform the procedure manually:
   lose track of IP address range ownership, possibly leading to
   duplicate IP addresses if you then start a new copy of Weave Net.
 
+## <a name="resources"></a>CPU and Memory Requirements
+
+Kubernetes manages
+[resources](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/)
+on each node, and only schedules pods to run on nodes that have enough
+free resources.
+
+The components of a typical Kubernetes installation (with the master
+node running etcd, scheduler, api-server, etc.) take up about 95% of a
+CPU, which leaves little room to run anything else. For all of Weave
+Net's features to work, it must run on every node, including the
+master.
+
+The best way to resolve this issue is to use machines with at least
+two CPU cores. However if you are installing Kubernetes and Weave Net
+for the first time, you may not be aware of this requirement. For this
+reason, Weave Net launches as a DaemonSet with a specification that
+reserves at least 1% CPU for each container. This enables Weave Net to
+start up seamlessly on a single-CPU node.
+
+Depending on the workload, Weave Net may need more than 1% of the
+CPU. The percentage set in the DaemonSet is the minimum and not a
+limit. This minimum setting allows Weave Net to take advantage of
+available CPU and "burst" above that limit if it needs to.
+
+## <a name="eviction"></a>Pod Eviction
+
+If a node runs out of CPU, memory or disk, Kubernetes may [decide to
+evict](https://kubernetes.io/docs/concepts/cluster-administration/out-of-resource/)
+one or more pods. It may choose to evict the Weave Net pod, which will
+disrupt pod network operations.
+
+You can reduce the chance of eviction by changing the DaemonSet to
+have a much bigger request, and a limit of the same value.
+
+This causes Kubernetes to apply a ["guaranteed" rather than a
+"burstable" policy](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/resource-qos.md).
+However a similar request for disk space can not
+be made, and so please be aware of this issue and monitor your
+resources to ensure that they stay below 100%.
+
+You can see when pods have been evicted via the `kubectl get events` command
+
+```
+LASTSEEN   COUNT     NAME          KIND    TYPE      REASON     SOURCE            MESSAGE
+1m         1         mypod-09vkd   Pod     Warning   Evicted    kubelet, node-1   The node was low on resource: memory.
+```
+
+or `kubectl get pods`
+
+```
+NAME                READY     STATUS    RESTARTS   AGE       IP          NODE
+mypod-09vkd         0/1       Evicted   0          1h        <none>      node-1
+```
+
+If you see this in your cluster, consider some of the above steps to
+reduce disruption.
+
 ## <a name="npc"></a>Network Policy Controller
 
 The addon also supports the [Kubernetes policy