From 8dcc673d5d1f000a3077dc67d5285e9f1d8fb788 Mon Sep 17 00:00:00 2001
From: Jeff Peeler <jpeeler@redhat.com>
Date: Tue, 21 Feb 2017 15:14:36 -0500
Subject: [PATCH] Add docs for projected volume driver

---
 _data/guides.yml                          |  1 +
 docs/user-guide/projected-volume/OWNERS   |  4 ++
 docs/user-guide/projected-volume/index.md | 73 +++++++++++++++++++++++
 3 files changed, 78 insertions(+)
 create mode 100644 docs/user-guide/projected-volume/OWNERS
 create mode 100644 docs/user-guide/projected-volume/index.md

diff --git a/_data/guides.yml b/_data/guides.yml
index df3ebad90a..3cf2e05947 100644
--- a/_data/guides.yml
+++ b/_data/guides.yml
@@ -27,6 +27,7 @@ toc:
   - docs/user-guide/update-demo/index.md
   - docs/user-guide/secrets/walkthrough.md
   - docs/user-guide/configmap/index.md
+  - docs/user-guide/projected-volume/index.md
   - docs/user-guide/horizontal-pod-autoscaling/walkthrough.md
   - docs/user-guide/config-best-practices.md
   - docs/user-guide/working-with-resources.md
diff --git a/docs/user-guide/projected-volume/OWNERS b/docs/user-guide/projected-volume/OWNERS
new file mode 100644
index 0000000000..57c9a30c50
--- /dev/null
+++ b/docs/user-guide/projected-volume/OWNERS
@@ -0,0 +1,4 @@
+assignees:
+- jpeeler
+- pmorie
+
diff --git a/docs/user-guide/projected-volume/index.md b/docs/user-guide/projected-volume/index.md
new file mode 100644
index 0000000000..656e283d21
--- /dev/null
+++ b/docs/user-guide/projected-volume/index.md
@@ -0,0 +1,73 @@
+---
+assignees:
+- jpeeler
+- pmorie
+title: Using Projected volumes
+---
+
+The _projected volume_ is a volume that projects several existing volume sources
+into the same directory. Currently, one can project configmaps, downward API,
+and secrets. The resulting pod spec is also shorter when projecting to a single
+volume as opposed to multiple different locations. See [all-in-one volume design document](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/all-in-one-volume.md)
+for more information.
+
+* TOC
+{:toc}
+
+## Overview of a projected volume
+
+The projected volume encapsulates multiple volumes to be projected, with each
+volume source respecting nearly the same parameters as supported by each
+individual type. Consider the following example:
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: volume-test
+spec:
+  containers:
+  - name: container-test
+    image: busybox
+    volumeMounts:
+    - name: all-in-one
+      mountPath: "/projected-volume"
+      readOnly: true
+  volumes:
+  - name: all-in-one
+    projected:
+      sources:
+      - secret:
+          name: mysecret
+          items:
+            - key: username
+              path: my-group/my-username
+      - secret:
+          name: mysecret2
+          items:
+            - key: password
+              path: my-group/my-password
+              mode: 511
+```
+
+Each volume source is listed in the spec under `sources`. As stated above the
+parameters are nearly the same with two exceptions:
+
+* For secrets, the `secretName` field has been changed to `name` to be consistent
+with config maps naming.
+* The `defaultMode` can only be specified at the projected level and not for each
+volume source. However, as illustrated above, you can explicitly set the `mode`
+for each individual projection.
+
+## Creating projections
+
+A projected volume is created by passing in the pod spec to kubectl as normally
+done to create a new pod:
+```shell
+kubectl create -f podspec.yaml
+```
+
+## Restrictions
+
+Both secrets and config maps are required to be in the same namespace as the
+pod.