Merge pull request #2325 from ahardin-rh/serviceaccount-secret

Bug 1304067, added clarifying details to the Secret Restrictions section

dev_guide/secrets.adoc

@@ -25,7 +25,7 @@ properties of secrets and provides an overview on how developers can use them.
 ----
 apiVersion: "v1"
 kind: "Secret"
-metadata: 
+metadata:
   name: "mysecret"
 namespace: "myns"
 data: <1>
@@ -119,9 +119,20 @@ Repositories for Builds] for more information.
 [[secrets-restrictions]]
 == Restrictions
 
-Secret volume sources are validated to ensure that the specified object
-reference points to a `*Secret*` object. Therefore, a secret needs to be created
-before the pods that depend on it.
+To use a secret, a pod needs to reference the secret. A secret can be used with
+a pod in two ways: either as files in a volume mounted on one or more of its
+containers, or used by kubelet when pulling images for the pod.
+
+Volume type secrets write data into the container as a file using the volume
+mechanism. *imagePullSecrets* use service accounts for the automatic injection of
+the secret into all pods in a namespaces.
+
+When a template contains a secret definition, the only way for the template to
+use the provided secret is to ensure that the secret volume sources are
+validated and that the specified object reference actually points to an object
+of type `*Secret*`. Therefore, a secret needs to be created before any pods that
+depend on it. The most effective way to ensure this is to have it get injected
+automatically through the use of a service account.
 
 Secret API objects reside in a namespace. They can only be referenced by pods in
 that same namespace.
@@ -130,11 +141,6 @@ Individual secrets are limited to 1MB in size. This is to discourage the
 creation of large secrets that would exhaust apiserver and kubelet memory.
 However, creation of a number of smaller secrets could also exhaust memory.
 
-Currently, when mounting a secret, the service account for a pod must have the
-secret in the list of mountable secrets. If a template contains a secret
-definition and pods that consume it, the pods will be rejected until the service
-account is updated.
-
 [[secret-data-keys]]
 
 === Secret Data Keys