Bug 1304067 - [Docs] Secrete Restrictions are not clear
[Docs] Secrete Restrictions are not clear
Product: OpenShift Container Platform
Classification: Red Hat
Component: Documentation (Show other bugs)
Unspecified Unspecified
medium Severity medium
: ---
: ---
Assigned To: Ashley Hardin
weiwei jiang
Vikram Goyal
: NeedsTestCase
Depends On:
  Show dependency treegraph
Reported: 2016-02-02 14:23 EST by Eric Rich
Modified: 2016-10-30 18:53 EDT (History)
6 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Last Closed: 2016-07-15 11:21:39 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---

Attachments (Terms of Use)
Sample Files (596 bytes, application/x-xz)
2016-02-03 09:53 EST, Eric Rich
no flags Details

  None (edit)
Description Eric Rich 2016-02-02 14:23:39 EST
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.
Comment 1 Eric Rich 2016-02-03 09:53 EST
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"
Comment 2 Steven Walter 2016-06-06 10:29:25 EDT
    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.

      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.
Comment 3 Ashley Hardin 2016-06-21 14:41:44 EDT
Work in progress: https://github.com/openshift/openshift-docs/pull/2325

@Eric- Please review. Thanks!
Comment 4 Eric Rich 2016-06-21 15:12:42 EDT
(In reply to Ashley Hardin from comment #3)
> Work in progress: https://github.com/openshift/openshift-docs/pull/2325
> @Eric- Please review. Thanks!

Comment 5 weiwei jiang 2016-06-22 04:00:29 EDT
Checked and the doc looks better now.
Comment 6 openshift-github-bot 2016-06-22 11:17:06 EDT
Commits pushed to master at https://github.com/openshift/openshift-docs

Bug 1304067, added clarifying details to the Secret Restrictions section

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

Bug 1304067, added clarifying details to the Secret Restrictions section

Note You need to log in before you can comment on or make changes to this bug.