.. _visivo-soda:

SODA Service
============

.. note::
    - Support: https://skao.slack.com/archives/C03ASTELLMA
    - Code Repository: https://gitlab.com/ska-telescope/src/src-ia/ska-src-ia-vo-soda-deployment


IVOA SODA Service
-----------------

Visivo-SODA service is an implementation of the IVOA protocol 
(https://ivoa.net/documents/SODA) to provide cutouts from FITS-files data based on astronomical coordinates.

This documentation is 
intended for operators deploying SODA in either containerized environments or 
Kubernetes clusters.

The SODA server provides access to FITS-files which are expected to be readable from the Docker-host.
The files should have read-only access. In case the files are not world-readable SODA-Docker must be run with suitable UID:GID.

.. _deploy-soda-services:


**Configuration for Docker**


Deployment with docker-compose is possible, but is expected only to be useful for development purposes. As such, instructions for this can be found here https://confluence.skatelescope.org/display/SRCSC/SODA+Documentation.
Docker images are stored under SKA-Harbor: `harbor.srcdev.skao.int/soda/visivo-vlkb-soda:1.7`.


Helm Deployment
----------

For deployment using Helm, you will need to define the SODA service configuration in the chart's ``values.yml``. An example is given in ``values.template.yml``

- ``image``: Specifies the Docker image repository, tag, and pull policy for the SODA server itself.
- ``deployment``: Define the Kubernetes namespace where the application will be deployed.
- ``extraEnv``: Allows passing custom environment variables to the SODA container.
- ``config``: SODA application-specific configuration.
- ``ingress``: Configures the Ingress for external access. Ingress installation can be toggled on or off.
- ``persistence``: Defines the persistent storage settings to set the data resource readable by the SODA service.

.. note::

    - **Persistence**. In order for the SODA service to be able to serve data in response to requests, persistence must be turned on, with either an appropriate existing PVC specified, or config values enabling the creation of a new one included. Typically this PVC is expected to refer to an externally resolvable (deterministic) volume, such as that of a data lake storage element.
    - **Ingress**. Ingress manifests for the nginx-ingress controller are provided (ingress-nginx must be installed separately).


Helm charts are available from:

.. code-block:: bash
    
    https://gitlab.com/ska-telescope/src/src-ia/ska-src-ia-vo-soda-deployment
    cd ska-src-ia-vo-soda-deployment


To deploy this service an example of the ``values.yml`` file could be the next:

.. code-block:: bash

    image:
    repository: harbor.srcdev.skao.int/soda/visivo-vlkb-soda
    tag: 1.6.2
    pullPolicy: Always

    deployment:
    namespace: ska-src-soda

    extraEnv:
    - name: SECURITY
        value:
    - name: ACCESS_CONTEXT_ROOT
        value: ska#datasets

    config:
    datasets: |-
        fits_path_surveys=/srv/soda/datasets
        fits_path_cutouts=/srv/soda/cutouts
        ivoid_authority=test.skao
        ivoid_resource_key=datasets/fits

    ingress:
    enabled: false
    host:
    proxyBodySize: 5000m
    proxyBuffering: "off"
    proxyRequestBuffering: "off"

    persistence:
    storageClass:
    existingClaim: ""
    enabled: true
    accessMode: ReadOnlyMany
    # TODO: Increase this once finished testing
    size: 10Gi

Change the next items to point the paths of your RSE: 

.. code-block:: bash

    fits_path_surveys=<surverys folder>


Then, run the next command to deploy the helm using the ``values.yml`` file

.. code-block:: bash

    helm upgrade --install --create-namespace -n ska-src-soda --values values.yml ska-src-soda etc/helm/


To check the service is up, access availability end point which returns the status in a short xml response. In this example:

.. code-block:: bash

    curl http://localhost:8080/ska/datasets/availability

adjust hostname and the path.



Integration of SODA Service
---------------------------

In the SKA architecture, SODA is one of the 'Backend services' which are proxied by the Gatekeeper. The **Backend-services must not be externally accessible**, only the Gatekeeper is and it provides security for the backend-services.Therefore, it is necessary to register the service in Site Capabilities 

How to add SODA (and other backend-services) to Site Capabilities refer to `Gatekeeper Service <_site-caps-gatekeeper>`_ of this manual.


TEST SODA service
---------------------------
The following is an example of how to call the SODA service via Gatekeeper. To run this test, you need a valid token from a user with permissions to access both the SODA service on the local node and the Rucio space where the data to be accessed is located.
You also need to know the local path of the file. The Rucio Client tool, in particular the commands ``rucio list-dids`` and ``rucio list-file-replicas <FILE_ID>``, can help you to identify a file to use in the test.

This is the code that you can use: 

.. code-block:: bash
    curl --get --data-urlencode "ID=ivo://src.skao.org/datasets/fits?<local_path>" --data-urlencode "POS=<value_soda_parameter_POS>" --data-urlencode "POSSYS=<value_soda_parameter_POSYS>" -o <path_output_file> -H "Authorisation: Bearer <token>" <url_gatekeeper_soda_local_service> 

And this is a specific example using the espSRC node:

.. code-block:: bash
    curl --get --data-urlencode "ID=ivo://src.skao.org/datasets/fits?sp3531_soda/9e/7a/23-11-09-22-06-30_LoTSS-DR2_P38Hetdex07_mosaic-blanked.fits" --data-urlencode "POS=CIRCLE 110.24 67.14 0.25" --data-urlencode "POSSYS=GALACTIC" -o /tmp/example-galactic.fits -H "Authorisation: Bearer $SKA_TOKEN" https://gatekeeper.espsrc.iaa.csic.es/soda/ska/datasets/soda