Container workloads elegantly making storage volume claims which are robustly satisfied without conflicts. I’d like to see that. Well, yes you can with OpenShift. Billy, cat-in-a-box, and his friends are here to tell you how. This lab is another in the OpenShift MiniLabs series.
Objectives
Let’s demonstrate container volume creation and claiming using the three approaches for operating your OpenShift local cluster. To recap these are:
- Direct invocation using the oc CLI – oc cluster up/down
- The convenience wrapper tool known as oc-cluster-wrapper – linux only
- The Python based convenience tool known powershift – linux or Windows 10
Setup
Initial Attempt
This tutorial assumes you have completed the OpenShift MiniLabs installation procedure. Then refresh before continuing.
Create an Application
We are going to need an application for testing. Let’s do this in the pre-supplied project, myproject.
$ oc login -u developer -p developer $ oc project myproject $ oc new-app --name='cotd' -l name='cotd' php~https://bitbucket.org/emergile/cotd.git $ oc expose service cotd --name=cotd -l name='cotd'
Check volume assignment using local Docker
Its worth first validating your environment to see if your operating system and file permissions are in order. We will do this by pulling down and running an existing image of the COTD application on Docker Hub and verifying that it can access a local volume for its pet images.
Make sure the target local volume is mapped as shareable by your Docker runtime. For Docker Toolbox, visit the Preference and check the File Sharing entries are correct. Google for the latest commentary on Docker volume mapping under Windows. For example, you may need to change your password to remove special characters. Again, replace $HOME as per your system environment.
Do the following for all environments then issue a run command as per your environment. Replace $HOME below by the full path name appropriate in your system. Note it assumed that you have cloned down the COTD repo as per the installation instructions as that is where the volume will be mapped..
$ docker pull spicozzi/cotd $ cd ~/containersascode $ cd cotd $ git pull
Linux/Mac OS/X
$ docker run -it -p 8080:8080 -v $HOME/containersascode/cotd/data/images:/opt/app-root/src/data/images spicozzi/cotd
Windows
$ docker run -it -p 8080:8080 -v /c/$HOME/containersascode/cotd/data/images:/opt/app-root/src/data/images spicozzi/cotd
Once you have launched the container, open your browser to http://localhost:8080 , or to whatever your local system is mapping for the Docker IP. Check that the website is using the images in the mapped location, e.g. by changing the name of one of the images. You may need to switch to an alternate browser to circumvent caching behaviour.
Repeat Attempt
To reset your environment to repeat this tutorial do the following:
$ cd ~/containersascode $ oc login -u developer -p developer $ oc delete all -l name-cotd -n myproject $ oc-cluster up containersascode $ oc delete persistentvolume cotdvolume --as system:admin $ oc delete persistentvolumeclaim cotdclaim
Instructions
There are three steps (a,b,c) to making a volume accessible by your container instance. Note that OpenShift will automatically map the claim event to an appropriate persistent volume if a volume is not specified.
- Create a persistent volume (pv)
- Create a persistent volume claim (pvc)
- Add the storage claim to your deployment config
We will demonstrate how to complete each of these steps using the CLI, oc-wrapper or powershift alternatives. In all cases we will assume the following settings, which you can adjust as necessary:
- $VOLUMESIZE=1Gi
- $VOLUMENAME=cotdvolume
- $PROFILE=containersascode
- $VOLUMECLAIMSIZE=100Mi
- $VOLUMECLAIMNAME=cotdclaim
- $PROJECT=myproject
- $VOLUMEPATH=$HOME/$PROFILE/cotd/data/images (Linux)
- $VOLUMEPATH=/c/$HOME/$PROFILE/cotd/data/images (Windows)
- $MOUNTPATH=/opt/app-root/src/data/images
1. oc cluster CLI
For this example, we will start from scratch and call out each step without using any convenience tools. This example will work on Linux, Mac OS/X and Windows 10. Note that using the CLI you can also collapse steps (b, c) into a single instruction using oc set volume which is also documented below.
a. Create a persistent volume
Do this by creating the necessary yaml file as per the instructions below. Some docs examples can be found here. Inside the yaml file replace the parameters to reflect your installation before issuing the create -f command.
$ oc login -u system:admin $ oc get pv $ oc create -f - << EOF! apiVersion: v1 kind: PersistentVolume metadata: name: $VOLUMENAME spec: capacity: storage: $VOLUMESIZE accessModes: - ReadWriteOnce - ReadWriteMany persistentVolumeReclaimPolicy: Recycle hostPath: path: $VOLUMEPATH EOF!
Access Modes
You may be wondering what those “access modes” are. The Kubernetes documentation at http://kubernetes.io/docs/user-guide/persistent-volumes/ summarises as follows:
- RWO – ReadWriteOnce – the volume can be mounted as read-write by a single node
- ROX – ReadOnlyMany – the volume can be mounted read-only by many nodes
- RWX – ReadWriteMany – the volume can be mounted as read-write by many nodes
b. Create a Persistent Volume Claim
The next step is to create a persistent volume claim (PVC). You can do this using the Console or from the command line.
Using Console
Point your browser to Create Storage link for your project, e.g. for myproject this would be https://127.0.0.1:8443/console/project/myproject/create-pvc. Then complete the form entering the $VOLUMECLAIMNAME and $VOLUMECLAIMSIZE as appropriate.
From Command Line
Do this by creating the necessary yaml file as per the instructions below. Check the docs for details as you wish here. Inside the yaml file replace the parameters to reflect your installation before issuing the create -f command, e.g.
$ oc login -u developer -p developer $ oc get pvc $ oc create -f - << EOF! apiVersion: v1 kind: PersistentVolumeClaim metadata: name: $VOLUMECLAIMNAME spec: accessModes: - ReadWriteOnce resources: requests: storage: $VOLUMECLAIMSIZE volumeName: $VOLUMENAME EOF!
Access Modes
Again, according to the Kubernetes documentation, claims use the same conventions as volumes when requesting storage with specific access modes.
c. Add Storage for PVC to Deploymentconfig
Finally, we need to add the storage claim to the deployment config (cd) of our application (myproject/cotd). You can do this using the Console or from the command line. A dc change will trigger a redeployment with the amended settings.
Using the Console
Point your browser to Add Storage link for the deployment config of your project/application, e.g. for myproject/cotd this would be https://127.0.0.1:8443/console/project/myproject/attach-pvc?kind=DeploymentConfig&name=cotd. Then complete the form for the $VOLUMECLAIM entering the $MOUNTPATH as appropriate. Volume name can be left empty.
From the Command Line
Equivalent instructions for adding storage to the dc from the command line would be as follows. Learn more about managing volumes here. Note for Windows PowerShell, use a “^” for command line continuation.
$ oc login -u developer -p developer $ oc project myproject $ oc volume dc/cotd --add \ --name=images --type=persistentVolumeClaim \ --claim-name=$VOLUMECLAIMNAME \ --mount-path=$MOUNTPATH --containers=cotd
Alternate – Combining steps b and c with set volume
Create a pvc and mapping a storage claim to your deployment can be combined into a single instruction. Using this method there is no need for steps b) and c) above.
From the Command Line
$ oc login -u developer -p developer $ oc project myproject $ oc set volume dc/pets --add \ --overwrite \ --name=images \ --type=persistentVolumeClaim \ --mount-path=/opt/app-root/src/data/images \ --claim-size=100Mi \ --claim-name=cotdclaim \ --containers=pets
2. oc-cluster-wrapper for Linux/Mac OS/X
a. Create a persistent volume
The convenience tool will create the .yaml configuration file for you. The equivalent invocation would be as follows. Note that if $VOLUMEPATH is not specificed it will default to $HOME/.oc/profiles/$PROFILE/volumes/$VOLUMENAME. The leading /c/ is not required for the $VOLUMEPATH with powershift.
$ oc-cluster create-volume $VOLUMENAME $VOLUMESIZE $VOLUMEPATH
$ oc get pv --as system:admin
b. Create a Persistent Volume Claim
Follow the equivalent instructions as described for the oc cluster CLI option.
c. Add Storage for PVC to Deploymentconfig
Follow the equivalent instructions as described for the oc cluster CLI option.
2. powershift for Linux/Mac OS/X and Windows 10
a. Create a persistent volume
This convenience tool will create the .yaml configuration file for you. The equivalent invocation would be as follows below. Note that if $VOLUMEPATH is not specificed it will default to $HOME/.powershift/profiles/$PROFILE/volumes/$VOLUMENAME (Linux) or $HOME/PowerShift/profiles/$PROFILE/volumes/$VOLUMENAME (Windows).
$ powershift cluster volumes create $VOLUMENAME \
--size $VOLUMESIZE \
--path $VOLUMEPATH
$ powershift cluster volumes list
b. Create a Persistent Volume Claim
Same instructions as described for the oc cluster CLI option.
c. Add Storage for PVC to Deploymentconfig
Same instructions as described for the oc cluster CLI option.
Verify Lab Success
Visit the application, e.g. as at http://cotd-myproject.127.0.0.1.xip.io and verify that it is using images drawn from the new mapped volume. You can do this by, e.g. changing the name of an image file and observing that the associated page now shows a blank image. Recall that the mapped volume is located at $VOLUMEPATH.
Trivia
Check sites such as https://blog.openshift.com/experimenting-with-persistent-volumes/ for further details.