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

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

Using Helm

The Onyxia helm chart is available at inseefrlab

helm repo add inseefrlab https://inseefrlab.github.io/helm-charts
helm install inseefrlab/onyxia

This will install both the API and the Web components.

Usage

Once Onyxia is started, browse to http://localhost:8080 to get the OpenAPI documentation.
Onyxia-API is primarly made to work with the webapp Onyxia-Web.
If you use it in other ways, we would love to hear from you :)

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 :

Key	Default	Description
regions	onyxia-api/src/main/resources/regions.json	List of regions, see Region configuration

Authentication configuration

Key	Default	Description
authentication.mode	none	Supported modes are : none, openidconnect (must be configured)

Open id configuration

Key	Default	Description
keycloak.realm		See Keycloak configuration
keycloak.resource		See Keycloak configuration
keycloak.auth-server-url		See Keycloak configuration
keycloak.ssl-required	external	See Keycloak configuration
keycloak.public-client	true	See Keycloak configuration
keycloak.enable-basic-auth	true	See Keycloak configuration
keycloak.bearer-only	true	See Keycloak configuration
keycloak.disable-trust-manager	false	See Keycloak configuration
oidc.username-claim	preferred_username	Claim to be used as user id. Should respect RFC 1123

Security configuration :

Key	Default	Description
security.cors.allowed_origins		To indicate which origins are allowed by CORS

Catalogs configuration :

Key	Default	Description
catalogs	see onyxia-api/src/main/resources/catalogs.json	List of catalogs. Each catalog can be of type universe or helm. Mixing is supported. If there is no region of corresponding type then the catalog will be ignored
catalogs.refresh.ms	300000 (5 minutes)	The rate at which the catalogs should be refreshed. <= 0 means no refreshs after initial loading

HTTP configuration

Key	Default	Description
http.proxyHost		Proxy hostname (e.g : proxy.example.com)
http.proxyPort	80 for HTTP, 443 for HTTPS	Proxy port
http.noProxy		Hosts that should not use the proxy (e.g : localhost,host.example.com)
http.proxyUsername		Username if the proxy requires authentication
http.proxyPassword		Password if the proxy requires authentication

Other configurations

Key	Default	Description
springdoc.swagger-ui.path	/	Open API (swagger) UI path
springdoc.swagger-ui.oauth.clientId	``	clientid used by swagger to authenticate the user, in general the same which is used by onyxia-ui is ok.

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 API compatibility matrix with Kubernetes

In addition of using helm, Onyxia API interacts with the Kubernetes cluster thanks to the fabric8.io Kubernetes client for Java.
See here for the compatibility matrix and here for the current version used by Onyxia.

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.