Extend secrets docs with key to path mapping and automatic updates of mounted secrets.

Secret volume plugin has been refactored. Currently, AtomicWritter is used to project all keys.
Allowing to automatically refresh projected secrets.

docs/user-guide/secrets/index.md

@@ -214,6 +214,52 @@ You can package many files into one secret, or use many secrets, whichever is co
 
 See another example of creating a secret and a pod that consumes that secret in a volume [here](/docs/user-guide/secrets/).
 
+##### Projection of secret keys to specific paths
+
+We can also control the paths within the volume where Secret keys are projected.
+You can use `spec.volumes[].secret.items` field to change target path of each key:
+
+```json
+{
+ "apiVersion": "v1",
+ "kind": "Pod",
+  "metadata": {
+    "name": "mypod",
+    "namespace": "myns"
+  },
+  "spec": {
+    "containers": [{
+      "name": "mypod",
+      "image": "redis",
+      "volumeMounts": [{
+        "name": "foo",
+        "mountPath": "/etc/foo",
+        "readOnly": true
+      }]
+    }],
+    "volumes": [{
+      "name": "foo",
+      "secret": {
+        "secretName": "mysecret",
+        "items": [{
+          "key": "username",
+          "path": "my-group/my-username"
+        }]
+      }
+    }]
+  }
+}
+```
+
+What will happen:
+
+* `username` secret is stored under `/etc/foo/my-group/my-username` file instead of `/etc/foo/username`.
+* `password` secret is not projected
+
+If `spec.volumes[].secret.items` is used, only keys specified in `items` are projected.
+To consume all keys from the secret, all of them must be listed in the `items` field.
+All listed keys must exist in the corresponding secret. Otherwise, the volume is not created.
+
 ##### Consuming Secret Values from Volumes
 
 Inside the container that mounts a secret volume, the secret keys appear as
@@ -234,6 +280,11 @@ $ cat /etc/foo/password
 The program in a container is responsible for reading the secret(s) from the
 files.
 
+##### Mounted Secrets are updated automatically
+
+When a secret being already consumed in a volume is updated, projected keys are eventually updated as well.
+The update time depends on the kubelet syncing period.
+
 #### Using Secrets as Environment Variables
 
 To use a secret in an environment variable in a pod:
@@ -334,27 +385,10 @@ secret exists.  Once a pod is scheduled, the kubelet will try to fetch the
 secret value.  If the secret cannot be fetched because it does not exist or
 because of a temporary lack of connection to the API server, kubelet will
 periodically retry.  It will report an event about the pod explaining the
-reason it is not started yet.  Once the a secret is fetched, the kubelet will
+reason it is not started yet.  Once the secret is fetched, the kubelet will
 create and mount a volume containing it.  None of the pod's containers will
 start until all the pod's volumes are mounted.
 
-Once the kubelet has started a pod's containers, its secret volumes will not
-change, even if the secret resource is modified.  To change the secret used,
-the original pod must be deleted, and a new pod (perhaps with an identical
-`PodSpec`) must be created.  Therefore, updating a secret follows the same
-workflow as deploying a new container image.  The `kubectl rolling-update`
-command can be used ([man page](/docs/user-guide/kubectl/kubectl_rolling-update)).
-
-The [`resourceVersion`](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#concurrency-control-and-consistency)
-of the secret is not specified when it is referenced.
-Therefore, if a secret is updated at about the same time as pods are starting,
-then it is not defined which version of the secret will be used for the pod. It
-is not possible currently to check what resource version of a secret object was
-used when a pod was created.  It is planned that pods will report this
-information, so that a replication controller restarts ones using an old
-`resourceVersion`.  In the interim, if this is a concern, it is recommended to not
-update the data of existing secrets, but to create new ones with distinct names.
-
 ## Use cases
 
 ### Use-Case: Pod with ssh keys