From acd7f69f21fd8f4c13900edc4bf5eb48d79a96fa Mon Sep 17 00:00:00 2001 From: Diego Rodriguez Date: Tue, 21 Mar 2017 15:45:32 +0100 Subject: [PATCH] installation: add local `minikube` installation * Adds local installation documentation and amends OpenStack installation. (closes #4) * Adds `minikube` specific installation option to REANA configuration script. (addresses #13) Signed-off-by: Diego Rodriguez --- MANIFEST.in | 3 + docs/gettingstarted.rst | 80 ----------------- docs/index.rst | 1 + docs/installation.rst | 188 ++++++++++++++++++++++++++++++++++++++++ requirements-k8s.txt | 1 + scripts/reana | 112 ++++++++++++++++++++++++ setup.py | 1 + 7 files changed, 306 insertions(+), 80 deletions(-) create mode 100644 docs/installation.rst create mode 100644 requirements-k8s.txt create mode 100755 scripts/reana diff --git a/MANIFEST.in b/MANIFEST.in index e2a888f6..4d330f9d 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -21,9 +21,12 @@ include COPYING include *.rst include *.sh +include *.txt include pytest.ini +prune docs/_build recursive-include docs *.py recursive-include docs *.png recursive-include docs *.rst recursive-include docs *.txt +recursive-include scripts reana recursive-include tests *.py diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index 69f60340..c7139e71 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -1,86 +1,6 @@ Getting started =============== -Create a Kubernetes cluster ---------------------------- - -In order to create a Kubernetes cluster using OpenStack infrastructure, -we need to run the magnum command, which we can have available running -the magnum docker client: - -.. code-block:: console - - $ docker login gitlab-registry.cern.ch - $ sudo docker run -it gitlab-registry.cern.ch/cloud/ciadm /bin/bash - -Or logging into `lxplus-cloud`: - -.. code-block:: console - - $ ssh lxplus-cloud.cern.ch - -Once we have it available we are ready to create the cluster: - -.. code-block:: console - - $ magnum cluster-create --name reana-cluster --keypair-id reanakey \ - --cluster-template kubernetes --node-count 2 - -Lastly, we must load the cluster configuration into the Kubernetes -client: - -.. code-block:: console - - $ $(magnum cluster-config reana-cluster) - -It is at this point that we will have the `kubectl` command available -to manage our brand new cluster. - -For more information on Kubernetes/OpenStack, please see -`CERN Cloud Docs `__. - -Create the Kubernetes resources using manifest files ----------------------------------------------------- -- Clone `reana-resources-k8s `__: - - ``git clone https://github.com/reanahub/reana-resources-k8s.git`` - -- Change Kubernetes service account token in `reana-job-controller` node configuration file: - -.. code-block:: console - - $ kubectl get secrets - NAME TYPE DATA AGE - default-token-XXXXX kubernetes.io/service-account-token 3 13d - $ sed 's/default-token-02p0z/default-token-XXXXX/' -i reana-resources-k8s/deployments/reana-system/job-controller.yaml - -- Create REANA system instances: - - ``kubectl create -f reana-resources-k8s/deployments/reana-system`` - -- Yadage workers: - - ``kubectl create -f reana-resources-k8s/deployments/yadage-workers`` - -- Services: - - ``kubectl create -f reana-resources-k8s/services/`` - -- Secrets (you should provide your own CephFS secret): - - ``kubectl create -f reana-resources-k8s/secrets/`` - -Get the Workflow Controller ip address and port ------------------------------------------------ -.. code-block:: console - - $ kubectl describe services workflow-controller | grep NodePort - NodePort: http 32313/TCP - $ kubectl get pods | grep workflow-controller | cut -d" " -f 1 | xargs kubectl describe pod | grep 'Node:' - Node: 192.168.99.100,192.168.99.100 - -So the Workflow Controller component can be accessed through ``192.168.99.100:32313``. - Launch workflows ---------------- diff --git a/docs/index.rst b/docs/index.rst index aca7d99f..e81ddad6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,6 +5,7 @@ :maxdepth: 2 introduction + installation gettingstarted architecture components diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 00000000..342831d5 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,188 @@ +Installation +=============== + +Local Kubernetes installation +----------------------------- + +Requirements +```````````` +In order to create a local REANA cluster with Kubernetes as a backend +the following requirements must be met: + +- `VirtualBox` +- `VT-x/AMD-v` virtualization must be enabled in BIOS + +Quickstart +`````````` + +We start by creating a fresh new Python virtual environment that will handle our `REANA` cluster instantiation. + +.. code-block:: console + + $ mkvirtualenv reana + +We update ``pip`` and ``setuptools`` + +.. code-block:: console + + $ pip install --upgrade pip setuptools + +Next we install ``reana`` package + +.. code-block:: console + + $ git clone https://github.com/reanahub/reana + $ cd reana + $ pip install -e .[all] + +Now, for instantiating a local REANA `minikube` based cluster we should run + +.. code-block:: console + + $ reana install-minikube + +which will do the following: + +.. literalinclude:: ../scripts/reana + :language: sh + :lines: 23-89 + +Once the script finishes, we should check ``kubectl get pods`` until we have an output as follows: + +.. code-block:: console + + $ kubectl get pods + job-controller-1390584237-0lt03 1/1 Running 0 1m + message-broker-1410199975-7c5v7 1/1 Running 0 1m + storage-admin 1/1 Running 0 1m + workflow-controller-2689978795-5kzgt 1/1 Running 0 1m + workflow-monitor-1639319062-q7v8z 1/1 Running 0 1m + yadage-alice-worker-1624764635-x8z71 1/1 Running 0 1m + yadage-atlas-worker-2909073811-t9qv3 1/1 Running 0 1m + yadage-cms-worker-209120003-js5cv 1/1 Running 0 1m + yadage-lhcb-worker-4061719987-6gpbn 1/1 Running 0 1m + zeromq-msg-proxy-1617754619-68p7v 1/1 Running 0 1m + +Now we will be able to check whether the nodes are actually working. Firstly, we get the VM's ip: + +.. code-block:: console + + $ export MINIKUBE_IP=$(minikube ip) + +Secondly, we get the current instances ports: + +.. code-block:: console + + $ export WORKFLOW_CONTROLLER_PORT=$(kubectl describe service workflow-controller | grep 'NodePort:' | cut -f 4 | sed -e "s@/TCP@@") + $ export WORKFLOW_MONITOR_PORT=$(kubectl describe service workflow-monitor | grep 'NodePort:' | cut -f 4 | sed -e "s@/TCP@@") + $ export JOB_CONTROLLER_PORT=$(kubectl describe service job-controller | grep 'NodePort:' | cut -f 4 | sed -e "s@/TCP@@") + +And finally, we open the test URLs: + +.. code-block:: console + + $ curl "http://$MINIKUBE_IP:$WORKFLOW_CONTROLLER_PORT/workflows" + { + "workflows": {} + } + $ open "http://$MINIKUBE_IP:$WORKFLOW_MONITOR_PORT/helloworld" + $ curl "http://$MINIKUBE_IP:$JOB_CONTROLLER_PORT/jobs" + { + "jobs": {} + } + + +CERN OpenStack installation +--------------------------- + +Kubernetes cluster creation +``````````````````````````` +In order to create a Kubernetes cluster using OpenStack infrastructure, +we need to run the magnum command, which we can have available running +the magnum docker client: + +.. code-block:: console + + $ docker login gitlab-registry.cern.ch + $ sudo docker run -it gitlab-registry.cern.ch/cloud/ciadm /bin/bash + +Or logging into `lxplus-cloud`: + +.. code-block:: console + + $ ssh lxplus-cloud.cern.ch + +Once we have it available we are ready to create the cluster: + +.. code-block:: console + + $ magnum cluster-create --name reana-cluster --keypair-id reanakey \ + --cluster-template kubernetes --node-count 2 + +Lastly, we must load the cluster configuration into the Kubernetes +client: + +.. code-block:: console + + $ $(magnum cluster-config reana-cluster) + +It is at this point that we will have the `kubectl` command available +to manage our brand new cluster. + +For more information on Kubernetes/OpenStack, please see +`CERN Cloud Docs `__. + +Create the Kubernetes resources using manifest files +```````````````````````````````````````````````````` + +First we create a new Python virtual environment + +.. code-block:: console + + $ mkvirtualenv reana-resources-k8s + +Then we install the ``reana-resources-k8s`` package + +.. code-block:: console + + $ git clone https://github.com/reanahub/reana-resources-k8s + $ cd reana-resources-k8s + $ pip install -e .[all] + +Now we should configure ``reana-resources-k8s/templates/config.yaml`` as it fits the better, and once we are done, we should generate the manifests and create the nodes + +.. code-block:: console + + $ reana-resources-k8s build-manifests + $ kubectl create -Rf configuration-manifests + +Clean manifests if they are not needed anymore + +.. code-block:: console + + $ rm -Rf configuration-manifests + +In order to see if the cluster is working we should firstly gather all the nodes IPs and ports: + +.. code-block:: console + + $ export WORKFLOW_CONTROLLER_IP=$(kubectl describe pod --selector=app=workflow-controller | grep IP | cut -f 3) + $ export WORKFLOW_CONTROLLER_PORT=$(kubectl describe service workflow-controller | grep 'NodePort:' | cut -f 4 | sed -e "s@/TCP@@") + $ export WORKFLOW_MONITOR_IP=$(kubectl describe pod --selector=app=workflow-monitor | grep IP | cut -f 3) + $ export WORKFLOW_MONITOR_PORT=$(kubectl describe service workflow-monitor | grep 'NodePort:' | cut -f 4 | sed -e "s@/TCP@@") + $ export JOB_CONTROLLER_IP=$(kubectl describe pod --selector=app=job-controller | grep IP | cut -f 3) + $ export JOB_CONTROLLER_PORT=$(kubectl describe service job-controller | grep 'NodePort:' | cut -f 4 | sed -e "s@/TCP@@") + +And finally, we open the test URLs: + +.. code-block:: console + + $ curl "http://$WORKFLOW_CONTROLLER_IP:$WORKFLOW_CONTROLLER_PORT/workflows" + { + "workflows": {} + } + $ open "http://$WORKFLOW_MONITOR_IP:$WORKFLOW_MONITOR_PORT/helloworld" + $ curl "http://$JOB_CONTROLLER_IP:$JOB_CONTROLLER_PORT/jobs" + { + "jobs": {} + } diff --git a/requirements-k8s.txt b/requirements-k8s.txt new file mode 100644 index 00000000..a6a9bb5c --- /dev/null +++ b/requirements-k8s.txt @@ -0,0 +1 @@ +-e 'git+https://github.com/reanahub/reana-resources-k8s.git@master#egg=reana-resources-k8s' diff --git a/scripts/reana b/scripts/reana new file mode 100755 index 00000000..41d5309f --- /dev/null +++ b/scripts/reana @@ -0,0 +1,112 @@ +#!/bin/sh +# +# This file is part of REANA. +# Copyright (C) 2017 CERN. +# +# REANA is free software; you can redistribute it and/or modify it under the +# terms of the GNU General Public License as published by the Free Software +# Foundation; either version 2 of the License, or (at your option) any later +# version. +# +# REANA is distributed in the hope that it will be useful, but WITHOUT ANY +# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR +# A PARTICULAR PURPOSE. See the GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License along with +# REANA; if not, write to the Free Software Foundation, Inc., 59 Temple Place, +# Suite 330, Boston, MA 02111-1307, USA. +# +# In applying this license, CERN does not waive the privileges and immunities +# granted to it by virtue of its status as an Intergovernmental Organization or +# submit itself to any jurisdiction. + +reana_components="reana-job-controller reana-workflow-controller + reana-workflow-monitor reana-message-broker + reana-workflow-engine-yadage" + +install_local_minikube () { + # Check whether the OS is supported + if ! echo "darwin linux" | grep -F -q -w -i "$(uname -s)" + then + echo 'Your OS is not supported.' + exit 1 + else + OS="$(uname -s | tr '[:upper:]' '[:lower:]')" + fi + + # Install tools `kubectl` and `minikube` if necessary + if ! command -v kubectl > /dev/null 2>&1 + then + echo 'Installing latest kubectl ...' + curl -LO "https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/$OS/amd64/kubectl" + chmod +x ./kubectl + sudo mv ./kubectl /usr/local/bin/kubectl + fi + + if ! command -v minikube > /dev/null 2>&1 + then + echo 'Installing minikube ...' + curl -Lo minikube "https://storage.googleapis.com/minikube/releases/v0.17.1/minikube-$OS-amd64" + chmod +x minikube + sudo mv minikube /usr/local/bin/ + fi + + # FIXME find better way to define this dependency. + # `extras_require` does not support not PyPI deps and + # `dependency_links` does not seem to work. + pip install -r requirements-k8s.txt + + # Start `minikube` + minikube start || echo 'Error while starting minikube' && exit 1 + + # Use minikube Docker daemon, so local images will be used instead + # of pulling from registry + echo 'Using minikube Docker daemon ...' + eval "$(minikube docker-env)" + + # Pull all REANA components images and retag for local `dev` + echo 'Pulling REANA components images ...' + for component in $reana_components + do + docker pull "reanahub/$component" + docker tag "reanahub/$component" "$component" + done + + # Generate Kubernetes manifests + echo 'Building REANA configuration manifests ...' + reana-resources-k8s build-manifests + + # Set current cluster secret for `reana-job-controller` component + current_cluster_secret=$(kubectl get secrets | grep 'service-account-token' | cut -d ' ' -f 1) + sed -i'' -e "s/default-token-8p260/$current_cluster_secret/" configuration-manifests/deployments/job-controller.yaml + + # Deploy system + echo 'Deploying REANA on minikube ...' + kubectl create -Rf configuration-manifests + + # Clean configuration manifests + rm -rf configuration-manifests +} + +usage() { + echo "${0##*/} manages REANA system operations" + echo "" + echo "Usage:" + echo " install-minikube Deploys local minikube based REANA cluster" + echo " -h Help" +} + +if [ "$1" != "" ] +then + case $1 in + install-minikube ) install_local_minikube + ;; + clean-minikube) minikube delete + ;; + -h | --help ) usage + exit + ;; + esac +else + usage +fi diff --git a/setup.py b/setup.py index f7ec2cb1..c031085b 100644 --- a/setup.py +++ b/setup.py @@ -84,6 +84,7 @@ extras_require=extras_require, setup_requires=setup_requires, tests_require=tests_require, + scripts=['scripts/reana'], classifiers=[ 'Environment :: Web Environment', 'Intended Audience :: Developers',