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.