From 6b62697a7f32fd7420fb8f3e3d5f771a6c392d5b Mon Sep 17 00:00:00 2001 From: kmova Date: Wed, 27 Sep 2017 00:22:56 +0530 Subject: [PATCH] Include minikube setup instructions Fixes #332 - validates that openebs can be run with minikube Fixes #350 - developer solutions category under setup Fixes #351 - sample instructions for setting up minikube Adds new document (rst) file for documentation developer solutions like minikube. This section will need to be further improved with links to developer options like modifying the PVC yaml files with openebs annotations. --- documentation/source/index.rst | 3 +- .../source/install/dev_solutions.rst | 147 ++++++++++++++++++ 2 files changed, 149 insertions(+), 1 deletion(-) create mode 100644 documentation/source/install/dev_solutions.rst diff --git a/documentation/source/index.rst b/documentation/source/index.rst index 1c592b3a87..f36121faa7 100644 --- a/documentation/source/index.rst +++ b/documentation/source/index.rst @@ -21,6 +21,7 @@ Contents: Overview Cloud Solutions On-Premise Solutions + Developer Solutions .. toctree:: @@ -51,4 +52,4 @@ Contents: :caption: Contributing to the OpenEBS Documents - Contributing to the OpenEBS Documentation \ No newline at end of file + Contributing to the OpenEBS Documentation diff --git a/documentation/source/install/dev_solutions.rst b/documentation/source/install/dev_solutions.rst new file mode 100644 index 0000000000..91c433282d --- /dev/null +++ b/documentation/source/install/dev_solutions.rst @@ -0,0 +1,147 @@ +******************* +Developer Solutions +******************* + +Minikube +======== + +Setting up OpenEBS with Kubernetes using Minikube +------------------------------------------------- + +Minikube helps developers to quickly setup a single-node Kubernetes cluster for their development environement. There are several options available for developers to install Minikube. See `Minikube Setup`_. + + .. _Minikube Setup: https://github.com/kubernetes/minikube + +If you are already an experienced Minikube user, you can easily setup OpenEBS on your existing Kubernetes cluster with a few simple kubectl commands. See, :ref:`quick-start`. + +This section provides instructions to set up Kubernetes using Minikube directly on Ubuntu 16.06 (without using any VM drivers) and to have OpenEBS running in hyper converged mode. + +Prerequisites +------------- +Minimum requirements for using Minikube + +* Machine Type - (Minimum 4 vCPUs) +* RAM - (Minimum 4GB) + +Make sure *docker* is installed on your Ubuntu Host. + + +Add iSCSI Support +----------------- + +On your Ubuntu host, install open-iscsi package. OpenEBS uses iSCSI to connect to the block volumes. +:: + sudo apt-get update + sudo apt-get install open-iscsi + sudo service open-iscsi restart + +Verify that iSCSI is configured +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Check that initiator name is configured and iSCSI service is running using the following commands. +:: + sudo cat /etc/iscsi/initiatorname.iscsi + sudo service open-iscsi status + + +Download and setup Minikube and kubectl +--------------------------------------- + +On your Ubuntu host, install minikube +:: + curl -Lo minikube https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64 + chmod +x minikube + sudo mv minikube /usr/local/bin/ + +On your Ubuntu host, install kubectl +:: + curl -Lo kubectl https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl + chmod +x kubectl + sudo mv kubectl /usr/local/bin/ + +On your Ubuntu host, setup directories for storing minkube and kubectl configuration +:: + mkdir /home/vagrant/.kube || true + touch /home/vagrant/.kube/config + +On your Ubuntu host, setup ENV for minikube. Copy the following to ~/.profile +:: + export MINIKUBE_WANTUPDATENOTIFICATION=false + export MINIKUBE_WANTREPORTERRORPROMPT=false + export MINIKUBE_HOME=$HOME + export CHANGE_MINIKUBE_NONE_USER=true + export KUBECONFIG=$HOME/.kube/config + +On your Ubuntu host, start the minikube +:: + sudo -E minikube start --vm-driver=none + +Verify that minikube is configured +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Check that minikube is configured and it has started using the following commands. +:: + minikube status + +When minikube is configured properly, *minikube status* will provide output as follows: +:: + minikube: Running + cluster: Running + kubectl: Correctly Configured: pointing to minikube-vm at 127.0.0.1 + +**Note** +In case, the minikube errors our with permission denied message to configuration files, run the following commands. +:: + sudo chown -R $USER $HOME/.kube + sudo chgrp -R $USER $HOME/.kube + sudo chown -R $USER $HOME/.minikube + sudo chgrp -R $USER $HOME/.minikube + +Verify that kubernetes is configured +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Check that kubectl is configured and services are running using the following commands. +:: + kubectl get pods + kubectl get nodes + +When configured properly, the above kubectl command will provide output similar to following: +:: + vagrant@minikube-dev:~$ kubectl get nodes + NAME STATUS AGE VERSION + minikube-dev Ready 8m v1.7.5 + vagrant@minikube-dev:~$ kubectl get pods --all-namespaces + NAMESPACE NAME READY STATUS RESTARTS AGE + kube-system kube-addon-manager-minikube-dev 1/1 Running 1 8m + kube-system kube-dns-910330662-4q4bm 3/3 Running 3 8m + kube-system kubernetes-dashboard-txn8f 1/1 Running 1 8m + vagrant@minikube-dev:~$ + + +Setup OpenEBS +--------------------------------------- + +Download the latest OpenEBS Operator files using the following commands. +:: + git clone https://github.com/openebs/openebs.git + cd openebs/k8s + kubectl apply -f openebs-operator.yaml + +Add OpenEBS related storage classes, that can then be used by developers and applications using the following command. +:: + kubectl apply -f openebs-storageclasses.yaml + +**Note:** + +The persistent storage is carved out from the space available on the nodes (default host directory : */var/openebs*). Development is in progress to provide administrator with additional options of consuming the storage (as outlined in *openebs-config.yaml*). These are slated to work hand-in-hand with the local storage manager of Kubernetes that is due in Kubernetes 1.7/1.8. + +To use OpenEBS as persistent storage for your stateful workloads, set the storage class in the Persistent Volume Claim (PVC) to the OpenEBS storage class. + +Get the list of storage classes using the following command. Choose the storage class that best suits your application. +:: + kubectl get sc + +Some sample YAML files for stateful workloads using OpenEBS are provided in the `openebs/k8s/demo`_ + + .. _openebs/k8s/demo: https://github.com/openebs/openebs/tree/master/k8s/demo +