Data Service API Server

The SPT-3G data service API server is a TornadoWeb-based webserver written in Python that implements the API endpoints that power the SPT-3G services. Currently the primary data service is the cutout service.

Authentication and authorization

The API server provides both web resources like webpages and programmatic API functions.

Web resources that require access control use our Keycloak service for single-sign-on (SSO) authentication. A custom OpenID Connect (OIDC) flow is implemented in the API server to authenticate users, leveraging the existing secure cookie feature of TornadoWeb to protect endpoints by adding a Python decorator @tornado.web.authenticated to the RequestHandler subclass functions like get() and post().

Authorization utilizes the Keycloak groups system, where users can be added to groups for access control purposes. By creating Keycloak mappers, this group membership information is supplied to our OIDC client applications via the returned OAuth token, allowing them to implement authorization as needed. For example, the API server only allows users in specific groups to access protected content.

Programmatic API endpoints are protected by requiring a standard Authorization: Bearer token HTTP request header. These protected endpoints are decorated with the @authenticated function. The access token is obtained by accessing the protected URL /account/token/create, which returns a JSON-formatted data structure containing a Java Web Token (JWT). The API server signs each generated JWT using a secret that protects the tokens from forgery. These tokens also have a TTL, or expiration period, after which they become invalid. For programmatic use of extended duration, users may use the /api/v1/account/token/refresh endpoint to exchange a valid token for a new one prior to expiration.

Job system

One of the functions of the API server is job management. Users can launch jobs, monitor their status, and retrieve the output files. The API server provides an asynchronous job management system that is inspired by the Universal Worker Service (UWS) pattern defined by the International Virtual Observatory Alliance.

ℹ️ Click here to explore the SPT-3G API documentation.

Development environment

Description

We need parallel development environments for the API server and cutout service web app for independent code development by multiple developers. To accomplish this, we create multiple releases of the spt-api-server Helm chart via separate ArgoCD applications:

• spt-api-server

• spt-api-server-dev1

• spt-api-server-dev2

The two dev apps deploy to separate Kubernetes namespaces, and they each use dedicated domain names for their ingresses. Helm parameter overrides activate the “dev mode” resources as illustrated in the Application manifest snippet below:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: spt-api-server-dev2
  namespace: argo-cd
spec:
  destination:
    server: https://kubernetes.default.svc
    namespace: spt-api-server-dev2
  project: spt3g
  source:
    path: charts/spt-api-server
    repoURL: https://gitlab.com/spt3g/kubernetes.git
    targetRevision: main
    helm:
      valueFiles:
      - "values.yaml"
      - "values-dev2.yaml"

In production mode, the ReactJS-based web app is served as a static set of HTML documents generated by the yarn build script, which compiles the JavaScript from ES6 modules to browser-compatible JavaScript. In development mode, we will separate the /app/cutout ingress path from the Python-based Tornado webserver and direct requests to that path instead to the Node dev server. We enable the “dev mode” via the config.devMode.enabled parameter in the Helm chart values.yaml file. When enabled, the release will include a deployment, service, and ingress for the Node-based development webserver started by the command yarn start.This will dynamically compile source files and serve them to the browser, and it will hot-reload them when it detects file changes. Thus, when Okteto is engaged to sync files between local development source code and the running container, Node will automatically recompile the web app nearly instantly after the developer modified files locally.

Web app tutorial

Use Okteto to dynamically sync files between your local source code directory and the container running remotely on Kubernetes. First move to the source code directory for the web app and set the KUBECONFIG env var to connect with the appropriate Kubernetes cluster:

cd "${SPT3G_KUBERNETES_REPO_CLONE}/src/cutout-web-app/src"
export KUBECONFIG=$HOME/.kube/spt3g.kubeconfig

Run okteto up -f okteto-dev2.yml to initialize the connection. The Okteto config file contains the deployment name and namespace information for the target. (Sometimes Okteto fails to connect to the dev container; try again until it works.)

$ okteto up -f okteto-dev2.yml 
 ✓  Images successfully pulled
 ✓  Files synchronized
    Context:   spt3g
    Namespace: spt-api-server-dev2
    Name:      spt-api-server-dev2-web-app
    Forward:   3000 -> 3000
               9229 -> 9229

Note: The Okteto config files okteto-dev1.yml and okteto-dev2.yml have been crafted to deconflict the local ports used by Okteto to port-forward the terminal opened in the remote container. This is unnecessary in the typical use case in which only one dev deployment is used at a time.

Once connected to the web app development container, you will first need to run yarn install to download and install the dependencies on the container’s data volume. (This is typically faster than adding the node_modules folder to the list of files that are synced to the container and waiting for that transfer to complete. The node_modules is ignored by the background Syncthing process because it is listed in the src/spt-api-server/src/static/app/cutout/.stignore file.)

Welcome to your development container. Happy coding!
spt-api-server-dev2:spt-api-server-dev2-web-app app> yarn install
yarn install v1.22.5
[1/4] Resolving packages...
[2/4] Fetching packages...

When the installation of the packages completes, launch the dev server with yarn start.

spt-api-server-dev2:spt-api-server-dev2-web-app app> yarn start

Compiled successfully!

You can now view spt3g-cutout-service in the browser.

  Local:            http://localhost:3000/app/cutout
  On Your Network:  http://10.42.192.6:3000/app/cutout

Note that the development build is not optimized.
To create a production build, use yarn build.

Open your browser to https://dev2.spt3g.ncsa.illinois.edu/app/cutout to view the web app. It should redirect you to /account/login to start the Keycloak login flow. (Our Keycloak server has been configured to allow auth callback URLs from our dev domains.)

API server tutorial

Following a similar pattern, launch Okteto to serve a development version of the API server.

$ cd "${SPT3G_KUBERNETES_REPO_CLONE}/src/spt-api-server/src"

$ export KUBECONFIG=$HOME/.kube/spt3g.kubeconfig

$ okteto up -f okteto-dev2.yml 
 ✓  Images successfully pulled
 ✓  Files synchronized
    Context:   spt3g
    Namespace: spt-api-server-dev2
    Name:      spt-api-server-dev2
    Forward:   8084 -> 8080
    Reverse:   9000 <- 9001

worker@spt-api-server-dev2-6fd5dd479b-ftkwt:~/src$ python3 main.py 
...
2021-11-03 16:21:12,160 [spt-api     ] INFO     API server listening on port 8080 at base path ""

Troubleshooting

Ensure that your dev deployment is in sync with the deployment repo by logging in to the ArgoCD web interface. You can use the App Diff tool to see exactly how the actual state differs from the desired state.

Note: When Okteto is engaged, the app will always be out of sync, because Okteto must alter the deployment to serve its function. These differences are typically confined to the Deployment objects.