Change:
(Note: the syntax of volumeID is currently awkward; #10181 fixes it) <del> ### NFS </del> <ins> ### nfs An `nfs` volume allows an existing NFS (Network File System) share to be mounted into your pod. Unlike `emptyDir`, which is erased when a Pod is removed, the contents of an `nfs` volume are preserved and the volume is merely unmounted.  This means that an NFS volume can be pre-populated with data, and that data can be "handed off" between pods.  NFS can be mounted by multiple writers simultaneuosly. __Important: You must have your own NFS server running with the share exported before you can use it__ See the [NFS example](../examples/nfs/) for more details. For example, [this file](../examples/nfs/nfs-web-pod.yaml) demonstrates how to specify the usage of an NFS volume within a pod. </ins> <del> Kubernetes NFS volumes allow an existing NFS share to be made available to containers within a pod. </del> <ins> In this example one can see that a `volumeMount` called "nfs" is being mounted onto `/var/www/html` in the container "web".  The volume "nfs" is defined as type `nfs`, with the NFS server serving from `nfs-server.default.kube.local` and exporting directory `/` as the share.  The mount being created in this example is writeable. </ins> <del> See the [NFS Pod examples](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/examples/nfs/) section for more details. For example, [nfs-web-pod.yaml](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/examples/nfs/nfs-web-pod.yaml) demonstrates how to specify the usage of an NFS volume within a pod. In this example one can see that a `volumeMount` called "nfs" is being mounted onto `/var/www/html` in the container "web". The volume "nfs" is defined as type `nfs`, with the NFS server serving from `nfs-server.default.kube.local` and exporting directory `/` as the share. The mount being created in this example is not read only. </del> <ins> ### iscsi An `iscsi` volume allows an existing iSCSI (SCSI over IP) volume to be mounted into your pod.  Unlike `emptyDir`, which is erased when a Pod is removed, the contents of an `iscsi` volume are preserved and the volume is merely unmounted.  This means that an iscsi volume can be pre-populated with data, and that data can be "handed off" between pods. __Important: You must have your own iSCSI server running with the volume created before you can use it__ A feature of iSCSI is that it can be mounted as read-only by multiple consumers simultaneously.  This means that you can pre-populate a volume with your dataset and then serve it in parallel from as many pods as you need.  Unfortunately, iSCSI volumes can only be mounted by a single consumer in read-write mode - no simultaneous readers allowed. See the [iSCSI example](../examples/iscsi/) for more details. ### glusterfs A `glusterfs` volume allows an [Glusterfs](http://www.gluster.org) (an open source networked filesystem) volume to be mounted into your pod.  Unlike `emptyDir`, which is erased when a Pod is removed, the contents of a `glusterfs` volume are preserved and the volume is merely unmounted.  This means that a glusterfs volume can be pre-populated with data, and that data can be "handed off" between pods.  GlusterFS can be mounted by multiple writers simultaneuosly. __Important: You must have your own GlusterFS installation running before you can use it__ See the [GlusterFS example](../examples/glusterfs/) for more details. ### rbd An `rbd` volume allows a [Rados Block Device](http://ceph.com/docs/master/rbd/rbd/) volume to be mounted into your pod.  Unlike `emptyDir`, which is erased when a Pod is removed, the contents of an `rbd` volume are preserved and the volume is merely unmounted.  This means that a glusterfs volume can be pre-populated with data, and that data can be "handed off" between pods. __Important: You must have your own Ceph installation running before you can use RBD__ A feature of RBD is that it can be mounted as read-only by multiple consumers simultaneously.  This means that you can pre-populate a volume with your dataset and then serve it in parallel from as many pods as you need.  Unfortunately, RBD volumes can only be mounted by a single consumer in read-write mode - no simultaneous readers allowed. See the [RBD example](../examples/rbd/) for more details. ### gitRepo A `gitRepo` volume is an example of what can be done as a volume plugin.  It mounts an empty directory and clones a git repository into it for your pod to use.  In the future, such volumes may be moved to an even more decoupled model, rather than extending the Kubernetes API for every such use case. </ins> ### Secrets <del> Secret volumes are used to pass sensitive information, such as passwords, to pods that mount these volumes. Secrets are described [here](secrets.md). </del> <ins> A `secret` volume is used to pass sensitive information, such as passwords, to pods.  You can store secrets in the Kubernetes API and mount them as files for use by pods without coupling to Kubernetes directly.  `secret` volumes are backed by tmpfs (a RAM-backed filesystem) so they are never written to non-volatile storage. __Important: You must create a secret in the Kubernetes API before you can use it__ Secrets are described in more detail [here](secrets.md). ### persistentVolumeClaim A `persistentVolumeClaim` volume is used to mount a [PersistentVolume](persistent-volumes.md) into a pod.  PersistentVolumes are a way for users to "claim" durable storage (such as a GCE PersistentDisk or an iSCSI volume) without knowing the details of the particular cloud environment. See the [PersistentVolumes example](../examples/persistent-volumes/) for more details. </ins> ## Resources <del> The storage media (Disk, SSD, or memory) of an EmptyDir volume is determined by the media of the filesystem holding the kubelet root dir (typically `/var/lib/kubelet`). There is no limit on how much space an EmptyDir or HostPath volume can consume, and no isolation between containers or between pods. </del> <ins> The storage media (Disk, SSD, etc) of an `emptyDir` volume is determined by the medium of the filesystem holding the kubelet root dir (typically `/var/lib/kubelet`).  There is no limit on how much space an `emptyDir` or `hostPath` volume can consume, and no isolation between containers or between pods. In the future, we expect that `emptyDir` and `hostPath` volumes will be able to request a certain amount of space using a [resource](./compute_resources.md) specification, and to select the type of media to use, for clusters that have several media types. </ins> <del> In the future, we expect that EmptyDir and HostPath volumes will be able to request a certain amount of space using a [compute resource](./compute_resources.md) specification, and to select the type of media to use, for clusters that have several media types. </del> [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/volumes.md?pixel)]()

Discussion:
only talks about these volumes: EmptyDir HostPath GCEPersistentDisk NFS However, we many more volume types. Documentation should be updated to reflect this.
cc
Is anyone working on this? If not, I would like to do it.
go for it :) Improving PV docs is on my TODO list, too.
Sure, thank you. I will start now, hope to send a PR ASAP.