From 6f1d610c99286bb2ae8727ecaf021ead9dc02341 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicolas=20Mass=C3=A9?= Date: Fri, 19 May 2017 12:06:48 +0100 Subject: [PATCH] Improve documentation --- README.md | 128 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 88 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 6c58bde..914597d 100644 --- a/README.md +++ b/README.md @@ -1,82 +1,130 @@ # An Hostpath Provisioner for OpenShift +This project solves the PersistentVolume provisioning in OpenShift. It is mainly +a packaged and polished version of the Kubernetes Incubator's Hostpath Provisioner. + +The original license is Apache 2.0. This project remains under the same license. + +Main differences from the original project : + - OpenShift Template that works Out-of-the-Box + - Naming convention (namespace/pvc-name instead of GUID) + - Configurable root directory (HOSTPATH_TO_USE parameter) + - Docker Image available on DockerHub (https://hub.docker.com/r/nmasse/openshift-hostpath-provisioner/) + ## If you just want to use it +If you just want to use this project, without having to compile or debug, +here is the way to go. + ### Setup +First, you will have to create a directory that will hold all PersistentVolumes : ``` -$ mkdir /tmp/openshift -$ chmod 777 /tmp/openshift -$ chcon -Rt svirt_sandbox_file_t /tmp/openshift -$ oc project default -$ oc process -f setup/hostpath-provisioner-template.yaml > objects.json -$ oc create -f objects.json +mkdir /tmp/openshift +chmod 777 /tmp/openshift +chcon -Rt svirt_sandbox_file_t /tmp/openshift ``` -### Test +If you chose a different path, mind that you will have to pass the HOSTPATH_TO_USE +parameter to the OpenShift template (-p HOSTPATH_TO_USE=/path/to/other/directory). +Then, you will have to process the template and create the generated objects : ``` -$ oc project my-project -$ oc create -f setup/sample-claim.yaml -$ find /tmp/openshift/ +oc process -f setup/hostpath-provisioner-template.yaml > objects.json +oc create -f objects.json ``` -### Cleanup +If you chose a different path, just pass the HOSTPATH_TO_USE parameter to the +"oc process" command : +``` +oc process -f setup/hostpath-provisioner-template.yaml -p HOSTPATH_TO_USE=/path/to/other/directory > objects.json +oc create -f objects.json +``` +The template by default creates objects in the "default" namespace, no matter +the "-n" option you used or the "oc project" command you issued before. This is +in fact a limitation (see https://github.com/openshift/origin/issues/8971). + +But, if you want to generate objects in another namespace (project), just pass the +TARGET_NAMESPACE parameter to the "oc process" command : ``` -$ oc project default -$ oc delete all -f objects.json +oc process -f setup/hostpath-provisioner-template.yaml -p TARGET_NAMESPACE=my-project > objects.json +oc create -f objects.json ``` -## If you want to hack it +By default, the template uses the "nmasse/openshift-hostpath-provisioner:latest" +image on DockerHub (see https://hub.docker.com/r/nmasse/openshift-hostpath-provisioner/). +You can change this behavior by passing the +HOSTPATH_PROVISIONER_IMAGE to "oc process" command : -### Build +``` +oc process -f setup/hostpath-provisioner-template.yaml -p HOSTPATH_PROVISIONER_IMAGE=john/openshift-hostpath-provisioner:latest > objects.json +oc create -f objects.json +``` +If you need to pass multiple parameters, use multiple "-p" options : ``` -$ export GOPATH="$PWD" -$ cd src -$ glide install -v -$ CGO_ENABLED=0 go build -a -ldflags '-extldflags "-static"' -o ../hostpath-provisioner hostpath-provisioner/hostpath-provisioner.go +oc process -f setup/hostpath-provisioner-template.yaml -p TARGET_NAMESPACE=my-project -p HOSTPATH_TO_USE=/path/to/other/directory > objects.json +oc create -f objects.json ``` -### Package +*Note about the file 'objects.json' :* + +It's a good idea to keep that file safe since it will be use to clean up your OpenShift +instance in case you change your mind. See the cleanup section below. + +### Test + +A sample PersistentVolumeClaim object is provided to test the provisioner : ``` -$ docker build -t openshift-hostpath-provisioner:latest . +oc project my-project +oc create -f setup/sample-claim.yaml +find /tmp/openshift/ ``` -### Setup +### Cleanup + +You can cleanup your OpenShift instance by running the "oc delete" command : ``` -$ oc project default -$ oc process -f setup/hostpath-provisioner-template.yaml -p HOSTPATH_PROVISIONER_IMAGE=openshift-hostpath-provisioner:latest | oc create -f - +oc delete -f objects.json ``` -### Test +## If you want to hack it + +### Build ``` -$ oc project my-project -$ oc create -f setup/sample-claim.yaml -$ find /tmp/openshift/ +export GOPATH="$PWD" +cd src +glide install -v +CGO_ENABLED=0 go build -a -ldflags '-extldflags "-static"' -o ../hostpath-provisioner hostpath-provisioner/hostpath-provisioner.go ``` -### Cleanup +### Package + +``` +docker build -t openshift-hostpath-provisioner:latest . +``` + +### Manual Cleanup ``` -$ oc project default -$ oc delete all -l template=hostpath-provisioner-template -$ oc delete clusterrolebinding hostpath-provisioner -$ oc delete clusterrole hostpath-provisioner -$ oc delete scc hostpath-provisioner -$ oc delete sa hostpath-provisioner -$ oc delete storageclass hostpath-provisioner +oc project default +oc delete all -l template=hostpath-provisioner-template +oc delete sa hostpath-provisioner +oc delete clusterrolebinding hostpath-provisioner +oc delete clusterrole hostpath-provisioner +oc delete scc hostpath-provisioner +oc delete storageclass hostpath-provisioner ``` ### Pushing your image to DockerHub (Optional) ``` -$ docker login https://index.docker.io/v1/ -$ docker images openshift-hostpath-provisioner:latest --format '{{ .ID }}' -$ docker tag $(docker images openshift-hostpath-provisioner:latest --format '{{ .ID }}') index.docker.io//openshift-hostpath-provisioner -$ docker push index.docker.io//openshift-hostpath-provisioner +docker login https://index.docker.io/v1/ +docker images openshift-hostpath-provisioner:latest --format '{{ .ID }}' +docker tag $(docker images openshift-hostpath-provisioner:latest --format '{{ .ID }}') index.docker.io//openshift-hostpath-provisioner +docker push index.docker.io//openshift-hostpath-provisioner ```