From 591adaffe5c84077bdea8a5671299ff76f4e40d9 Mon Sep 17 00:00:00 2001 From: steveperry-53 Date: Tue, 17 Jan 2017 12:04:57 -0800 Subject: [PATCH] Write new Task: Configuring a Pod to use a PersistentVolume. --- _data/tasks.yml | 1 + .../configure-persistent-volume-storage.md | 211 ++++++++++++++++++ .../task-pv-claim.yaml | 10 + .../configure-pod-container/task-pv-pod.yaml | 22 ++ .../task-pv-volume.yaml | 13 ++ 5 files changed, 257 insertions(+) create mode 100644 docs/tasks/configure-pod-container/configure-persistent-volume-storage.md create mode 100644 docs/tasks/configure-pod-container/task-pv-claim.yaml create mode 100644 docs/tasks/configure-pod-container/task-pv-pod.yaml create mode 100644 docs/tasks/configure-pod-container/task-pv-volume.yaml diff --git a/_data/tasks.yml b/_data/tasks.yml index 231a583524..de066c9ed2 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -9,6 +9,7 @@ toc: - docs/tasks/configure-pod-container/define-command-argument-container.md - 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/distribute-credentials-secure.md - docs/tasks/configure-pod-container/pull-image-private-registry.md - docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md diff --git a/docs/tasks/configure-pod-container/configure-persistent-volume-storage.md b/docs/tasks/configure-pod-container/configure-persistent-volume-storage.md new file mode 100644 index 0000000000..95065e7a93 --- /dev/null +++ b/docs/tasks/configure-pod-container/configure-persistent-volume-storage.md @@ -0,0 +1,211 @@ +--- +redirect_from: +- "/docs/user-guide/persistent-volumes/walkthrough/" +- "/docs/user-guide/persistent-volumes/walkthrough.html" +title: Configuring a Pod to Use a PersistentVolume for Storage +--- + +{% capture overview %} + +This page shows how to configure a Pod to use a PersistentVolumeClaim for storage. +Here is a summary of the process: + +1. A cluster administrator creates a PersistentVolume that is backed by physical +storage. The administrator does not associate the volume with any Pod. + +1. A cluster user creates a PersistentVolumeClaim, which gets automatically +bound to a suitable PersistentVolume. + +1. The user creates a Pod that uses the PersistentVolumeClaim as storage. + +{% endcapture %} + +{% capture prerequisites %} + +* You need to have a Kubernetes cluster that has only one Node, and the kubectl +command-line tool must be configured to communicate with your cluster. If you +do not already have a single-node cluster, you can create one by using +[Minikube](/docs/getting-started-guides/minikube). + +* Familiarize yourself with the material in +[Persistent Volumes](/docs/user-guide/persistent-volumes/). + +{% endcapture %} + +{% capture steps %} + +## Creating an index.html file on your Node + +Open a shell to the Node in your cluster. How you open a shell depends on how +you set up your cluster. For example, if you are using Minikube, you can open a +shell to your Node by entering `minikube ssh`. + +In your shell, create a `/tmp/data` directory: + + mkdir /tmp/data + +In the `/tmp/data` directory, create an `index.html` file: + + echo 'Hello from Kubernetes storage' > /tmp/data/index.html + +## Creating a PersistentVolume + +In this exercise, you create a *hostPath* PersistentVolume. Kubernetes supports +hostPath for development and testing on a single-node cluster. A hostPath +PersistentVolume uses a file or directory on the Node to emulate network-attached storage. + +In a production cluster, you would not use hostPath. Instead a cluster administrator +would provision a network resource like a Google Compute Engine persistent disk, +an NFS share, or an Amazon Elastic Block Store volume. Cluster administrators can also +use [StorageClasses](/docs/resources-reference/v1.5/#storageclass-v1beta1) +to set up +[dynamic provisioning](http://blog.kubernetes.io/2016/10/dynamic-provisioning-and-storage-in-kubernetes.html). + +Here is the configuration file for the hostPath PersistentVolume: + +{% include code.html language="yaml" file="task-pv-volume.yaml" ghlink="/docs/tasks/configure-pod-container/task-pv-volume.yaml" %} + +The configuration file specifies that the volume is at `/tmp/data` on the +the cluster's Node. The configuration also specifies a size of 10 gibibytes and +an access mode of `ReadWriteOnce`, which means the volume can be mounted as +read-write by a single Node. + +Create the PersistentVolume: + + kubectl create -f http://k8s.io/docs/tasks/configure-pod-container/task-pv-volume.yaml + +View information about the PersistentVolume: + + kubectl get pv task-pv-volume + +The output shows that the PersistentVolume has a `STATUS` of `Available`. This +means it has not yet been bound to a PersistentVolumeClaim. + + NAME CAPACITY ACCESSMODES RECLAIMPOLICY STATUS CLAIM REASON AGE + task-pv-volume 10Gi RWO Retain Available 17s + + +## Creating a PersistentVolumeClaim + +The next step is to create a PersistentVolumeClaim. Pods use PersistentVolumeClaims +to request physical storage. In this exercise, you create a PersistentVolumeClaim +that requests a volume of at least three gibibytes that can provide read-write +access for at least one Node. + +Here is the configuration file for the PersistentVolumeClaim: + +{% include code.html language="yaml" file="task-pv-claim.yaml" ghlink="/docs/tasks/configure-pod-container/task-pv-claim.yaml" %} + +Create the PersistentVolumeClaim: + + kubectl create -f http://k8s.io/docs/tasks/configure-pod-container/task-pv-claim.yaml + +After you create the PersistentVolumeClaim, the Kubernetes control plane looks +for a PersistentVolume that satisfies the claim's requirements. If the control +plane finds a suitable PersistentVolume, it binds the claim to the volume. + +Look again at the PersistentVolume: + + kubectl get pv task-pv-volume + +Now the output shows a `STATUS` of `Bound`. + + kubectl get pv task-pv-volume + NAME CAPACITY ACCESSMODES RECLAIMPOLICY STATUS CLAIM REASON AGE + task-pv-volume 10Gi RWO Retain Bound default/task-pv-claim 8m + +Look at the PersistentVolumeClaim: + + kubectl get pvc task-pv-claim + +The output shows that the PersistentVolumeClaim is bound to your PersistentVolume, +`task-pv-volume`. + + NAME STATUS VOLUME CAPACITY ACCESSMODES AGE + task-pv-claim Bound task-pv-volume 10Gi RWO 5s + +## Creating a Pod + +The next step is to create a Pod that uses your PersistentVolumeClaim as a volume. + +Here is the configuration file for the Pod: + +{% include code.html language="yaml" file="task-pv-pod.yaml" ghlink="/docs/tasks/configure-pod-container/task-pv-pod.yaml" %} + +Notice that the Pod's configuration file specifies a PersistentVolumeClaim, but +it does not specify a PersistentVolume. From the Pod's point of view, the claim +is a volume. + +Create the Pod: + + kubectl create -f http://k8s.io/docs/tasks/configure-pod-container/task-pv-pod.yaml + +Verify that the Container in the Pod is running; + + kubectl get pod task-pv-pod + +Get a shell to the Container running in your Pod: + + kubectl exec -it task-pv-pod -- /bin/bash + +In your shell, verify that nginx is serving the `index.html` file from the +hostPath volume: + + root@task-pv-pod:/# apt-get update + root@task-pv-pod:/# apt-get install curl + root@task-pv-pod:/# curl localhost + +The output shows the text that you wrote to the `index.html` file on the +hostPath volume: + + Hello from Kubernetes storage + +{% endcapture %} + + +{% capture discussion %} + +## Access control + +Storage configured with a group ID (GID) allows writing only by Pods using the same +GID. Mismatched or missing GIDs cause permission denied errors. To reduce the +need for coordination with users, an administrator can annotate a PersistentVolume +with a GID. Then the GID is automatically added to any Pod that uses the +PersistentVolume. + +Use the `pv.beta.kubernetes.io/gid` annotation as follows: + + kind: PersistentVolume + apiVersion: v1 + metadata: + name: pv1 + annotations: + pv.beta.kubernetes.io/gid: "1234" + +When a Pod consumes a PersistentVolume that has a GID annotation, the annotated GID +is applied to all Containers in the Pod in the same way that GIDs specified in the +Pod’s security context are. Every GID, whether it originates from a PersistentVolume +annotation or the Pod’s specification, is applied to the first process run in +each Container. + +**Note**: When a Pod consumes a PersistentVolume, the GIDs associated with the +PersistentVolume are not present on the Pod resource itself. + +{% endcapture %} + + +{% capture whatsnext %} + +* Learn more about [PersistentVolumes](/docs/user-guide/persistent-volumes/). +* Read the [Persistent Storage design document](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/persistent-storage.md). + +### Reference + +* [PersistentVolume](/docs/resources-reference/v1.5/#persistentvolume-v1) +* [PersistentVolumeSpec](/docs/resources-reference/v1.5/#persistentvolumespec-v1) +* [PersistentVolumeClaim](/docs/resources-reference/v1.5/#persistentvolumeclaim-v1) +* [PersistentVolumeClaimSpec](/docs/resources-reference/v1.5/#persistentvolumeclaimspec-v1) + +{% endcapture %} + +{% include templates/task.md %} diff --git a/docs/tasks/configure-pod-container/task-pv-claim.yaml b/docs/tasks/configure-pod-container/task-pv-claim.yaml new file mode 100644 index 0000000000..fc82113f41 --- /dev/null +++ b/docs/tasks/configure-pod-container/task-pv-claim.yaml @@ -0,0 +1,10 @@ +kind: PersistentVolumeClaim +apiVersion: v1 +metadata: + name: task-pv-claim +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 3Gi diff --git a/docs/tasks/configure-pod-container/task-pv-pod.yaml b/docs/tasks/configure-pod-container/task-pv-pod.yaml new file mode 100644 index 0000000000..79d97c2f77 --- /dev/null +++ b/docs/tasks/configure-pod-container/task-pv-pod.yaml @@ -0,0 +1,22 @@ +kind: Pod +apiVersion: v1 +metadata: + name: task-pv-pod +spec: + + volumes: + - name: task-pv-storage + persistentVolumeClaim: + claimName: task-pv-claim + + containers: + - name: task-pv-container + image: nginx + ports: + - containerPort: 80 + name: "http-server" + volumeMounts: + - mountPath: "/usr/share/nginx/html" + name: task-pv-storage + + diff --git a/docs/tasks/configure-pod-container/task-pv-volume.yaml b/docs/tasks/configure-pod-container/task-pv-volume.yaml new file mode 100644 index 0000000000..bffcc7ae97 --- /dev/null +++ b/docs/tasks/configure-pod-container/task-pv-volume.yaml @@ -0,0 +1,13 @@ +kind: PersistentVolume +apiVersion: v1 +metadata: + name: task-pv-volume + labels: + type: local +spec: + capacity: + storage: 10Gi + accessModes: + - ReadWriteOnce + hostPath: + path: "/tmp/data"