diff --git a/docs/images.md b/docs/images.md
index d124065c99c..d8979e8cd08 100644
--- a/docs/images.md
+++ b/docs/images.md
@@ -5,31 +5,152 @@ You create your Docker image and push it to a registry before referring to it in
 
 The `image` property of a container supports the same syntax as the `docker` command does, including private registries and tags.
 
+## Updating Images
+
+The default pull policy is `PullIfNotPresent` which causes the Kubelet to not
+pull an image if it already exists. If you would like to always force a pull
+you must set a pull image policy of `PullAlways` or specify a `:latest` tag on
+your image.
+
 ## Using a Private Registry
+Private registries may require keys to read images from them.
+Credentials can be provided in several ways:
+  - Using Google Container Registy
+    - Per-cluster
+    - automatically configured on GCE/GKE
+    - all pods can read the project's private registry
+  - Configuring Nodes to Authenticate to a Private Registry 
+    - all pods can read any configured private registries
+    - requires node configuration by cluster administrator
+  - Pre-pulling Images
+    - all pods can use any images cached on a node
+    - requires root access to all nodes to setup
+  - Specifying ImagePullKeys on a Pod
+    - only pods which provide own keys can access the private registry
+Each option is described in more detail below.
+   
 
-### Google Container Registry
-Kubernetes has native support for the [Google Container Registry](https://cloud.google.com/tools/container-registry/), when running on Google Compute Engine.  If you are running your cluster on Google Compute Engine or Google Container Engine, simply use the full image name (e.g. gcr.io/my_project/image:tag) and the kubelet will automatically authenticate and pull down your private image.
+### Using Google Container Registry
 
-### Other Private Registries
-Docker stores keys for private registries in a `.dockercfg` file.  Create a config file by running `docker login <registry>.<domain>` and then copying the resulting `.dockercfg` file to the kubelet working dir.
-The kubelet working dir varies by cloud provider.  It is `/` on GCE and `/home/core` on CoreOS.  You can determine the working dir by running this command:
-`sudo ls -ld /proc/$(pidof kubelet)/cwd` on a kNode.
+Kubernetes has native support for the [Google Container
+Registry (GCR)](https://cloud.google.com/tools/container-registry/), when running on Google Compute
+Engine (GCE).  If you are running your cluster on GCE or Google Container Engine (GKE), simply
+use the full image name (e.g. gcr.io/my_project/image:tag).
 
-All users of the cluster will have access to any private registry in the `.dockercfg`.
+All pods in a cluster will have read access to images in this registry.
 
-## Preloading Images
+The kubelet kubelet will authenticate to GCR using the instance's
+Google service account.  The service account on the instance
+will have a `https://www.googleapis.com/auth/devstorage.read_only`,
+so it can pull from the project's GCR, but not push.
+
+### Configuring Nodes to Authenticate to a Private Registry 
+Docker stores keys for private registries in a `.dockercfg` file.  Create a config file by running
+`docker login <registry>.<domain>` and then copy the resulting `.dockercfg` file to the root user's
+`$HOME` directory (e.g. `/root/.dockercfg`) on each node in the cluster.
+
+You must ensure all nodes in the cluster have the same `.dockercfg`.  Otherwise, pods will run on
+some nodes and fail to run on others.  For example, if you use node autoscaling, then each instance
+template needs to include the `.dockercfg` or mount a drive that contains it.
+
+All pods will have read access to images in any private registry with keys in the `.dockercfg`.
+
+### Pre-pulling Images
 
 Be default, the kubelet will try to pull each image from the specified registry.
 However, if the `imagePullPolicy` property of the container is set to `IfNotPresent` or `Never`,
 then a local image is used (preferentially or exclusively, respectively).
 
+If you want to rely on pre-pulled images as a substitute for registry authentication,
+you must ensure all nodes in the cluster have the same pre-pulled images.
+
 This can be used to preload certain images for speed or as an alternative to authenticating to a private registry.
 
-Pull Policy is per-container, but any user of the cluster will have access to all local images.
+All pods will have read access to any pre-pulled images.
 
-## Updating Images
+### Specifying ImagePullKeys on a Pod
+Kubernetes supports specifying registry keys on a pod.
 
-The default pull policy is `PullIfNotPresent` which causes the Kubelet to not pull an image if it already exists. If you would like to always force a pull you must set a pull image policy of `PullAlways` or specify a `:latest` tag on your image.
+First, create a `.dockercfg`, such as running `docker login <registry.domain>`.
+Then put the resulting `.dockercfg` file into a [secret resource](../docs/secret.md).  For example:
+```
+cat > dockercfg <<EOF
+{ 
+   "https://docker.io/thisisfake": { 
+     "email": "bob@example.com", 
+     "auth": "secret" 
+   } 
+}
+EOF
+$ cat dockercfg | base64
+eyAKICAgImh0dHBzOi8vZG9ja2VyLmlvL3RoaXNpc2Zha2UiOiB7IAogICAgICJlbWFpbCI6ICJib2JAZXhhbXBsZS5jb20iLCAKICAgICAiYXV0aCI6ICJzZWNyZXQiIAogICB9Cn0K
+
+cat > secret.json <<EOF
+{
+  "apiVersion": "v1",
+  "kind": "Secret",
+  "metadata" : {
+    "name": "myregistrykey",
+  },  
+  "type": "kubernetes.io/dockercfg",
+  "data": {
+    ".dockercfg":
+      "eyAKICAgImh0dHBzOi8vZG9ja2VyLmlvL3RoaXNpc2Zha2UiOiB7IAogICAgICJlbWFpbCI6ICJib2JAZXhhbXBsZS5jb20iLCAKICAgICAiYXV0aCI6ICJzZWNyZXQiIAogICB9Cn0K",
+  }
+}
+EOF
+This process only needs to be done one time (per namespace).
+
+$ kubectl create -f secret.json
+secrets/myregistrykey
+```
+
+Now, you can create pods which reference that secret by adding an `imagePullSecrets`
+section to a pod definition.
+```
+apiVersion: v1
+kind: Pod
+metadata:
+  name: foo
+spec:
+  containers:
+    - name: foo
+      image: registry.example.com/bar/fo
+  imagePullSecrets:
+    - name: myregistrykey
+```
+This needs to be done for each pod that is using a private registry.
+However, setting of this field can be automated by setting the imagePullSecrets
+in a [serviceAccount](../docs/service_accounts.md) resource.
+
+Currently, all pods will potentially have read access to any images which were
+pulled using imagePullSecrets.  That is, imagePullSecrets does *NOT* protect your
+images from being seen by other users in the cluster.  Our intent
+is to fix that.
+
+### Use Cases
+There are a number of solutions for configuring private registries.  Here are some
+common use cases and suggested solutions.
+
+ 1. Cluster running only non-proprietary (e.g open-source) images.  No need to hide images.
+   - Use public images on the Docker hub.
+     - no configuration required
+     - on GCE/GKE, a local mirror is automatically used for improved speed and availability
+ 1. Cluster running some proprietary images which should be hidden to those outside the company, but
+   visible to all cluster users.
+   - Use a hosted private [Docker registry](https://docs.docker.com/registry/)
+     - may be hosted on the [Docker Hub](https://hub.docker.com/account/signup/), or elsewhere.
+     - manually configure .dockercfg on each node as described above
+   - Or, run an internal private registry behind your firewall with open read access.
+     - no kubernetes configuration required
+   - Or, when on GCE/GKE, use the project's Google Container Registry.
+     - will work better with cluster autoscaling than manual node configuration
+   - Or, on a cluster where changing the node configuration is inconvenient, use `imagePullSecrets`.
+  1. Cluster with a proprietary images, a few of which require stricter access control
+     - Move sensitive data into a "Secret" resource, instead of packaging it in an image.
+     - DO NOT use imagePullSecrets for this use case yet.
+  1. A multi-tenant cluster where each tenant needs own private registry
+     - NOT supported yet.
 
 
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/images.md?pixel)]()