Rework definition of pods.

This rephrases and expands the definition of pods in an attempt to be:
a) much more explicit about what technically constitutes a pod;
b) agnostic towards particular container implementations.

A change along these lines will be critical as Kubernetes starts to
support alternative container runtimes (for example, #2725).

In trying to be as clear as possible, this turned into a larger rewrite
than I had originally anticipated, but I am fairly confident that it is
still effectively a no-op in terms of the current Kubernetes
implementation.  But I stand correctable :-).

The change also introduces some other minor cleanup and drops the
link to the `lmctfy` paper, which seemed like a tenuous reference
(perhaps there is something more specific within the lmctfy project we
could link to instead?)

docs/pods.md

@@ -1,12 +1,23 @@
 # Pods
 
-In Kubernetes, rather than individual containers, _pods_ are the smallest deployable units that can be created, scheduled, and managed.
+In Kubernetes, rather than individual application containers, _pods_ are the smallest deployable units that can be created, scheduled, and managed.
 
 ## What is a _pod_?
 
-A _pod_ (as in a pod of whales or pea pod) correspond to a colocated group of [Docker containers](http://docker.io) with shared [volumes](volumes.md). A pod models an application-specific "logical host" in a containerized environment. It may contain one or more containers which are relatively tightly coupled -- in a pre-container world, they would have executed on the same physical or virtual host.
+A _pod_ (as in a pod of whales or pea pod) corresponds to a colocated group of applications running with a shared context. Within that context, the applications may also have individual cgroup isolations applied. A pod models an application-specific "logical host" in a containerized environment. It may contain one or more applications which are relatively tightly coupled -- in a pre-container world, they would have executed on the same physical or virtual host.
 
-Like running containers, pods are considered to be relatively ephemeral rather than durable entities. As discussed in [life of a pod](pod-states.md), pods are scheduled to nodes and remain there until termination (according to restart policy) or deletion. When a node dies, the pods scheduled to that node are deleted. Specific pods are never rescheduled to new nodes; instead, they must be replaced (see [replication controller](replication-controller.md) for more details). (In the future, a higher-level API may support pod migration.)
+The context of the pod can be defined as the conjunction of several Linux namespaces:
+- PID namespace (applications within the pod can see each other's processes)
+- network namespace (applications within the pod have access to the same IP and port space)
+- mount namespace (applications within the pod can share mounted volumes)
+- IPC namespace (applications within the pod can use SystemV IPC or POSIX message queues to communicate)
+- UTS namespace (applications within the pod share a hostname)
+
+Additionally, a pod may define top-level cgroup isolations which form an outer bound to any individual isolation applied to constituent applications.
+
+In terms of [Docker](https://www.docker.com/) constructs, a pod consists of a colocated group of Docker containers with shared [volumes](volumes.md) (which emulate the shared mount namespace). IPC and PID namespace sharing are not yet implemented with Docker.
+
+Like individual application containers, pods are considered to be relatively ephemeral rather than durable entities. As discussed in [life of a pod](pod-states.md), pods are scheduled to nodes and remain there until termination (according to restart policy) or deletion. When a node dies, the pods scheduled to that node are deleted. Specific pods are never rescheduled to new nodes; instead, they must be replaced (see [replication controller](replication-controller.md) for more details). (In the future, a higher-level API may support pod migration.)
 
 ## Motivation for pods
 
@@ -14,11 +25,9 @@ Like running containers, pods are considered to be relatively ephemeral rather t
 
 Pods facilitate data sharing and communication among their constituents.
 
-The containers in the pod all use the same network namespace/IP and port space, and can find and communicate with each other using localhost. Each pod has an IP address in a flat shared networking namespace that has full communication with other physical computers and containers across the network. The hostname is set to the pod's Name for the containers within the pod. [More details on networking](networking.md).
+The applications in the pod all use the same network namespace/IP and port space, and can find and communicate with each other using localhost. Each pod has an IP address in a flat shared networking namespace that has full communication with other physical computers and containers across the network. The hostname is set to the pod's Name for the containers within the pod. [More details on networking](networking.md).
 
-In addition to defining the containers that run in the pod, the pod specifies a set of shared storage volumes. Volumes enable data to survive container restarts and to be shared among the containers within the pod.
-
-In the future, pods will share IPC namespaces, CPU, and memory ([LPC2013](http://www.linuxplumbersconf.org/2013/ocw//system/presentations/1239/original/lmctfy%20(1).pdf)).
+In addition to defining the application containers that run in the pod, the mount namespace allows the pod to provide a set of shared storage volumes. Volumes enable data to survive container restarts and to be shared among the applications within the pod.
 
 ### Management
 
@@ -37,11 +46,13 @@ Individual pods are not intended to run multiple instances of the same applicati
 
 ## Alternatives considered
 
-Why not just run multiple programs in a single Docker container?
+_Why not just run multiple programs in a single (Docker) container?_
 
 1. Transparency. Making the containers within the pod visible to the infrastructure enables the infrastructure to provide services to those containers, such as process management and resource monitoring. This facilitates a number of conveniences for users.
 2. Decoupling software dependencies. The individual containers may be rebuilt and redeployed independently. Kubernetes may even support live updates of individual containers someday.
 3. Ease of use. Users don't need to run their own process managers, worry about signal and exit-code propagation, etc.
 4. Efficiency. Because the infrastructure takes on more responsibility, containers can be lighterweight.
 
-Why not support affinity-based co-scheduling of containers? That approach would provide co-location, but would not provide most of the benefits of pods, such as resource sharing, IPC, guaranteed fate sharing, and simplified management.
+_Why not support affinity-based co-scheduling of containers?_
+
+That approach would provide co-location, but would not provide most of the benefits of pods, such as resource sharing, IPC, guaranteed fate sharing, and simplified management.