diff --git a/docs/user-guide/configmap/index.md b/docs/user-guide/configmap/index.md
index 7b5cd452fc..f37c83f4ac 100644
--- a/docs/user-guide/configmap/index.md
+++ b/docs/user-guide/configmap/index.md
@@ -414,6 +414,11 @@ When this pod is run, the output will be:
 very
 ```
 
+#### Projecting keys to specific paths and file permissions
+
+You can project keys to specific paths and specific permissions on a per-file
+basis. The [Secrets](/docs/user-guide/secrets/) user guide explains the syntax.
+
 ## Real World Example: Configuring Redis
 
 Let's take a look at a real-world example: configuring redis using ConfigMap.  Say we want to inject
diff --git a/docs/user-guide/downward-api/index.md b/docs/user-guide/downward-api/index.md
index 5a957b4323..b485c98c00 100644
--- a/docs/user-guide/downward-api/index.md
+++ b/docs/user-guide/downward-api/index.md
@@ -114,6 +114,10 @@ The downward API volume refreshes its data in step with the kubelet refresh loop
 
 In future, it will be possible to specify a specific annotation or label.
 
+#### Projecting keys to specific paths and file permissions
+
+You can project keys to specific paths and specific permissions on a per-file
+basis. The [Secrets](/docs/user-guide/secrets/) user guide explains the syntax.
 
 ### Example
 
diff --git a/docs/user-guide/secrets/index.md b/docs/user-guide/secrets/index.md
index fff246c937..6d388dbebd 100644
--- a/docs/user-guide/secrets/index.md
+++ b/docs/user-guide/secrets/index.md
@@ -262,6 +262,83 @@ If `spec.volumes[].secret.items` is used, only keys specified in `items` are pro
 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.
 
+**Secret files permissions**
+
+You can also specify the permission mode bits files part of a secret will have.
+If you don't specify any, `0644` is used by default. You can sepecify a default
+mode for the whole secret volume and override per key if needed.
+
+For example, you can specify a default mode like this:
+
+```json
+{
+ "apiVersion": "v1",
+ "kind": "Pod",
+  "metadata": {
+    "name": "mypod",
+    "namespace": "myns"
+  },
+  "spec": {
+    "containers": [{
+      "name": "mypod",
+      "image": "redis",
+      "volumeMounts": [{
+        "name": "foo",
+        "mountPath": "/etc/foo",
+      }]
+    }],
+    "volumes": [{
+      "name": "foo",
+      "secret": {
+        "secretName": "mysecret",
+        "defaultMode": 0400
+      }
+    }]
+  }
+}
+```
+
+Then, the secret will be mounted on `/etc/foo` and all the files created by the
+secret volume mount will have permission `0400`.
+
+You can also use mapping, as in the previous example, and specify different
+permission for different files like this:
+
+```json
+{
+ "apiVersion": "v1",
+ "kind": "Pod",
+  "metadata": {
+    "name": "mypod",
+    "namespace": "myns"
+  },
+  "spec": {
+    "containers": [{
+      "name": "mypod",
+      "image": "redis",
+      "volumeMounts": [{
+        "name": "foo",
+        "mountPath": "/etc/foo",
+      }]
+    }],
+    "volumes": [{
+      "name": "foo",
+      "secret": {
+        "secretName": "mysecret",
+        "items": [{
+          "key": "username",
+          "path": "my-group/my-username",
+          "mode": 0777
+        }]
+      }
+    }]
+  }
+}
+```
+
+In this case, the file resulting in `/etc/foo/my-group/my-username` will have
+permission `0777`.
+
 **Consuming Secret Values from Volumes**
 
 Inside the container that mounts a secret volume, the secret keys appear as