Onyxia API

This is the server part of the Onyxia datalab, it interacts with your container orchestrator (Kubernetes) to deploy users services.
Deployable services are listed and configured inside catalogs.
Default catalogs are from InseeFrlab : Interactive services, Databases, Automation but more catalogs (including your own) can be added.

Quick start

Onyxia-api is usually run as a component within the Onyxia stack. See Onyxia helm chart and docs.onyxia.sh for installation instruction.

Running Onyxia-API standalone

Using docker

docker run -p 8080:8080 inseefrlab/onyxia-api

Using Java / maven (from sources)

git clone https://github.com/InseeFrLab/onyxia-api.git
cd onyxia-api
mvn spring-boot:run

Usage

Once Onyxia is started, browse to http://localhost:8080 to get started with the OpenAPI documentation.

Contributing

Contributions are welcome. Make sure to conform to Android Open Source Project code style : mvn spotless:apply can enforce it.

Configuration

Main configuration file is onyxia-api/src/main/resources/application.properties.
Each variable can be overridden using environment variables.

Regions configuration :

Catalogs configuration :

Authentication configuration

Open id configuration (used when authentication.mode=openidconnect)

The only two required parameters are oidc.issuer-uri and oidc.clientID. See below for more details.

Configurable properties :
| Key | Default | Description | | -------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | oidc.issuer-uri | | Issuer URI. Onyxia-API will use this URL to retrieve the public key for token validation. e.g for Keycloak : https://keycloak.example.com/auth/realms/REALMNAME | | oidc.clientID | | Client id to be used by Onyxia web application | | oidc.username-claim | preferred_username | Claim to be used as user id. Must conform to RFC 1123 | | oidc.groups-claim | groups | Claim to be used as list of user groups. | | oidc.roles-claim | roles | Claim to be used as list of user roles. | | oidc.audience | | Optional : audience to validate. Must be the same as the token's aud field | | oidc.skip-tls-verify | false | Disable tls cert verification when retrieving keys from the IDP. Not intended for production. Consider mounting the proper cacerts instead of disabling the verification. | | oidc.public-key | | Optional: If for some reason you don't want Onyxia-API to bootstrap configuration by requesting the issuer-uri then you can manually provide the public key used for validating incoming tokens. | | oidc.extra-query-params | | Optional : query params to be added by client. e.g : prompt=consent&kc_idp_hint=google | | oidc.scope | openid profile | Optional : Specifies the OIDC scopes to be requested by the Onyxia client. "openid" is always requested, regardless of this setting. | | oidc.idleSessionLifetimeInSeconds | | Optional: Automatically logs out users after a set period of inactivity. |

Security configuration :

HTTP configuration

Events

Admin configuration:

:warning: This section should be considered pre-alpha and may be subject to major changes and revamps :warning:

Other configurations

Onyxia API dependency to Helm

Onyxia-API makes system calls to helm using the helm-wrapper Java library.
helm is bundled in the Onyxia API Docker image, see current version bundled here : Dockerfile.
If running Onyxia API locally you need to have helm available in the PATH.

Onyxia Helm format extension

Onyxia's catalogs are based on the Helm chart format and especially the values.schema.json (see https://helm.sh/docs/topics/charts/#schema-files) file used to populate the personalization tabs displayed by the UI.
Onyxia is fully interoperable with the Helm chart format which means you can use any helm chart repository as a onyxia catalog. But you probably want to use one that includes values.schema.json files (those files are optional in helm).
Onyxia extends this format to enhance it and provide more customization tools in the UI.

An example of such extension can be found here, see x-onyxia.