From a9062ea5f1d40c65484e0793930586cb1dc0f05a Mon Sep 17 00:00:00 2001 From: paigehargrave Date: Wed, 27 Feb 2019 21:03:28 -0500 Subject: [PATCH] Update use-nfs-volumes.md --- ee/ucp/kubernetes/storage/use-nfs-volumes.md | 111 +++++++++---------- 1 file changed, 54 insertions(+), 57 deletions(-) diff --git a/ee/ucp/kubernetes/storage/use-nfs-volumes.md b/ee/ucp/kubernetes/storage/use-nfs-volumes.md index 121304301c..76519dabff 100644 --- a/ee/ucp/kubernetes/storage/use-nfs-volumes.md +++ b/ee/ucp/kubernetes/storage/use-nfs-volumes.md @@ -8,34 +8,34 @@ redirect_from: Users can provide persistent storage for workloads running on Docker Enterprise by using NFS storage. These NFS shares, when mounted into the running container, -providing state to the application, managing data externally to the container's +provide state to the application, managing data external to the container's lifecycle. -> Note: Provisioning an NFS server and/or exporting an NFS share is out of scope -> of this guide. Additionally, using external [Kubernetes +> Note: Provisioning an NFS server and exporting an NFS share are out of scope +> for this guide. Additionally, using external [Kubernetes > plugins](https://github.com/kubernetes-incubator/external-storage/tree/master/nfs) > to dynamically provision NFS shares, is also out of scope for this guide. To mount existing NFS shares within Kubernetes Pods, we have 2 options: - - We can define NFS shares within our Pod definitions. NFS shares are defined + - Define NFS shares within the Pod definitions. NFS shares are defined manually by each tenant when creating a workload. - - We can define NFS shares as a Cluster object through Persistent Volumes, with - its lifecycle handled separately to the workload. This is common if an - operator wanted to define a range of NFS shares, for tenants to request and + - Define NFS shares as a Cluster object through Persistent Volumes, with + the CLuster object lifecycle handled separately from the workload. This is common for + operators who want to define a range of NFS shares for tenants to request and consume. -## Defining NFS Shares in the Pod Spec +## Defining NFS Shares in the Pod definition When defining workloads in Kubernetes manifest files, an end user can directly reference the NFS shares to mount inside of each Pod. The NFS share is defined -within the Pod specification, this could be a standalone pod, or could be -wrapped in a higher-level object like a Deployment, Daemonset or StatefulSet. +within the Pod specification, which could be a standalone pod, or could be +wrapped in a higher-level object like a Deployment, Daemonset, or StatefulSet. -In the following example, we have a running UCP cluster, and have downloaded a -[client bundle](../../user-access/cli/#download-client-certificates), with +The following example includes a running UCP cluster and a downloaded +[client bundle](../../user-access/cli/#download-client-certificates) with permission to schedule pods in a namespace. -An example pod specification with an NFS volume defined: +Here is an example pod specification with an NFS volume defined: ```bash $ cat nfs-in-a-pod.yaml @@ -59,7 +59,7 @@ spec: path: /share1 # Please change this to the relevant share ``` -To deploy the pod, and ensure that is has started up correctly we will use [kubectl](../../user-access/kubectl/) command line. +To deploy the pod, and ensure that it started up correctly, use the [kubectl](../../user-access/kubectl/) command line tool. ```bash $ kubectl create -f nfsinapod.yaml @@ -69,8 +69,8 @@ NAME READY STATUS RESTARTS AGE nfs-in-a-pod 1/1 Running 0 6m ``` -We can check everything has been mounted correctly by getting a shell prompt -within the container, and searching for our mount. +Verify everything was mounted correctly by getting a shell prompt +within the container and searching for your mount. ```bash $ kubectl exec -it pod-using-nfs sh @@ -80,34 +80,33 @@ nfs.example.com://share1 on /var/nfs type nfs4 (rw,relatime,vers=4.0,rsize=26214 / # ``` -As we have defined the NFS share as part of the Pod Spec, UCP or Kubernetes -doesn't know anything about this NFS share. This means that when the pod gets -deleted, the NFS share will be unattached from the Cluster. The data will of -course still remain in the NFS share. +Because you defined the NFS share as part of the Pod Spec, neither UCP nor Kubernetes +knows anything about this NFS share. This means that when the pod gets +deleted, the NFS share is unattached from the Cluster. However, the data remains in the NFS share. ## Exposing NFS shares as a Cluster Object -For this method we will use the Kubernetes Objects [Persistent +For this method, use the Kubernetes Objects [Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistent-volumes) and [Persistent Volume Claims](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) to manage the lifecycle and access to NFS Shares. -Here an operator could define multiple shares for a tenant to use within the +Here you can define multiple shares for a tenant to use within the cluster. The [Persistent -Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistent-volumes) -is a cluster wide object so could be pre-provisioned by an operator. A +Volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistent-volumes) +is a cluster wide object, so it can be pre-provisioned. A [Persistent Volume -Claims](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) -is a claim by a tenant, for use of a PV within their namespace. +Claim](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) +is a claim by a tenant for use of a Persistent Volume within their namespace. -> Note: NFS Share Lifecycle in this sense, is referring to granting and removing -> end user's ability to consume NFS storage, rather than managing the lifecycle +> Note: In this case, 'NFS share lifecycle' is referring to granting and removing the +> end user's ability to consume NFS storage, not managing the lifecycle > of the NFS Server. ### Persistent Volume -As an operator define the persistent volume at the cluster level: +Define the Persistent Volume at the cluster level: ```bash $ cat pvwithnfs.yaml @@ -126,12 +125,11 @@ spec: path: /share1 # Please change this to the relevant share ``` -To create a Physical Volume on the cluster, an operator would need a [Cluster +To create Persistent Volume objects at the Cluster level, you need a [Cluster Role Binding](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding) -grant, to create persistent volume objects at the Cluster level. Once again a we -will use the [kubectl](../../user-access/kubectl/) command line to create the -volume. +grant. Again use the [kubectl](../../user-access/kubectl/) command line tool to create the +volume: ``` $ kubectl create -f pvwithnfs.yaml @@ -144,33 +142,33 @@ my-nfs-share 5Gi RWO Recycle Available #### Access Modes -The access mode for a NFS persistent volume can either be: +The access mode for a NFS Persistent Volume can be any of the following modes: -- ReadWriteOnce – the volume can be mounted as read-write by a single node -- ReadOnlyMany – the volume can be mounted read-only by many nodes -- ReadWriteMany – the volume can be mounted as read-write by many nodes +- ReadWriteOnce – the volume can be mounted as read-write by a single node. +- ReadOnlyMany – the volume can be mounted read-only by many nodes. +- ReadWriteMany – the volume can be mounted as read-write by many nodes. The access mode in the Persistent Volume definition is used to match a Persistent Volume to a Claim. When a Persistent Volume is defined and created inside of Kubernetes, a Volume is not mounted. For more information on [access modes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) -see the kubernetes documentation. +see the Kubernetes documentation. #### Reclaim The [reclaim policy](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#reclaiming) -is used to define what the cluster should do after a persistent volume has been -released from a claim. A persistent volume reclaim policy could be: Reclaim, +is used to define what the cluster should do after a Persistent Volume has been +released from a Claim. A Persistent Volume Reclaim policy could be: Reclaim, Recycle and Delete. Please see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#reclaiming) for a deeper understanding. ### Persistent Volume Claim -A tenant can now "claim" that persistent volume for use within their workloads -by using a Kubernetes persistent volume claim. A persistent volume claim will -live within a namespace, and it will try and match available persistent volumes +A tenant can now "claim" a Persistent Volume for use within their workloads +by using a Kubernetes Persistent Volume Claim. A Persistent Volume Claim resides within a namespace, +and it attempts to match available Persistent Volumes to what a tenant has requested. ``` bash @@ -188,12 +186,11 @@ spec: storage: 5Gi # volume size requested ``` -A tenant, with a +A tenant with a [RoleBinding](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding) -to create persistent volume claims, will now be able to deploy this persistent -volume claim. Assuming there is a persistent volume that meets the tenants -criteria, Kubernetes will now bind the persistent volume to the Claim. Once -again, this is not mounting the share. +to create Persistent Volume Claims can deploy this Persistent +Volume Claim. If there is a Persistent Volume that meets the tenant's +criteria, Kubernetes binds the Persistent Volume to the Claim. Again, this does not mount the share. ```bash $ kubectl create -f myapp-claim.yaml @@ -208,12 +205,12 @@ NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM my-nfs-share 5Gi RWO Recycle Bound default/myapp-nfs slow 4m ``` -### Defining a Workload +### Defining a workload -Finally, a tenant can deploy a workload to consume this persistent volume claim. -The persistent volume claim is defined within the Pod specification, this could -be a standalone pod, or could be wrapped in a higher-level object like a -Deployment, Daemonset or StatefulSet. +Finally, a tenant can deploy a workload to consume the Persistent Volume Claim. +The Persistent Volume Claim is defined within the Pod specification, which could +be a standalone pod or could be wrapped in a higher-level object like a +Deployment, Daemonset, or StatefulSet. ```bash $ cat myapp-pod.yaml @@ -236,9 +233,9 @@ spec: claimName: myapp-nfs ``` -The pod can be deployed by a tenant, using the -[kubectl](../../user-access/kubectl/) command line tool. Additionally, we can -check that the pod is running successfully, and the NFS share has been mounted +The pod can be deployed by a tenant using the +[kubectl](../../user-access/kubectl/) command line tool. Additionally, you can +verify that the pod is running successfully and that the NFS share has been mounted inside of the container. ```bash @@ -257,4 +254,4 @@ nfs.example.com://share1 on /var/nfs type nfs4 (rw,relatime,vers=4.1,rsize=26214 ## Where to go next - [Deploy an Ingress Controller on Kubernetes](/ee/ucp/kubernetes/layer-7-routing/) -- [Discover Network Encryption on Kubernetes](/ee/ucp/kubernetes/kubernetes-network-encryption/) \ No newline at end of file +- [Discover Network Encryption on Kubernetes](/ee/ucp/kubernetes/kubernetes-network-encryption/)