******************
Installation guide on Kubernetes
******************


Architecture overview
-------------------

Sarus is made of several services that communicate through HTTP
requests. They each run in a separate container. 

Main components are: 

* Gateway API: handling the calls from the SDK to perform analytics or ML training
* Gateway worker: service for long running jobs in analytics/ML
* Dataowner front: the UI for the Data owner preparing the datasets 
* Dataowner-dash API: the API to prepare datasets, manage users & privacy policies, audit...
* Dataowner-dash worker: service for long running jobs in dataset preparation
* Nginx as a load balancer

.. _requirements-1:

Requirements & cluster setup
------------

Sarus requires: 

* a running and maintained Kubernetes cluster
* a Storage with ReadWriteMany capabilities

To get more details on how to setup a managed Kubernetes cluster 
for Sarus on GCP, AWS, Azure or OVH, visit :doc:`Kubernetes Setup <k8s_setup>`.

Deploying the Sarus application on a cluster with helm
------------------------------------------------------

Here, we assume that you have received a TOKEN_NAME and a
secret personal access TOKEN from your Sarus Account Manager 
to be able to access Sarus’ Helm repo and pull Sarus docker images. 

Adding Sarus’ Helm repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You need to add Sarus' repo to your local list of helm repositories:

::

   $ REPO_ID=22362555; CHANNEL=devel; helm repo add --username ${TOKEN_NAME} --password ${TOKEN} sarus https://gitlab.com/api/v4/projects/${REPO_ID}/packages/helm/${CHANNEL}`
   "sarus" has been added to your repositories

You can then see Sarus' Helm chart using:

::

   $ helm repo update
   Hang tight while we grab the latest from your chart repositories...
   ...Successfully got an update from the "sarus" chart repository
   Update Complete. ⎈Happy Helming!⎈

   $ helm search repo sarus
   NAME            CHART VERSION   APP VERSION DESCRIPTION         
   sarus/sarus-app 0.2.2           0.2.2       The Sarus Helm chart

Filling the deployment values
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

They can see what are the required variables using:
``helm show values sarus/sarus-app``, and print the readme using
``helm show values sarus/sarus-app``. See `helm
show <https://helm.sh/docs/helm/helm_inspect/>`__.

They should fill a ``myvalues.yaml`` file with their specifics for the
Sarus App.

Installing the Sarus app
~~~~~~~~~~~~~~~~~~~~~~~~

Using ``helm install``, you can install a chosen release of Sarus (2.8.1 in the exemple below)

::

   RELEASE="2.8.1"; helm install -f myvalues.yaml ${RELEASE} sarus/sarus-app --set sarus-registry-chart.enabled=true --set sarus-secrets-chart.enabled=true

``sarus-registry-chart`` and ``sarus-secrets-chart`` are optional; they can be omitted when upgrading the app.

Using a namespace
^^^^^^^^^^^^^^^^^

Helm can deploy the app in a particular Kubernetes namespace with the
additional argument to the command line: ``-n my-namespace`` ; Helm can
create it if it does not exist with ``--create-namespace``.

If Helm creates the namespace, it will not delete it by itself with
``helm uninstall``: the deletion is a manual process.


Updating the cluster with new images
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If docker images have been updated on the container registry, you just
need to do

::

   kubectl rollout restart deployments