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. How to do this depends on your operating system.

3.1.1. Versions

For REANA v0.3, kubectl 1.11.2 and minikube 0.28.2 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.2.0:

$ pacman -Q | grep -iE '(docker|virtualbox|kube|qemu|libvirt)'
docker 1:18.06.0-1
docker-compose 1.22.0-2
docker-machine 0.15.0-1
docker-machine-driver-kvm2 0.28.2-1
kubectl-bin 1.11.2-1
libvirt 4.6.0-3
minikube 0.28.2-1
python-docker 3.5.0-1
python-docker-pycreds 0.3.0-2
python-dockerpty 0.4.1-3
qemu 3.0.0-1
virtualbox 5.2.18-1
virtualbox-guest-iso 5.2.18-1
virtualbox-host-modules-arch 5.2.18-7

3.2. Start minikube

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

$ minikube start --kubernetes-version="v1.11.2"

or, in case of KVM2 hypervisor:

$ minikube start --kubernetes-version="v1.11.2" --vm-driver=kvm2

You will see an output like:

Starting local Kubernetes v1.11.2 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:

$ mkvirtualenv reana-cluster
$ 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.11.2"
  db_config: &db_base_config
    - REANA_SQLALCHEMY_DATABASE_URI: "postgresql+psycopg2://reana:reana@db:5432/reana"
  root_path: "/reana"
  #  cephfs_monitors:
  #    - 188.184.86.25:6790
  #    - 188.184.94.56:6790
  #    - 188.185.66.208:6790
  db_persistence_path: "/reanadb"

components:
  reana-workflow-controller:
    type: "docker"
    image: "reanahub/reana-workflow-controller:0.3.2"
    environment:
      - <<: *db_base_config
      - SHARED_VOLUME_PATH: "/reana"
      - ORGANIZATIONS: "default,alice,atlas,cms,lhcb"

  reana-job-controller:
    type: "docker"
    image: "reanahub/reana-job-controller:0.3.2"
    environment:
      - <<: *db_base_config
      - SHARED_VOLUME_PATH: "/reana"
      - REANA_STORAGE_BACKEND: "LOCAL"

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

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

  reana-workflow-monitor:
    type: "docker"
    image: "reanahub/reana-workflow-monitor:0.2.0"
    environment:
      - ZMQ_PROXY_CONNECT: "tcp://zeromq-msg-proxy.default.svc.cluster.local:8667"

  reana-workflow-engine-yadage:
    type: "docker"
    image: "reanahub/reana-workflow-engine-yadage:0.3.1"
    environment:
      - <<: *db_base_config
      - ZMQ_PROXY_CONNECT: "tcp://zeromq-msg-proxy.default.svc.cluster.local:8666"
      - SHARED_VOLUME_PATH: "/reana"

  reana-workflow-engine-cwl:
    type: "docker"
    image: "reanahub/reana-workflow-engine-cwl:0.3.2"
    environment:
      - <<: *db_base_config
      - ZMQ_PROXY_CONNECT: "tcp://zeromq-msg-proxy.default.svc.cluster.local:8666"
      - SHARED_VOLUME_PATH: "/reana"

  reana-workflow-engine-serial:
    type: "docker"
    image: "reanahub/reana-workflow-engine-serial:0.3.2"
    environment:
      - ZMQ_PROXY_CONNECT: "tcp://zeromq-msg-proxy.default.svc.cluster.local:8666"
      - SHARED_VOLUME_PATH: "/reana"

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
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 following way:

$ reana-cluster -f reana-cluster-custom.yaml init

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
workflow-monitor        match
zeromq-msg-proxy        match
yadage-default-worker   match
cwl-default-worker      match
serial-default-worker   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
workflow-monitor        Running
zeromq-msg-proxy        Running
yadage-default-worker   Running
cwl-default-worker      Running
serial-default-worker   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