Update replication-controller docs

Adds a document on pod templates that can be shared between various controller docs. Move more philosophical content to later in the doc. Add more task-oriented stuff earlier. Put example config in the document, early on, so users have something concrete to relate the discussion of fields to. Link to Job and DaemonSet docs. Make format more like that of Job and DaemonSet docs. Use jsonpath in examples, which is available in v1.1. Added example files.
lavalamp · Feb 8, 2016 · f7a89ce · f7a89ce
1 parent 6b20879
commit f7a89ce
Show file tree

Hide file tree

Showing 4 changed files with 296 additions and 23 deletions.
diff --git a/docs/user-guide/pod-templates.md b/docs/user-guide/pod-templates.md
@@ -0,0 +1,46 @@
+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
+
+<!-- BEGIN STRIP_FOR_RELEASE -->
+
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+
+<h2>PLEASE NOTE: This document applies to the HEAD of the source tree</h2>
+
+If you are using a released version of Kubernetes, you should
+refer to the docs that go with that version.
+
+Documentation for other releases can be found at
+[releases.k8s.io](http://releases.k8s.io).
+</strong>
+--
+
+<!-- END STRIP_FOR_RELEASE -->
+
+<!-- END MUNGE: UNVERSIONED_WARNING -->
+
+# Pod Templates
+
+Pod templates are [pod](pods.md) specifications which are included in other objects, such as
+[Replication Controllers](replication-controller.md), [Jobs](jobs.md), and
+[DaemonSets](../admin/daemons.md).  Controllers use Pod Templates to make actual pods.
+
+Rather than specifying the current desired state of all replicas, pod templates are like cookie cutters. Once a cookie has been cut, the cookie has no relationship to the cutter. There is no quantum entanglement. Subsequent changes to the template or even switching to a new template has no direct effect on the pods already created. Similarly, pods created by a replication controller may subsequently be updated directly. This is in deliberate contrast to pods, which do specify the current desired state of all containers belonging to the pod. This approach radically simplifies system semantics and increases the flexibility of the primitive.
+
+
+## Future Work
+
+A replication controller creates new pods from a template, which is currently inline in the `ReplicationController` object, but which we plan to extract into its own resource [#170](http://issue.k8s.io/170).
+
+
+<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
+[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/pod-templates.md?pixel)]()
+<!-- END MUNGE: GENERATED_ANALYTICS -->