Red Hat Bugzilla – Bug 1304067
[Docs] Secrete Restrictions are not clear
Last modified: 2016-10-30 18:53:21 EDT
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.
Created attachment 1120804 [details] Sample Files Customer who read our documentation now expect the following flow to occur. Deploy secret-sa.yml (oc create -f secret-sa.yml) Deploy secret.yml (oc create -f secret.yml) Deploy mysecurepod.yml as it have secret-sa service account, the pod can mount the secret, so it can be deployed (oc create -f mysecurepod.yml) Deploy should-fail-pod.yml wich doesn't have secret-sa service account so it should not mount the secret and therefore should not be deployed (oc create -f should-fail-pod.yml) - Note: This last item is not correct as the service account information only applies to "imagesecretes"
The section noted by Eric, https://docs.openshift.com/enterprise/3.0/dev_guide/secrets.html#restrictions, also creates confusion when compared to the following paragraph from https://docs.openshift.com/enterprise/3.1/admin_guide/service_accounts.html#infrastructure-service-accounts: Set limitSecretReferences field in master configuration file to true to require pod secret references to be whitelisted by their service accounts. Set its value to false to allow pods to reference any secret in the namespace. serviceAccountConfig: ... limitSecretReferences: false From the developer's perspective, the documentation indicates that a secret must be indicated in a pod's service account in order for the service account to mount the secret volume. However this is only true if the above variable is set in the master-config file, and this is only indicated in the cluster admin's service account page. The developer guide would likely benefit from an indication that the cluster administrator would need to enable this; as there is no real cluster administrator page on secrets, there should at least be a reference in the developer's guide to this effect.
Work in progress: https://github.com/openshift/openshift-docs/pull/2325 @Eric- Please review. Thanks!
(In reply to Ashley Hardin from comment #3) > Work in progress: https://github.com/openshift/openshift-docs/pull/2325 > > @Eric- Please review. Thanks! LGTM
Checked and the doc looks better now.
Commits pushed to master at https://github.com/openshift/openshift-docs https://github.com/openshift/openshift-docs/commit/dbf6c5a36552039376e38c2f583fb7b947e61c16 Bug 1304067, added clarifying details to the Secret Restrictions section https://github.com/openshift/openshift-docs/commit/4364b8b078a21438f4e8d3c116c9cf6cc1ffd2d6 Merge pull request #2325 from ahardin-rh/serviceaccount-secret Bug 1304067, added clarifying details to the Secret Restrictions section
Content is now published: https://access.redhat.com/documentation/en/openshift-enterprise/version-3.2/developer-guide/#secrets-restrictions