Merge pull request #8979 from erictune/docs6

Explain that file-based pods cannot use secrets

docs/design/secrets.md

@@ -1,4 +1,3 @@
-# Secret Distribution
 
 ## Abstract
 
@@ -184,6 +183,11 @@ For now, we will not implement validations around these limits.  Cluster operato
 much node storage is allocated to secrets. It will be the operator's responsibility to ensure that
 the allocated storage is sufficient for the workload scheduled onto a node.
 
+For now, kubelets will only attach secrets to api-sourced pods, and not file- or http-sourced
+ones.  Doing so would:
+  - confuse the secrets admission controller in the case of mirror pods.
+  - create an apiserver-liveness dependency -- avoiding this dependency is a main reason to use non-api-source pods.
+
 ### Use-Case: Kubelet read of secrets for node
 
 The use-case where the kubelet reads secrets has several additional requirements:

docs/secrets.md

@@ -73,6 +73,12 @@ of very large secrets which would exhaust apiserver and kubelet memory.
 However, creation of many smaller secrets could also exhaust memory.  More
 comprehensive limits on memory usage due to secrets is a planned feature.
 
+Kubelet only supports use of secrets for Pods it gets from the API server.
+This includes any pods created using kubectl, or indirectly via a replication
+controller.  It does not include pods created via the kubelets
+`--manifest-url` flag, its `--config` flag, or its REST API (these are
+not common ways to create pods.)
+
 ### Consuming Secret Values
 
 The program in a container is responsible for reading the secret(s) from the