move user docs to their new home

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

@@ -0,0 +1,118 @@
+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
+
+<!-- BEGIN STRIP_FOR_RELEASE -->
+
+<h1>*** PLEASE NOTE: This document applies to the HEAD of the source
+tree only. If you are using a released version of Kubernetes, you almost
+certainly want the docs that go with that version.</h1>
+
+<strong>Documentation for specific releases can be found at
+[releases.k8s.io](http://releases.k8s.io).</strong>
+
+<!-- END STRIP_FOR_RELEASE -->
+
+<!-- END MUNGE: UNVERSIONED_WARNING -->
+# How To Use Persistent Volumes
+
+The purpose of this guide is to help you become familiar with Kubernetes Persistent Volumes.  By the end of the guide, we'll have
+nginx serving content from your persistent volume.
+
+This guide assumes knowledge of Kubernetes fundamentals and that you have a cluster up and running.
+
+## Provisioning
+
+A Persistent Volume (PV) in Kubernetes represents a real piece of underlying storage capacity in the infrastructure.  Cluster administrators
+must first create storage (create their Google Compute Engine (GCE) disks, export their NFS shares, etc.) in order for Kubernetes to mount it.
+
+PVs are intended for "network volumes" like GCE Persistent Disks, NFS shares, and AWS ElasticBlockStore volumes.  ```HostPath``` was included
+for ease of development and testing.  You'll create a local ```HostPath``` for this example.
+
+> IMPORTANT! For ```HostPath``` to work, you will need to run a single node cluster.  Kubernetes does not
+support local storage on the host at this time.  There is no guarantee your pod ends up on the correct node where the ```HostPath``` resides.
+
+  
+```
+
+// this will be nginx's webroot
+$ mkdir /tmp/data01
+$ echo 'I love Kubernetes storage!' > /tmp/data01/index.html
+
+```
+
+PVs are created by posting them to the API server.
+
+```
+$ kubectl create -f examples/persistent-volumes/volumes/local-01.yaml
+NAME      LABELS       CAPACITY      ACCESSMODES   STATUS      CLAIM     REASON
+pv0001    type=local   10737418240   RWO           Available 
+```
+
+## Requesting storage
+
+Users of Kubernetes request persistent storage for their pods.  They don't know how the underlying cluster is provisioned.
+They just know they can rely on their claim to storage and can manage its lifecycle independently from the many pods that may use it.  
+
+Claims must be created in the same namespace as the pods that use them.
+
+```
+
+$ kubectl create -f examples/persistent-volumes/claims/claim-01.yaml
+
+$ kubectl get pvc
+NAME                LABELS              STATUS              VOLUME
+myclaim-1           map[]                                   
+           
+           
+# A background process will attempt to match this claim to a volume.
+# The eventual state of your claim will look something like this:
+
+$ kubectl get pvc
+NAME        LABELS    STATUS    VOLUME
+myclaim-1   map[]     Bound     pv0001
+
+$ kubectl get pv
+NAME      LABELS       CAPACITY      ACCESSMODES   STATUS    CLAIM               REASON
+pv0001    type=local   10737418240   RWO           Bound     default/myclaim-1 
+```
+
+## Using your claim as a volume
+
+Claims are used as volumes in pods.  Kubernetes uses the claim to look up its bound PV.  The PV is then exposed to the pod.
+
+```
+$ kubectl create -f examples/persistent-volumes/simpletest/pod.yaml
+
+$ kubectl get pods
+NAME      READY     STATUS    RESTARTS   AGE
+mypod     1/1       Running   0          1h
+
+$ kubectl create -f examples/persistent-volumes/simpletest/service.json
+$ kubectl get services
+NAME              LABELS                                    SELECTOR            IP(S)        PORT(S)
+frontendservice   <none>                                    name=frontendhttp   10.0.0.241   3000/TCP
+kubernetes        component=apiserver,provider=kubernetes   <none>              10.0.0.2     443/TCP
+
+
+```
+
+## Next steps
+
+You should be able to query your service endpoint and see what content nginx is serving.  A "forbidden" error might mean you 
+need to disable SELinux (setenforce 0).
+
+```
+
+curl 10.0.0.241:3000
+I love Kubernetes storage!
+
+```
+
+Hopefully this simple guide is enough to get you started with PersistentVolumes.  If you have any questions, join
+```#google-containers``` on IRC and ask!
+
+Enjoy!
+
+
+<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
+[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/examples/persistent-volumes/README.md?pixel)]()
+<!-- END MUNGE: GENERATED_ANALYTICS -->

docs/user-guide/persistent-volumes/claims/claim-01.yaml

@@ -0,0 +1,10 @@
+kind: PersistentVolumeClaim
+apiVersion: v1
+metadata:
+  name: myclaim-1
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 3Gi

docs/user-guide/persistent-volumes/claims/claim-02.yaml

@@ -0,0 +1,10 @@
+kind: PersistentVolumeClaim
+apiVersion: v1
+metadata:
+  name: myclaim-2
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 8Gi

docs/user-guide/persistent-volumes/claims/claim-03.json

@@ -0,0 +1,17 @@
+{
+    "kind": "PersistentVolumeClaim",
+    "apiVersion": "v1",
+    "metadata": {
+        "name": "myclaim-3"
+    }, "spec": {
+        "accessModes": [
+            "ReadWriteOnce",
+            "ReadOnlyMany"
+        ],
+        "resources": {
+            "requests": {
+                "storage": "10G"
+            }
+        }
+    }
+}

docs/user-guide/persistent-volumes/simpletest/namespace.json

@@ -0,0 +1,10 @@
+{
+    "kind": "Namespace",
+    "apiVersion":"v1",
+    "metadata": {
+        "name": "myns",
+        "labels": {
+            "name": "development"
+        }
+    }
+}

docs/user-guide/persistent-volumes/simpletest/pod.yaml

@@ -0,0 +1,20 @@
+kind: Pod
+apiVersion: v1
+metadata:
+  name: mypod
+  labels:
+    name: frontendhttp
+spec:
+  containers:
+    - name: myfrontend
+      image: nginx
+      ports:
+        - containerPort: 80
+          name: "http-server"
+      volumeMounts:
+      - mountPath: "/var/www/html"
+        name: mypd
+  volumes:
+    - name: mypd
+      persistentVolumeClaim:
+       claimName: myclaim-1

docs/user-guide/persistent-volumes/simpletest/service.json

@@ -0,0 +1,19 @@
+{
+  "kind": "Service",
+  "apiVersion": "v1",
+  "metadata": {
+    "name": "frontendservice"
+  },
+  "spec": {
+    "ports": [
+      {
+        "protocol": "TCP",
+        "port": 3000,
+        "targetPort": "http-server"
+      }
+    ],
+    "selector": {
+      "name": "frontendhttp"
+    }
+  }
+}

docs/user-guide/persistent-volumes/volumes/gce.yaml

@@ -0,0 +1,13 @@
+kind: PersistentVolume
+apiVersion: v1
+metadata:
+  name: pv0003
+spec:
+  capacity:
+    storage: 10Gi
+  accessModes:
+    - ReadWriteOnce
+    - ReadOnlyMany
+  gcePersistentDisk:
+    pdName: "abc123"
+    fsType: "ext4"

docs/user-guide/persistent-volumes/volumes/local-01.yaml

@@ -0,0 +1,13 @@
+kind: PersistentVolume
+apiVersion: v1
+metadata:
+  name: pv0001
+  labels:
+    type: local
+spec:
+  capacity:
+    storage: 10Gi
+  accessModes:
+    - ReadWriteOnce
+  hostPath:
+    path: "/tmp/data01"

docs/user-guide/persistent-volumes/volumes/local-02.yaml

@@ -0,0 +1,14 @@
+kind: PersistentVolume
+apiVersion: v1
+metadata:
+  name: pv0002
+  labels:
+    type: local
+spec:
+  capacity:
+    storage: 8Gi
+  accessModes:
+    - ReadWriteOnce
+  hostPath:
+    path: "/tmp/data02"
+  persistentVolumeReclaimPolicy: Recycle

docs/user-guide/persistent-volumes/volumes/nfs.yaml

@@ -0,0 +1,12 @@
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: pv0003
+spec:
+  capacity:
+    storage: 5Gi
+  accessModes:
+    - ReadWriteOnce
+  nfs:
+    path: /tmp
+    server: 172.17.0.2