Better docs for downward API

docs/downward_api.md

@@ -1,28 +1,51 @@
 # Downward API
 
-The downward API allows containers to consume information about the system without coupling to the
+It is sometimes useful for a container to have information about itself, but we
+want to be careful not to over-couple containers to Kubernetes. The downward
+API allows containers to consume information about themselves or the system and
+expose that information how they want it, without necessarily coupling to the
 kubernetes client or REST API.
 
-### Capabilities
+An example of this is a "legacy" app that is already written assuming
+that a particular environment variable will hold a unique identifier.  While it
+is often possible to "wrap" such applications, this is tedious and error prone,
+and violates the goal of low coupling.  Instead, the user should be able to use
+the Pod's name, for example, and inject it into this well-known variable.
 
-Containers can consume the following information via the downward API:
+## Capabilities
 
-*   Their pod's name
-*   Their pod's namespace
+The following information is available to a `Pod` through the the downward API:
 
-### Consuming information about a pod in a container
+*   The pod's name
+*   The pod's namespace
 
-Containers consume information from the downward API using environment variables.  In the future,
-containers will also be able to consume the downward API via a volume plugin.  The `valueFrom`
-field of an environment variable allows you to specify an `ObjectFieldSelector` to select fields
-from the pod's definition.  The `ObjectFieldSelector` has an `apiVersion` field and a `fieldPath`
-field.  The `fieldPath` field is an expression designating a field on the pod.  The `apiVersion`
-field is the version of the API schema that the `fieldPath` is written in terms of.  If the
-`apiVersion` field is not specified it is defaulted to the API version of the enclosing object.
+More information will be exposed through this same API over time.
 
-### Example: consuming the downward API
+## Exposing pod information into a container
 
-This is an example of a pod that consumes its name and namespace via the downward API:
+Containers consume information from the downward API using environment
+variables.  In the future, containers will also be able to consume the downward
+API via a volume plugin.
+
+### Environment variables
+
+Most environment variables in the Kubernetes API use the `value` field to carry
+simple values.  However, the alternate `valueFrom` field allows you to specify
+a `fieldRef` to select fields from the pod's definition.  The `fieldRef` field
+is a structure that has an `apiVersion` field and a `fieldPath` field.  The
+`fieldPath` field is an expression designating a field of the pod.  The
+`apiVersion` field is the version of the API schema that the `fieldPath` is
+written in terms of.  If the `apiVersion` field is not specified it is
+defaulted to the API version of the enclosing object.
+
+The `fieldRef` is evaluated and the resulting value is used as the value for
+the environment variable.  This allows users to publish their pod's name in any
+environment variable they want.
+
+## Example
+
+This is an example of a pod that consumes its name and namespace via the
+downward API:
 
 ```yaml
 apiVersion: v1
@@ -35,16 +58,20 @@ spec:
       image: gcr.io/google_containers/busybox
       command: [ "/bin/sh", "-c", "env" ]
       env:
-        - name: POD_NAME
+        - name: MY_POD_NAME
           valueFrom:
             fieldRef:
               fieldPath: metadata.name
-        - name: POD_NAMESPACE
+        - name: MY_POD_NAMESPACE
           valueFrom:
             fieldRef:
               fieldPath: metadata.namespace
   restartPolicy: Never
 ```
 
+Some more thorough examples:
+   * [environment variables](../examples/environment-guide)
+   * [downward API](../examples/downward-api)
+
 
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/downward_api.md?pixel)]()