Merge pull request #938 from wongma7/sg

Document persistentvolume gid annotation

docs/user-guide/persistent-volumes/walkthrough.md

@@ -40,6 +40,34 @@ NAME      LABELS       CAPACITY      ACCESSMODES   STATUS      CLAIM     REASON
 pv0001    type=local   10737418240   RWO           Available 
 ```
 
+### Access Control
+Storage configured with GID will only allow writing by pods using the same GID.
+Mismatched or missing GIDs will cause `permission denied` errors. Annotating a
+`PersistentVolume` with a GID allows `Kubelet` to automatically add the GID to
+the pod that requires it. No coordination between an admin and end user is 
+required.
+
+To annotate the volume's with a GID you use the `pv.beta.kubernetes.io/gid`
+annotation as follows:
+
+```yaml
+kind: PersistentVolume
+apiVersion: v1
+metadata:
+  name: pv1
+  annotations:
+    pv.beta.kubernetes.io/gid: "1234"
+#...
+```
+
+When a pod consumes a PV with a GID annotation, the annotated GID is applied to
+all containers in the pod in the same way GIDs specified in the pod's 
+[security context](/docs/user-guide/security-context/) are. Every GID, whether
+it originates from a PV annotation or the pod's specification, is applied to
+the first process run in each container, in addition to the container's primary
+GID. Currently, the GIDs associated with PVs a pod consumes will not be present
+on the pod resource itself, unlike GIDs specified in a pod's security context.
+
 ## Requesting storage
 
 Users of Kubernetes request persistent storage for their pods.  They don't know how the underlying cluster is provisioned.