From 4ac08fcccdc3c362d09aa51e9744fc7e65af0717 Mon Sep 17 00:00:00 2001
From: Jay Pipes <jaypipes@gmail.com>
Date: Mon, 10 Jun 2019 10:39:08 -0400
Subject: [PATCH] improve arch/nodes.md info on Conditions and Allocatable
 (#14753)

* clarify Conditions section in arch/nodes.md

The field name is `conditions` (plural), so have the section name match
the field name. In addition, updates the JSON output of an individual
Condition to match all the fields returned in k8s 1.14+.

* add information about Allocatable to nodes.md

Since k8s 1.6, a Node object returns information about both the node's
capacity as well as the allocatable resources on the node. The latter is
a representation of the resources that are available for normal pods to
consume.

This patch adds information about capacity vs. allocatable to the
documentation about nodes and provides a link to where the reader can
find more information about reserving compute resources.
---
 .../en/docs/concepts/architecture/nodes.md    | 24 ++++++++++++++-----
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/content/en/docs/concepts/architecture/nodes.md b/content/en/docs/concepts/architecture/nodes.md
index c70b99fb87..921e380872 100644
--- a/content/en/docs/concepts/architecture/nodes.md
+++ b/content/en/docs/concepts/architecture/nodes.md
@@ -26,8 +26,8 @@ architecture design doc for more details.
 A node's status contains the following information:
 
 * [Addresses](#addresses)
-* [Condition](#condition)
-* [Capacity](#capacity)
+* [Conditions](#condition)
+* [Capacity and Allocatable](#capacity)
 * [Info](#info)
 
 Each section is described in detail below.
@@ -41,9 +41,9 @@ The usage of these fields varies depending on your cloud provider or bare metal
 * InternalIP: Typically the IP address of the node that is routable only within the cluster.
 
 
-### Condition
+### Conditions {#condition}
 
-The `conditions` field describes the status of all `Running` nodes.
+The `conditions` field describes the status of all `Running` nodes. Examples of conditions include:
 
 | Node Condition | Description |
 |----------------|-------------|
@@ -60,7 +60,11 @@ The node condition is represented as a JSON object. For example, the following r
 "conditions": [
   {
     "type": "Ready",
-    "status": "True"
+    "status": "True",
+    "reason": "KubeletReady",
+    "message": "kubelet is posting ready status",
+    "lastHeartbeatTime": "2019-06-05T18:38:35Z",
+    "lastTransitionTime": "2019-06-05T11:41:27Z"
   }
 ]
 ```
@@ -88,11 +92,19 @@ Enabling this feature creates a small delay between the
 time when a condition is observed and when a taint is created. This delay is usually less than one second, but it can increase the number of Pods that are successfully scheduled but rejected by the kubelet.
 {{< /caution >}}
 
-### Capacity
+### Capacity and Allocatable {#capacity}
 
 Describes the resources available on the node: CPU, memory and the maximum
 number of pods that can be scheduled onto the node.
 
+The fields in the capacity block indicate the total amount of resources that a
+Node has. The allocatable block indicates the amount of resources that on a
+Node that are available to be consumed by normal Pods.
+
+You may read more about capacity and allocatable resources while learning how
+to [reserve compute resources](/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable)
+on a Node.
+
 ### Info
 
 General information about the node, such as kernel version, Kubernetes version