3. User guide

3.1. Prerequisites

REANA cloud uses Kubernetes container orchestration system. The best way to try it out locally on your laptop is to set up Minikube with Helm and Traefik installed inside. How to do this depends on your operating system.

3.1.1. Versions

For REANA v0.5, kubectl 1.14.0 and minikube 1.0.0 are known to work well.

3.1.2. Arch Linux

For example, on Arch Linux, you should install the following packages:

Moreover, if you plan to run Minikube via the VirtualBox hypervisor, you should install also:

Alternatively, if you plan to run Minikube using the KVM2 hypervisor:

Here is one example of well-working versions for REANA v0.5.0:

$ pacman -Q | grep -iE '(docker|virtualbox|kube|qemu|libvirt)'
docker 1:18.09.5-1
docker-compose 1.24.0-1
docker-machine 0.16.1-2
docker-machine-driver-kvm2 1.0.0-1
kubectl-bin 1.14.0-1
kubernetes-helm-bin 2.13.1-1
libvirt 5.2.0-1
minikube-bin 1.0.0-1
python-docker 3.7.2-1
python-docker-pycreds 0.4.0-1
python-dockerpty 0.4.1-4
qemu 3.1.0-2
virtualbox 6.0.6-1
virtualbox-guest-iso 6.0.6-1
virtualbox-host-modules-arch 6.0.6-1

3.1.3. MacOS

For example, on MacOS, you should install the following packages:

$ brew install kubernetes-cli
$ brew install hyperkit
$ brew cask install minikube
$ brew install kubernetes-helm

3.2. Start minikube

Once you have installed kubectl and minikube, you can start minikube by running:

$ minikube config set memory 4096
$ minikube start --feature-gates="TTLAfterFinished=true"

in case of KVM2 hypervisor:

$ minikube start --vm-driver=kvm2 --feature-gates="TTLAfterFinished=true"

or, in case of Hyperkit hypervisor:

$ minikube start --vm-driver=hyperkit --feature-gates="TTLAfterFinished=true"

You will see an output like:

Starting local Kubernetes v1.14.0 cluster...
Starting VM...
Getting VM IP address...
Moving files into cluster...
Setting up certs...
Connecting to cluster...
Setting up kubeconfig...
Starting cluster components...
Kubectl is now configured to use the cluster.
Loading cached images from config file.

As seen from the output, Minikube startup routines already configured kubectl to interact with the newly created Kubernetes deployment, but it best to test whether kubectl is indeed configured properly:

$ kubectl get all
NAME             TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
svc/kubernetes   ClusterIP   10.0.0.1     <none>        443/TCP   1m

3.3. Install reana-cluster CLI tool

reana-cluster command line interface tool is easily installable from PyPI. You may want to install it into a new virtual environment:

$ # create new virtual environment
$ virtualenv ~/.virtualenvs/myreana
$ source ~/.virtualenvs/myreana/bin/activate
$ # install reana-cluster utility
$ pip install reana-cluster

3.4. Configure REANA cluster

The main function of reana-cluster command line tool is to initialise a working REANA cluster, ready to run workflows that users submit via reana-client.

In order to achieve this, reana-cluster needs to know how the REANA cluster should be set up; e.g. what versions of REANA components should be deployed and how the configuration of each component should be set up. reana-cluster expects to get this information via reana-cluster.yaml file that comes with the package:

cluster:
  type: "kubernetes"
  version: "v1.14.0"
  db_config: &db_base_config
    - REANA_SQLALCHEMY_DATABASE_URI: "postgresql+psycopg2://reana:reana@db:5432/reana"
  root_path: "/var/reana"
  shared_volume_path: "/var/reana"
  reana_url: "reana-dev.cern.ch"
  cephfs_volume_size: 200
  #  cephfs_monitors:
  #    - 188.184.86.25:6790
  #    - 188.184.94.56:6790
  #    - 188.185.66.208:6790
  db_persistence_path: "/var/reana/db"

components:
  reana-workflow-controller:
    type: "docker"
    image: "reanahub/reana-workflow-controller:0.5.0"
    environment:
      - <<: *db_base_config
      - ORGANIZATIONS: "default,alice,atlas,cms,lhcb"
      - REANA_WORKFLOW_ENGINE_IMAGE_CWL: "reanahub/reana-workflow-engine-cwl:0.5.0"
      - REANA_WORKFLOW_ENGINE_IMAGE_YADAGE: "reanahub/reana-workflow-engine-yadage:0.5.0"
      - REANA_WORKFLOW_ENGINE_IMAGE_SERIAL: "reanahub/reana-workflow-engine-serial:0.5.0"

  reana-job-controller:
    type: "docker"
    image: "reanahub/reana-job-controller:0.5.1"
    environment:
      - <<: *db_base_config

  reana-server:
    type: "docker"
    image: "reanahub/reana-server:0.5.0"
    environment:
      - <<: *db_base_config

  reana-message-broker:
    type: "docker"
    image: "reanahub/reana-message-broker:0.5.0"

You can use the supplied reana-cluster.yaml, or create your own custom configuration. For instance, if you wish to use a different Docker image for the reana-server component, you can copy the default reana-cluster.yaml to a reana-cluster-custom.yaml file and change the image tag reanahub/reana-server:0.2.0 according to your wishes.

3.5. Initialise a REANA cluster

Initialising a REANA cluster is just a matter of running init command:

$ reana-cluster init --traefik
REANA cluster is initialised.

If you have created a custom configuration, you can use the -f command-line option and specify your own file. In the same way you can set URL for REANA cluster --url <cluster_url>.

$ reana-cluster -f reana-cluster-custom.yaml --url reana.cern.ch init --traefik

3.6. Verify REANA components

You can verify that components deployed to REANA cluster are set up according to what is defined in REANA cluster specifications file via the verify command:

$ reana-cluster verify components
COMPONENT               IMAGE
job-controller          match
message-broker          match
server                  match
workflow-controller     match
wdb                     match
db                      match

3.7. Verify REANA cluster readiness

You can verify whether the REANA cluster is ready to serve the user requests by running the status command:

$ reana-cluster status
job-controller          Running
message-broker          Running
server                  Running
workflow-controller     Running
wdb                     Running
db                      Running
REANA cluster is ready.

In the above example, everything is running and the REANA cluster is ready for serving user requests.

3.8. Display commands to set up the environment for the REANA client

You can print the list of commands to configure the environment for the reana-client:

$ reana-cluster env
export REANA_SERVER_URL=http://192.168.39.247:31106

You can execute the displayed command easily as follows:

$ eval $(reana-cluster env)

3.9. Delete REANA cluster deployment

To bring the cluster deployment down, i.e. delete all REANA components that were deployed during init, you can run:

$ reana-cluster down

3.10. Delete interactive sessions

Interactive sessions that were not closed after work have been finished leave active Kubernetes objects (pod, service and Ingress) running in the REANA cluster. These objects might need to be deleted from time to time. Please note that interactive session pod and service are linked to the Ingress object. If it gets deleted other two will be deleted automatically.

To delete open interactive sessions use following commands:

# get all ingresses of open interactive sessions
$ kubectl get ingresses | grep interactive
interactive-jupyter-ad814137-baec-4ee5-b899-1d549e90b44a   *                 80      103m
interactive-jupyter-e4c7aa38-370b-47b7-bf8c-44f5f0f44b44   *                 80      3h48m
interactive-jupyter-ec5438b1-65a8-4bba-a52c-ff7970242e83   *                 80      3h16m
interactive-jupyter-f401874d-e9a6-4b2b-9b9d-12b0f141a442   *                 80      103m
interactive-jupyter-f9f56f92-a533-4bcc-aad9-581f5e31ff0f   *                 80      103m
# lets delete all remaining objects of open interactive sessions
$ kubectl delete $(kubectl get ingresses -o name | grep interactive)
ingress.extensions "interactive-jupyter-ad814137-baec-4ee5-b899-1d549e90b44a" deleted
ingress.extensions "interactive-jupyter-e4c7aa38-370b-47b7-bf8c-44f5f0f44b44" deleted
ingress.extensions "interactive-jupyter-ec5438b1-65a8-4bba-a52c-ff7970242e83" deleted
ingress.extensions "interactive-jupyter-f401874d-e9a6-4b2b-9b9d-12b0f141a442" deleted
ingress.extensions "interactive-jupyter-f9f56f92-a533-4bcc-aad9-581f5e31ff0f" deleted