Bug 1304067

Document URL: https://docs.openshift.com/enterprise/3.0/dev_guide/secrets.html#restrictions

Section Number and Name: Restrictions

Describe the issue: The way the documentation currently reads it makes customers think that "if the pod has a serviceaccount defined and the serviceaccount doesn't reference a secret, [that] the pod will fail to deploy because the secret is mounting doesn't appear in serviceaccount"

This is a direct reference to: 

"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."

Suggestions for improvement: 

If your review the information from http://kubernetes.io/v1.1/docs/user-guide/secrets.html#secrets you will see that there are 2 types of secretes. 

    "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."

The first type is a volume type, and it simply writes data into the container as a file using the volume mechanism. 
The second type is a imagePullSecrets and this type uses Service accounts for the automatic injection of this secrete into all pods in a namespaces. It is this second type to which the note [in our documentation is] pointing to:

Because the example uses a "template [that] contains a secret definition", the only way for the "template" to use the provided secrete is to ensure that "Secret volume sources are validated to ensure 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." is meet as requirement first. The best and most effective way to ensure this is to have it get injected automatically through the use of a service account. 

Additional information: 

It is not 100% clear if the serviceaccount needs to know of the secrete as in theory if "a secret [is] created before any pods that depend on it" you should be able to deploy or use a template (however its not clear if what name space the secrete needs to be in). -- This should be investigated by Engineering and QE, as I feel the use of a service account (and the restriction here) is simply to make thing simple for the user.