Merge pull request #434 from janetkuo/deployments-restart-policy

Document Deployment restartPolicy

docs/user-guide/deployments.md

@@ -432,6 +432,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 (i.e. don't overlap with other controllers, see [selector](#selector)) and an appropriate restart policy.
+
+Only a [`.spec.template.spec.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
@@ -439,8 +445,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 a [label selector](/docs/user-guide/labels/#label-selectors) for the Pods
+targeted by this deployment. 
+
+If specified, `.spec.selector` must match `.spec.template.metadata.labels`, or it will
+be rejected by the API.  If `.spec.selector` is unspecified, `.spec.selector.matchLabels` will be defaulted to
+`.spec.template.metadata.labels`.
+
+Deployment may kill Pods whose labels match the selector, in the case that 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.