WTD: Projected volumes (#3856)

* Update projected volume task

- Rename file
- Build out steps
- Create separate yaml file for pod configuration
- Add new page to the sidenav

* Add projected volume type to volumes concept page

_data/tasks.yml

@@ -13,7 +13,7 @@ toc:
   - docs/tasks/configure-pod-container/assign-cpu-ram-container.md
   - docs/tasks/configure-pod-container/configure-volume-storage.md
   - docs/tasks/configure-pod-container/configure-persistent-volume-storage.md
-  - docs/tasks/configure-pod-container/projected-volume.md
+  - docs/tasks/configure-pod-container/configure-projected-volume-storage.md
   - docs/tasks/configure-pod-container/configure-service-account.md
   - docs/tasks/configure-pod-container/pull-image-private-registry.md
   - docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md

docs/concepts/storage/volumes.md

@@ -82,6 +82,7 @@ Kubernetes supports several types of Volumes:
    * `secret`
    * `persistentVolumeClaim`
    * `downwardAPI`
+   * `projected`
    * `azureFileVolume`
    * `azureDisk`
    * `vsphereVolume`
@@ -441,6 +442,99 @@ It mounts a directory and writes the requested data in plain text files.
 
 See the [`downwardAPI` volume example](/docs/tasks/configure-pod-container/downward-api-volume-expose-pod-information/)  for more details.
 
+### projected
+
+A `projected` volume maps several existing volume sources into the same directory.
+
+Currently, the following types of volume sources can be projected:
+
+- [`secret`](#secret)
+- [`downwardAPI`](#downardapi)
+- `configMap`
+
+All sources are required to be in the same namespace as the pod. For more details, see the [all-in-one volume design document](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/all-in-one-volume.md).
+
+#### Example pod with a secret, a downward API, and a configmap
+
+```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
+      - downwardAPI:
+          items:
+            - path: "labels"
+              fieldRef:
+                fieldPath: metadata.labels
+            - path: "cpu_limit"
+              resourceFieldRef:
+                containerName: container-test
+                resource: limits.cpu
+      - configMap:
+          name: myconfigmap
+          items:
+            - key: config
+              path: my-group/my-config
+```
+
+#### Example pod with multiple secrets with a non-default permission mode set
+
+```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 projected volume source is listed in the spec under `sources`. 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.
+
 ### FlexVolume
 
 A `FlexVolume` enables users to mount vendor volumes into a pod. It expects vendor
@@ -464,7 +558,7 @@ More details can be found [here](https://github.com/kubernetes/kubernetes/tree/{
 
 ### vsphereVolume
 
-__Prerequisite: Kubernetes with vSphere Cloud Provider configured. 
+__Prerequisite: Kubernetes with vSphere Cloud Provider configured.
 For cloudprovider configuration please refer [vSphere getting started guide](http://kubernetes.io/docs/getting-started-guides/vsphere/).__
 
 A `vsphereVolume` is used to mount a vSphere VMDK Volume into your Pod.  The contents
@@ -475,7 +569,7 @@ __Important: You must create VMDK using one of the following method before using
 #### Creating a VMDK volume
 
 * Create using vmkfstools.
-   
+
    First ssh into ESX and then use following command to create vmdk,
 
 ```shell
@@ -553,9 +647,9 @@ __Important: Make sure you have an existing PortworxVolume with name `pxvol` bef
 More details and examples can be found [here](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/examples/volumes/portworx/README.md)
 
 ### ScaleIO
-ScaleIO is a software-based storage platform that can use existing hardware to create clusters of scalable 
+ScaleIO is a software-based storage platform that can use existing hardware to create clusters of scalable
-shared block networked storage.  The ScaleIO volume plugin allows deployed pods to access existing ScaleIO 
+shared block networked storage.  The ScaleIO volume plugin allows deployed pods to access existing ScaleIO
-volumes (or it can dynamically provision new volumes for persistent volume claims, see 
+volumes (or it can dynamically provision new volumes for persistent volume claims, see
 [ScaleIO Persistent Volumes](/docs/user-guide/persistent-volumes/#scaleio)).
 
 __Important: You must have an existing ScaleIO cluster already setup and running with the volumes created

docs/tasks/configure-pod-container/configure-projected-volume-storage.md

@@ -0,0 +1,67 @@
+---
+assignees:
+- jpeeler
+- pmorie
+title: Configuring a Pod to Use a Projected Volume for Storage
+redirect_from:
+- "/docs/tasks/configure-pod-container/projected-volume/"
+- "/docs/user-guide/projected-volume/"
+- "/docs/user-guide/projected-volume/index.html"
+---
+
+{% capture overview %}
+This page shows how to use a [`projected`](/docs/concepts/storage/volumes/#projected) volume to mount several existing volume sources into the same directory. Currently, `secret`, `configMap`, and `downwardAPI` volumes can be projected.
+{% endcapture %}
+
+{% capture prerequisites %}
+{% include task-tutorial-prereqs.md %}
+{% endcapture %}
+
+{% capture steps %}
+## Configure a projected volume for a pod
+
+In this exercise, you create username and password Secrets from local files. You then create a Pod that runs one Container, using a [`projected`](/docs/concepts/storage/volumes/#projected) Volume to mount the Secrets into the same shared directory.
+
+Here is the configuration file for the Pod:
+
+{% include code.html language="yaml" file="projected-volume.yaml" ghlink="/docs/tasks/configure-pod-container/projected-volume.yaml" %}
+
+1. Create the Secrets:
+
+        # Create files containing the username and password:
+        echo -n "admin" > ./username.txt
+        echo -n "1f2d1e2e67df" > ./password.txt
+
+        # Package these files into secrets:
+        kubectl create secret generic user --from-file=./username.txt
+        kubectl create secret generic pass --from-file=./password.txt
+
+1. Create the Pod:
+
+        kubectl create -f projected-volume.yaml
+
+1. Verify that the Pod's Container is running, and then watch for changes to
+the Pod:
+
+        kubectl get --watch pod test-projected-volume
+
+    The output looks like this:
+
+        NAME                    READY     STATUS    RESTARTS   AGE
+        test-projected-volume   1/1       Running   0          14s
+
+1. In another terminal, get a shell to the running Container:
+
+        kubectl exec -it test-projected-volume -- /bin/sh
+
+1. In your shell, verify that the `projected-volumes` directory contains your projected sources:
+
+        / # ls projected-volumes/
+{% endcapture %}
+
+{% capture whatsnext %}
+* Learn more about [`projected`](/docs/concepts/storage/volumes/#projected) volumes.
+* Read the the [all-in-one volume](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/all-in-one-volume.md) design document.
+{% endcapture %}
+
+{% include templates/task.md %}

docs/tasks/configure-pod-container/projected-volume.md

@@ -1,76 +0,0 @@
----
-assignees:
-- jpeeler
-- pmorie
-title: Configuring a Pod to Use a Projected Volume for Storage
-redirect_from:
-- "/docs/user-guide/projected-volume/"
-- "/docs/user-guide/projected-volume/index.html"
----
-
-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.

docs/tasks/configure-pod-container/projected-volume.yaml

@@ -0,0 +1,23 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: test-projected-volume
+spec:
+  containers:
+  - name: test-projected-volume
+    image: busybox
+    args:
+    - sleep
+    - "86400"
+    volumeMounts:
+    - name: all-in-one
+      mountPath: "/projected-volume"
+      readOnly: true
+  volumes:
+  - name: all-in-one
+    projected:
+      sources:
+      - secret:
+          name: user
+      - secret:
+          name: pass