Improve secrets docs.

Explain that imagePullSecrets added to a service account
are added automatically to pods using that service account.

Reword text to not imply that ordinary secrets added to
a service account are not automatically added as volumes
to a pod.

docs/user-guide/secrets.md

@@ -43,11 +43,12 @@ a docker image. See [Secrets design document](../design/secrets.md) for more inf
 
 - [Secrets](#secrets)
   - [Overview of Secrets](#overview-of-secrets)
-    - [Service Accounts Automatically Create and Use Secrets with API Credentials](#service-accounts-automatically-create-and-use-secrets-with-api-credentials)
+    - [Service Accounts Automatically Create and Attach Secrets with API Credentials](#service-accounts-automatically-create-and-attach-secrets-with-api-credentials)
     - [Creating a Secret Manually](#creating-a-secret-manually)
     - [Manually specifying a Secret to be Mounted on a Pod](#manually-specifying-a-secret-to-be-mounted-on-a-pod)
     - [Manually specifying an imagePullSecret](#manually-specifying-an-imagepullsecret)
-    - [Automatic use of Manually Created Secrets](#automatic-use-of-manually-created-secrets)
+    - [Arranging for imagePullSecrets to be Automatically Attached](#arranging-for-imagepullsecrets-to-be-automatically-attached)
+    - [Automatic Mounting of Manually Created Secrets](#automatic-mounting-of-manually-created-secrets)
   - [Details](#details)
     - [Restrictions](#restrictions)
     - [Consuming Secret Values](#consuming-secret-values)
@@ -64,19 +65,18 @@ a docker image. See [Secrets design document](../design/secrets.md) for more inf
 
 ## Overview of Secrets
 
+A Secret is an object that contains a small amount of sensitive data such as
+a password, a token, or a key.  Such information might otherwise be put in a
+Pod specification or in an image; putting it in a Secret object allows for
+more control over how it is used, and reduces the risk of accidental exposure.
 
-Creation of secrets can be manual (done by the user) or automatic (done by
+Users can create secrets, and the system also creates some secrets.
-automation built into the cluster).
 
-A secret can be used with a pod in two ways: either as files in a [volume](volumes.md) mounted on one or more of
+To use a secret, a pod needs to reference the secret.
+A secret can be used with a pod in two ways: eithe as files in a [volume](volumes.md) mounted on one or more of
 its containers, or used by kubelet when pulling images for the pod.
 
-To use a secret, a pod needs to reference the secret.  This reference
+### Service Accounts Automatically Create and Attach Secrets with API Credentials
-can likewise be added manually or automatically.
-
-A single Pod may use various combination of the above options.
-
-### Service Accounts Automatically Create and Use Secrets with API Credentials
 
 Kubernetes automatically creates secrets which contain credentials for
 accessing the API and it automatically modifies your pods to use this type of
@@ -112,9 +112,8 @@ are `value-1` and `value-2`, respectively, with carriage return and newline char
 
 Create the secret using [`kubectl create`](kubectl/kubectl_create.md).
 
-Once the secret is created, you can:
+Once the secret is created, you can need to modify your pod to specify
-  - create pods that automatically use it via a [Service Account](service-accounts.md).
+that it should use the secret.
-  - modify your pod specification to use the secret
 
 ### Manually specifying a Secret to be Mounted on a Pod
 
@@ -162,15 +161,22 @@ See another example of creating a secret and a pod that consumes that secret in
 
 Use of imagePullSecrets is described in the [images documentation](images.md#specifying-imagepullsecrets-on-a-pod)
 
-### Automatic use of Manually Created Secrets
+### Arranging for imagePullSecrets to be Automatically Attached
 
-*This feature is planned but not implemented.  See [issue
+You can manually create an imagePullSecret, and reference it from
-9902](http://issue.k8s.io/9902).*
+a serviceAccount.  Any pods created with that serviceAccount
+or that default to use that serviceAccount, will get have the imagePullSecret of the
+field set to that of the service account.
+See [here](service-accounts.md#adding-imagepullsecrets-to-a-service-account)
+ for a detailed explanation of that process.
 
-You can reference manually created secrets from a [Service Account](service-accounts.md).
+
-Then, pods which use that Service Account will have
+### Automatic Mounting of Manually Created Secrets
-`volumeMounts` and/or `imagePullSecrets` added to them.
+
-The secrets will be mounted at **TBD**.
+We plan to extend the service account behavior so that manually created
+secrets (e.g. one containing a token for accessing a github account)
+can be automatically attached to pods based on their service account.
+*This is not implemented yet.  See [issue 9902](http://issue.k8s.io/9902).*
 
 ## Details
 

docs/user-guide/service-accounts.md

@@ -160,6 +160,62 @@ token:
 
 > Note that the content of `token` is elided here.
 
+## Adding ImagePullSecrets to a service account
+
+First, create an imagePullSecret, as described [here](images.md#specifying-imagepullsecrets-on-a-pod)
+Next, verify it has been created.  For example:
+
+```console
+$ kubectl get secrets myregistrykey
+NAME             TYPE                      DATA
+myregistrykey    kubernetes.io/dockercfg   1
+```
+
+Next, read/modify/write the service account for the namespace to use this secret as an imagePullSecret
+
+```console
+$ kubectl get serviceaccounts default -o yaml > ./sa.yaml
+$ cat sa.yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  creationTimestamp: 2015-08-07T22:02:39Z
+  name: default
+  namespace: default
+  resourceVersion: "243024"
+  selfLink: /api/v1/namespaces/default/serviceaccounts/default
+  uid: 052fb0f4-3d50-11e5-b066-42010af0d7b6
+secrets:
+- name: default-token-uudge
+$ vi sa.yaml
+[editor session not shown]
+[delete line with key "resourceVersion"]
+[add lines with "imagePullSecret:"]
+$ cat sa.yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  creationTimestamp: 2015-08-07T22:02:39Z
+  name: default
+  namespace: default
+  selfLink: /api/v1/namespaces/default/serviceaccounts/default
+  uid: 052fb0f4-3d50-11e5-b066-42010af0d7b6
+secrets:
+- name: default-token-uudge
+imagePullSecrets:
+- name: myregistrykey
+$ kubectl replace serviceaccount default -f ./sa.yaml
+serviceaccounts/default
+```
+
+Now, any new pods created in the current namespace will have this added to their spec:
+
+```yaml
+spec:
+  imagePullSecrets:
+  - name: myregistrykey
+```
+
 ## Adding Secrets to a service account.
 
 TODO: Test and explain how to use additional non-K8s secrets with an existing service account.