Include minikube setup instructions

Fixes openebs#332 - validates that openebs can be run with minikube Fixes openebs#350 - developer solutions category under setup Fixes openebs#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.
satyamz · Sep 26, 2017 · 6b62697 · 6b62697
1 parent cfdd48c
commit 6b62697
Show file tree

Hide file tree

Showing 2 changed files with 149 additions and 1 deletion.
diff --git a/documentation/source/index.rst b/documentation/source/index.rst
@@ -21,6 +21,7 @@ Contents:
     Overview <install/install_overview>
     Cloud Solutions <install/cloud_solutions>
     On-Premise Solutions <install/on_premise_solutions>
+    Developer Solutions <install/dev_solutions>
 
 
 .. toctree::
@@ -51,4 +52,4 @@ Contents:
     :caption: Contributing to the OpenEBS Documents
 
 
-    Contributing to the OpenEBS Documentation <contribute/contribute_openebs_doc>
+    Contributing to the OpenEBS Documentation <contribute/contribute_openebs_doc>
diff --git a/documentation/source/install/dev_solutions.rst 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
+