Consolidated examples into storage/ and volume/ folders

Search and replace for references to moved examples Reverted find and replace paths on auto gen docs Reverting changes to changelog Fix bugs in test-cmd.sh Fixed path in examples README ran update-all successfully Updated verify-flags exceptions to include renamed files
2025-09-17 15:13:08 +00:00 · 2016-06-21 15:43:29 -07:00
parent 04602bb9e5
commit fedc513658
137 changed files with 324 additions and 409 deletions
--- a/examples/volumes/nfs/README.md
+++ b/examples/volumes/nfs/README.md
@@ -0,0 +1,204 @@
+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
+
+<!-- BEGIN STRIP_FOR_RELEASE -->
+
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+
+<h2>PLEASE NOTE: This document applies to the HEAD of the source tree</h2>
+
+If you are using a released version of Kubernetes, you should
+refer to the docs that go with that version.
+
+<!-- TAG RELEASE_LINK, added by the munger automatically -->
+<strong>
+The latest release of this document can be found
+[here](http://releases.k8s.io/release-1.2/examples/volumes/nfs/README.md).
+
+Documentation for other releases can be found at
+[releases.k8s.io](http://releases.k8s.io).
+</strong>
+--
+
+<!-- END STRIP_FOR_RELEASE -->
+
+<!-- END MUNGE: UNVERSIONED_WARNING -->
+
+# Outline
+
+This example describes how to create Web frontend server, an auto-provisioned persistent volume on GCE, and an NFS-backed persistent claim.
+
+Demonstrated Kubernetes Concepts:
+
+* [Persistent Volumes](http://kubernetes.io/docs/user-guide/persistent-volumes/) to
+  define persistent disks (disk lifecycle not tied to the Pods).
+* [Services](http://kubernetes.io/docs/user-guide/services/) to enable Pods to
+  locate one another.
+
+![alt text][nfs pv example]
+
+As illustrated above, two persistent volumes are used in this example:
+
+- Web frontend Pod uses a persistent volume based on NFS server, and
+- NFS server uses an auto provisioned [persistent volume](http://kubernetes.io/docs/user-guide/persistent-volumes/) from GCE PD or AWS EBS.
+
+Note, this example uses an NFS container that doesn't support NFSv4.
+
+[nfs pv example]: nfs-pv.png
+
+
+## tl;dr Quickstart
+
+```console
+$ kubectl create -f examples/volumes/nfs/provisioner/nfs-server-gce-pv.yaml
+$ kubectl create -f examples/volumes/nfs/nfs-server-rc.yaml
+$ kubectl create -f examples/volumes/nfs/nfs-server-service.yaml
+# get the cluster IP of the server using the following command
+$ kubectl describe services nfs-server
+# use the NFS server IP to update nfs-pv.yaml and execute the following
+$ kubectl create -f examples/volumes/nfs/nfs-pv.yaml
+$ kubectl create -f examples/volumes/nfs/nfs-pvc.yaml
+# run a fake backend
+$ kubectl create -f examples/volumes/nfs/nfs-busybox-rc.yaml
+# get pod name from this command
+$ kubectl get pod -l name=nfs-busybox
+# use the pod name to check the test file
+$ kubectl exec nfs-busybox-jdhf3 -- cat /mnt/index.html
+```
+
+## Example of NFS based persistent volume
+
+See [NFS Service and Replication Controller](nfs-web-rc.yaml) for a quick example of how to use an NFS
+volume claim in a replication controller. It relies on the
+[NFS persistent volume](nfs-pv.yaml) and
+[NFS persistent volume claim](nfs-pvc.yaml) in this example as well.
+
+## Complete setup
+
+The example below shows how to export a NFS share from a single pod replication
+controller and import it into two replication controllers.
+
+### NFS server part
+
+Define [the NFS Service and Replication Controller](nfs-server-rc.yaml) and
+[NFS service](nfs-server-service.yaml):
+
+The NFS server exports an an auto-provisioned persistent volume backed by GCE PD:
+
+```console
+$ kubectl create -f examples/volumes/nfs/provisioner/nfs-server-gce-pv.yaml
+```
+
+```console
+$ kubectl create -f examples/volumes/nfs/nfs-server-rc.yaml
+$ kubectl create -f examples/volumes/nfs/nfs-server-service.yaml
+```
+
+The directory contains dummy `index.html`. Wait until the pod is running
+by checking `kubectl get pods -l role=nfs-server`.
+
+### Create the NFS based persistent volume claim
+
+The [NFS busybox controller](nfs-busybox-rc.yaml) uses a simple script to
+generate data written to the NFS server we just started. First, you'll need to
+find the cluster IP of the server:
+
+```console
+$ kubectl describe services nfs-server
+```
+
+Replace the invalid IP in the [nfs PV](nfs-pv.yaml). (In the future,
+we'll be able to tie these together using the service names, but for
+now, you have to hardcode the IP.)
+
+Create the the [persistent volume](../../../docs/user-guide/persistent-volumes.md)
+and the persistent volume claim for your NFS server. The persistent volume and
+claim gives us an indirection that allow multiple pods to refer to the NFS
+server using a symbolic name rather than the hardcoded server address.
+
+```console
+$ kubectl create -f examples/volumes/nfs/nfs-pv.yaml
+$ kubectl create -f examples/volumes/nfs/nfs-pvc.yaml
+```
+
+## Setup the fake backend
+
+The [NFS busybox controller](nfs-busybox-rc.yaml) updates `index.html` on the
+NFS server every 10 seconds. Let's start that now:
+
+```console
+$ kubectl create -f examples/volumes/nfs/nfs-busybox-rc.yaml
+```
+
+Conveniently, it's also a `busybox` pod, so we can get an early check
+that our mounts are working now. Find a busybox pod and exec:
+
+```console
+$ kubectl get pod -l name=nfs-busybox
+NAME                READY     STATUS    RESTARTS   AGE
+nfs-busybox-jdhf3   1/1       Running   0          25m
+nfs-busybox-w3s4t   1/1       Running   0          25m
+$ kubectl exec nfs-busybox-jdhf3 -- cat /mnt/index.html
+Thu Oct 22 19:20:18 UTC 2015
+nfs-busybox-w3s4t
+```
+
+You should see output similar to the above if everything is working well. If
+it's not, make sure you changed the invalid IP in the [NFS PV](nfs-pv.yaml) file
+and make sure the `describe services` command above had endpoints listed
+(indicating the service was associated with a running pod).
+
+### Setup the web server
+
+The [web server controller](nfs-web-rc.yaml) is an another simple replication
+controller demonstrates reading from the NFS share exported above as a NFS
+volume and runs a simple web server on it.
+
+Define the pod:
+
+```console
+$ kubectl create -f examples/volumes/nfs/nfs-web-rc.yaml
+```
+
+This creates two pods, each of which serve the `index.html` from above. We can
+then use a simple service to front it:
+
+```console
+kubectl create -f examples/volumes/nfs/nfs-web-service.yaml
+```
+
+We can then use the busybox container we launched before to check that `nginx`
+is serving the data appropriately:
+
+```console
+$ kubectl get pod -l name=nfs-busybox
+NAME                READY     STATUS    RESTARTS   AGE
+nfs-busybox-jdhf3   1/1       Running   0          1h
+nfs-busybox-w3s4t   1/1       Running   0          1h
+$ kubectl get services nfs-web
+NAME      LABELS    SELECTOR            IP(S)        PORT(S)
+nfs-web   <none>    role=web-frontend   10.0.68.37   80/TCP
+$ kubectl exec nfs-busybox-jdhf3 -- wget -qO- http://10.0.68.37
+Thu Oct 22 19:28:55 UTC 2015
+nfs-busybox-w3s4t
+```
+
+
+
+
+<!-- BEGIN MUNGE: IS_VERSIONED -->
+<!-- TAG IS_VERSIONED -->
+<!-- END MUNGE: IS_VERSIONED -->
+
+
+<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
+[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/examples/volumes/nfs/README.md?pixel)]()
+<!-- END MUNGE: GENERATED_ANALYTICS -->
--- a/examples/volumes/nfs/nfs-busybox-rc.yaml
+++ b/examples/volumes/nfs/nfs-busybox-rc.yaml
@@ -0,0 +1,32 @@
+# This mounts the nfs volume claim into /mnt and continuously
+# overwrites /mnt/index.html with the time and hostname of the pod.
+
+apiVersion: v1
+kind: ReplicationController
+metadata:
+  name: nfs-busybox
+spec:
+  replicas: 2
+  selector:
+    name: nfs-busybox
+  template:
+    metadata:
+      labels:
+        name: nfs-busybox
+    spec:
+      containers:
+      - image: busybox
+        command:
+          - sh
+          - -c
+          - 'while true; do date > /mnt/index.html; hostname >> /mnt/index.html; sleep $(($RANDOM % 5 + 5)); done'
+        imagePullPolicy: IfNotPresent
+        name: busybox
+        volumeMounts:
+          # name must match the volume name below
+          - name: nfs
+            mountPath: "/mnt"
+      volumes:
+      - name: nfs
+        persistentVolumeClaim:
+          claimName: nfs
--- a/examples/volumes/nfs/nfs-data/Dockerfile
+++ b/examples/volumes/nfs/nfs-data/Dockerfile
@@ -0,0 +1,26 @@
+# Copyright 2016 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+FROM centos
+MAINTAINER Jan Safranek, jsafrane@redhat.com; Huamin Chen, hchen@redhat.com
+RUN yum -y install /usr/bin/ps nfs-utils && yum clean all
+RUN mkdir -p /exports
+ADD run_nfs.sh /usr/local/bin/
+ADD index.html /tmp/index.html
+RUN chmod 644 /tmp/index.html
+
+# expose mountd 20048/tcp and nfsd 2049/tcp and rpcbind 111/tcp
+EXPOSE 2049/tcp 20048/tcp 111/tcp 111/udp
+
+ENTRYPOINT ["/usr/local/bin/run_nfs.sh", "/exports"]
--- a/examples/volumes/nfs/nfs-data/README.md
+++ b/examples/volumes/nfs/nfs-data/README.md
@@ -0,0 +1,42 @@
+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
+
+<!-- BEGIN STRIP_FOR_RELEASE -->
+
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
+     width="25" height="25">
+
+<h2>PLEASE NOTE: This document applies to the HEAD of the source tree</h2>
+
+If you are using a released version of Kubernetes, you should
+refer to the docs that go with that version.
+
+Documentation for other releases can be found at
+[releases.k8s.io](http://releases.k8s.io).
+</strong>
+--
+
+<!-- END STRIP_FOR_RELEASE -->
+
+<!-- END MUNGE: UNVERSIONED_WARNING -->
+
+# NFS-exporter container with a file
+
+This container exports /exports with index.html in it via NFS. Based on
+../exports. Since some Linux kernels have issues running NFSv4 daemons in containers,
+only NFSv3 is opened in this container.
+
+Available as `gcr.io/google-samples/nfs-server`
+
+
+
+<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
+[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/examples/volumes/nfs/nfs-data/README.md?pixel)]()
+<!-- END MUNGE: GENERATED_ANALYTICS -->
--- a/examples/volumes/nfs/nfs-data/index.html
+++ b/examples/volumes/nfs/nfs-data/index.html
@@ -0,0 +1 @@
+Hello world!
--- a/examples/volumes/nfs/nfs-data/run_nfs.sh
+++ b/examples/volumes/nfs/nfs-data/run_nfs.sh
@@ -0,0 +1,72 @@
+#!/bin/bash
+
+# Copyright 2015 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+function start()
+{
+
+    # prepare /etc/exports
+    for i in "$@"; do
+        # fsid=0: needed for NFSv4
+        echo "$i *(rw,fsid=0,insecure,no_root_squash)" >> /etc/exports
+        # move index.html to here
+        /bin/cp /tmp/index.html $i/
+        chmod 644 $i/index.html
+        echo "Serving $i"
+    done
+  
+    # start rpcbind if it is not started yet
+    /usr/sbin/rpcinfo 127.0.0.1 > /dev/null; s=$?
+    if [ $s -ne 0 ]; then
+       echo "Starting rpcbind"
+       /usr/sbin/rpcbind -w
+    fi
+
+    mount -t nfsd nfds /proc/fs/nfsd
+
+    # -N 4.x: disable NFSv4
+    # -V 3: enable NFSv3
+    /usr/sbin/rpc.mountd -N 2 -V 3 -N 4 -N 4.1
+
+    /usr/sbin/exportfs -r
+    # -G 10 to reduce grace time to 10 seconds (the lowest allowed)
+    /usr/sbin/rpc.nfsd -G 10 -N 2 -V 3 -N 4 -N 4.1 2
+    /usr/sbin/rpc.statd --no-notify
+    echo "NFS started"
+}
+
+function stop()
+{
+    echo "Stopping NFS"
+
+    /usr/sbin/rpc.nfsd 0
+    /usr/sbin/exportfs -au
+    /usr/sbin/exportfs -f
+
+    kill $( pidof rpc.mountd )
+    umount /proc/fs/nfsd
+    echo > /etc/exports
+    exit 0
+}
+
+
+trap stop TERM
+
+start "$@"
+
+# Ugly hack to do nothing and wait for SIGTERM
+while true; do
+    sleep 5
+done
--- a/examples/volumes/nfs/nfs-pv.png
+++ b/examples/volumes/nfs/nfs-pv.png
--- a/examples/volumes/nfs/nfs-pv.yaml
+++ b/examples/volumes/nfs/nfs-pv.yaml
@@ -0,0 +1,13 @@
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: nfs
+spec:
+  capacity:
+    storage: 1Mi
+  accessModes:
+    - ReadWriteMany
+  nfs:
+    # FIXME: use the right IP
+    server: 10.244.1.4
+    path: "/exports"
--- a/examples/volumes/nfs/nfs-pvc.yaml
+++ b/examples/volumes/nfs/nfs-pvc.yaml
@@ -0,0 +1,10 @@
+kind: PersistentVolumeClaim
+apiVersion: v1
+metadata:
+  name: nfs
+spec:
+  accessModes:
+    - ReadWriteMany
+  resources:
+    requests:
+      storage: 1Mi
--- a/examples/volumes/nfs/nfs-server-rc.yaml
+++ b/examples/volumes/nfs/nfs-server-rc.yaml
@@ -0,0 +1,32 @@
+apiVersion: v1
+kind: ReplicationController
+metadata:
+  name: nfs-server
+spec:
+  replicas: 1
+  selector:
+    role: nfs-server
+  template:
+    metadata:
+      labels:
+        role: nfs-server
+    spec:
+      containers:
+      - name: nfs-server
+        image: gcr.io/google-samples/nfs-server:1.1
+        ports:
+          - name: nfs
+            containerPort: 2049
+          - name: mountd
+            containerPort: 20048
+          - name: rpcbind
+            containerPort: 111
+        securityContext:
+          privileged: true
+        volumeMounts:
+          - mountPath: /exports
+            name: mypvc
+      volumes:
+        - name: mypvc
+          persistentVolumeClaim:
+            claimName: nfs-pv-provisioning-demo
--- a/examples/volumes/nfs/nfs-server-service.yaml
+++ b/examples/volumes/nfs/nfs-server-service.yaml
@@ -0,0 +1,14 @@
+kind: Service
+apiVersion: v1
+metadata:
+  name: nfs-server
+spec:
+  ports:
+    - name: nfs
+      port: 2049
+    - name: mountd
+      port: 20048
+    - name: rpcbind
+      port: 111
+  selector:
+    role: nfs-server
--- a/examples/volumes/nfs/nfs-web-rc.yaml
+++ b/examples/volumes/nfs/nfs-web-rc.yaml
@@ -0,0 +1,30 @@
+# This pod mounts the nfs volume claim into /usr/share/nginx/html and
+# serves a simple web page.
+
+apiVersion: v1
+kind: ReplicationController
+metadata:
+  name: nfs-web
+spec:
+  replicas: 2
+  selector:
+    role: web-frontend
+  template:
+    metadata:
+      labels:
+        role: web-frontend
+    spec:
+      containers:
+      - name: web
+        image: nginx
+        ports:
+          - name: web
+            containerPort: 80
+        volumeMounts:
+            # name must match the volume name below
+            - name: nfs
+              mountPath: "/usr/share/nginx/html"
+      volumes:
+      - name: nfs
+        persistentVolumeClaim:
+          claimName: nfs
--- a/examples/volumes/nfs/nfs-web-service.yaml
+++ b/examples/volumes/nfs/nfs-web-service.yaml
@@ -0,0 +1,9 @@
+kind: Service
+apiVersion: v1
+metadata:
+  name: nfs-web
+spec:
+  ports:
+    - port: 80
+  selector:
+    role: web-frontend
--- a/examples/volumes/nfs/provisioner/nfs-server-gce-pv.yaml
+++ b/examples/volumes/nfs/provisioner/nfs-server-gce-pv.yaml
@@ -0,0 +1,13 @@
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: nfs-pv-provisioning-demo
+  labels:
+    demo: nfs-pv-provisioning
+  annotations:
+    volume.alpha.kubernetes.io/storage-class: any
+spec:
+  accessModes: [ "ReadWriteOnce" ]
+  resources:
+    requests:
+      storage: 200Gi