From cd2b26890520e89b2f858bb3e4a6f00495a00f92 Mon Sep 17 00:00:00 2001
From: Janet Kuo <chiachenk@google.com>
Date: Mon, 25 Apr 2016 14:00:59 -0700
Subject: [PATCH] Document Deployment restartPolicy

---
 docs/user-guide/deployments.md                  | 16 ++++++++++++++--
 docs/user-guide/labels.md                       |  4 ++--
 docs/user-guide/replication-controller/index.md |  4 ++--
 3 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/docs/user-guide/deployments.md b/docs/user-guide/deployments.md
index e8fe9d6cbf..e7f1442ebb 100644
--- a/docs/user-guide/deployments.md
+++ b/docs/user-guide/deployments.md
@@ -425,6 +425,12 @@ The `.spec.template` is a [pod template](/docs/user-guide/replication-controller
 the same schema as a [Pod](/docs/user-guide/pods), except it is nested and does not have an
 `apiVersion` or `kind`.
 
+In addition to required fields for a Pod, a pod template in a Deployment must specify appropriate
+labels (see [selector](#selector)) and an appropriate restart policy.
+
+Only a [`RestartPolicy`](/docs/user-guide/pod-states/) equal to `Always` is allowed, which is the default
+if not specified.
+
 ### Replicas
 
 `.spec.replicas` is an optional field that specifies the number of desired Pods. It defaults
@@ -432,8 +438,14 @@ to 1.
 
 ### Selector
 
-`.spec.selector` is an optional field that specifies label selectors for Pods
-targeted by this deployment. Deployment kills some of these Pods, if their
+`.spec.selector` is an optional field that specifies [label selectors](/docs/user-guide/labels/#label-selectors) for Pods
+targeted by this deployment. 
+
+If specified, the `.spec.template.metadata.labels` must be equal to the `.spec.selector`, or it will
+be rejected by the API.  If `.spec.selector` is unspecified, it will be defaulted to
+`.spec.template.metadata.labels`.
+
+Deployment kills some of these Pods, if their
 template is different than `.spec.template` or if the total number of such Pods
 exceeds `.spec.replicas`. It will bring up new Pods with `.spec.template` if
 number of Pods are less than the desired number.
diff --git a/docs/user-guide/labels.md b/docs/user-guide/labels.md
index 86df0df9af..fa7109b50a 100644
--- a/docs/user-guide/labels.md
+++ b/docs/user-guide/labels.md
@@ -147,9 +147,9 @@ selector:
 
 this selector (respectively in `json` or `yaml` format) is equivalent to `component=redis` or `component in (redis)`.
 
-#### Job and other new resources
+#### Resources that support set-based requirements
 
-Newer resources, such as [job](/docs/user-guide/jobs), support _set-based_ requirements as well.
+Newer resources, such as [`Job`](/docs/user-guide/jobs), [`Deployment`](/docs/user-guide/deployments/), [`Replica Set`](/docs/user-guide/replicasets/), and [`Daemon Set`](/docs/admin/daemons/), support _set-based_ requirements as well.
 
 ```yaml
 selector:
diff --git a/docs/user-guide/replication-controller/index.md b/docs/user-guide/replication-controller/index.md
index 49e393fe4f..f94a79cac4 100644
--- a/docs/user-guide/replication-controller/index.md
+++ b/docs/user-guide/replication-controller/index.md
@@ -96,8 +96,8 @@ The `.spec.template` is a [pod template](#pod-template).  It has exactly
 the same schema as a [pod](/docs/user-guide/pods/), except it is nested and does not have an `apiVersion` or
 `kind`.
 
-In addition to required fields for a Pod, a pod template in a job must specify appropriate
-labels (see [pod selector](#pod-selector) and an appropriate restart policy.
+In addition to required fields for a Pod, a pod template in a Replication Controller must specify appropriate
+labels (see [pod selector](#pod-selector)) and an appropriate restart policy.
 
 Only a [`RestartPolicy`](/docs/user-guide/pod-states/) equal to `Always` is allowed, which is the default
 if not specified.