OGDC Service API

The ogdc-runner service API sits between users of the CLI and Argo Workflows. It is responsible for translating user recipes into workflows that are submitted to and executed by Argo.

The service interface is defined using FastAPI. See the FastAPI docs on First Steps to learn how to get started with using FastAPI.

the OGDC service is defined as a subpackage of the ogdc-runner. See: ogdc_runner.service.

FastAPI application

The FastAPI application and API routes are defined in ogdc_runner.service.main.

Database

The OGDC service API uses a postgresql database to serve as persistent storage of user information and (eventually) recipe status information.

See ogdc_runner.service.db for details.

Authentication

The OGDC API uses a standard OAuth2 approach. Users authenticate with a username/password, and the service responds with a token that can then be used to authenticate further actions (like submitting a recipe). The approach is roughly based on the FastAPI Security Tutorial.

See ogdc_runner.service.auth for details.

Routes needing auth

When writing new API routes, consider if the route should require user authentication. If so, use the auth.AuthenticatedUserDependency as a type annotation in the function args:

from ogdc_runner.service import auth

@app.get("/user")
async def get_current_user(
    current_user: auth.AuthenticatedUserDependency,
) -> dict[str, str]:
    """Return the current authenticated user.

    Useful for testing that authentication is working as expected.
    """
    return {"current_user": current_user.name}

Using the auth.AuthenticatedUserDependency as a type annotation in the function args will cause the associated route (in this case, user) to require authentication via a token obtained via the ogdc_runner.service.auth.token route (which requires username/password).

By default, all routes in ogdc_runner.service.auth_routes require a valid auth token and do not need to explicitly use auth.AuthenticatedUserDependency in the function signature.

Adding new users

Currently, only the admin user can create other users. Ensure that you have admin credentials set:

export OGDC_API_USERNAME=admin
export OGDC_API_password=admin-password

Then, use the ogdc-runner CLI to create the new user:

ogdc-runner create-user my-username my-password

Required envvars

  • OGDC_DB_USERNAME: database username that the service will use to interact with the backend PostgreSQL database.

  • OGDC_DB_PASSWORD: database password that the service will use to interact with the backend PostgreSQL database.

  • OGDC_DB_HOST: hostname of the backend PostgreSQL database (typically ${RELEASE_NAME}-db-cnpg-rw when deployed via the ogdc-helm chart).

  • OGDC_DB_NAME (optional): database name, defaults to ogdc.

  • OGDC_JWT_SECRET_KEY: value of the secret key used to encode/decode the JWT tokens used for authentication.

  • OGDC_ADMIN_PASSWORD: the value desired for the service’s admin user account.

  • OGDC_WORKFLOW_PVC_NAME (optional): name of the PersistentVolumeClaim mounted into workflow pods, defaults to cephfs-qgnet-ogdc-workflow-pvc. The ogdc-helm chart sets this to cephfs-${RELEASE_NAME}-workflow-pvc.

  • ARGO_NAMESPACE (optional): kubernetes namespace in which argo workflows are submitted, defaults to qgnet. The ogdc-helm chart sets this to the release namespace.