1 of 8

Release Notes & Upgrade Instructions

In this section of the website, you will find a description of the new features introduced in each major version of Onyxia, along with the relevant instructions for upgrading.

v9 -> v10

⚠️ The quotas configuration has finally been cleaned up ! The "old style quota" that was deprecated for more than 1 year has finally been removed. Don't worry, migration is easy : instead of using enabled and default, you have to enable and define quotas for user and groups separately. See https://github.com/InseeFrLab/onyxia-api/blob/main/docs/region-configuration.md#quotas-properties for details. Note that you can now define quotas per role thanks to the new role system introduced in this release. ⚠️

⚠️ This release has refactored some endpoints of the API, especially endpoints regarding catalogs. If you are relying on the Onyxia-API directly (e.g you built a custom frontend) you will notice that some endpoints have been removed / renamed. Note that we don't recommend nor support relying on the Onyxia-API directly but if you do, we would love to hear from you and your usecase. Maybe it could be officially supported and benefit others. ⚠️

New feature You can use overwrite schemas based on role. You can configure role inside Onyxia and provide schema for each role. For more details, refer to the documentation:

v8 -> v9

tl;dr: Breaking change, defaultConfiguration in region configuration is not allowed anymore and has been replaced by JSONSchemas override using the new api.schemas key from v9 helm chart.

Onyxia v9 allows administrators to define custom JSON schemas, allowing them to override the default schemas provided by the chart. Prior to this change, Onyxia relied on providing default values for specific keys in the region configuration : defaultConfiguration.

Chart owners can now define which properties can be overridden using a JSON Schema.

Here is an example of a Chart that supports JSONSchemas (taken from the default IDE catalog, see this link) :

values.schema.json

"nodeSelector": {
      "type": "object",
      "description": "NodeSelector",
      "default": {},
      "x-onyxia": {
          "hidden": false,
          "overwriteDefaultWith": "region.nodeSelector",
          "overwriteSchemaWith": "nodeSelector.json"
      }
    }

The overwriteDefaultWith attribute was the old method for overriding, instructing Onyxia to use the "defaultConfiguration" from the Region. This method is no longer supported in v9, though it can still be used for catalog compatibility with v8.

In v9, overwriteDefaultWith has been replaced by overwriteSchemaWith, which offers more flexibility due to the capabilities of JSON Schemas. Default schemas are bundled with Onyxia-API and will be used if no override is provided. You can find these default schemas here: Onyxia-API Schemas.

To override a schema, use the new schemas key from the v9 Helm chart and provide the list of schemas you want to override. For more details, refer to the documentation: Onyxia v9 Catalog.

Onyxia v9 will fail to start with error message :

FATAL : Setting defaultConfiguration in region is no longer supported and has been replaced by JSONSchema support. See migration guide at https://docs.onyxia.sh/admin-doc/migration-guides/v8-greater-than-v9

if you don't remove the defaultConfiguration from the region configuration.

v7 -> v8

You can now have comments, trailing comas and single quotes in your region and catalog parameters! See the PR.

In this release, the Onyxia S3 integration has been completely revamped!

This is the DIFF you have to apply to your Onyxia configuration assuming you have a typical MinIO integration configured:

onyxia-values.yaml

 ...
 api:
   ...
   regions:
     [
       {
         ...
         "data": {
           "S3": {
-            "type": "minio",
             "URL": "https://minio.lab.my-domain.net",
             "region": "us-east-1",
-            "bucketClaim": "preferred_username",
-            "defaultDurationSeconds": 86400,
-            "oidcConfiguration": {
-              "clientID": "onyxia-minio"
-            },
+            "sts": {
+              "durationSeconds": 86400,
+              "oidcConfiguration": {
+                "clientID": "onyxia-minio"
+              }
+            },
-            "bucketPrefix": "user-",
-            "groupBucketPrefix": "projet-",
+            "workingDirectory": {
+              "bucketMode": "multi",
+              "bucketNamePrefix": "user-",
+              "bucketNamePrefixGroup": "projet-"
+            }
           },
           ...

helm upgrade onyxia inseefrlab/onyxia -f onyxia-values.yaml

v6 -> v7

In this major version a lot of the parameters of the webapp have been updated/refined. Here is the changes you need to apply to your values.json to migrate smoothly.

The `THEME_ID` parameter has been removed.

Onyxia is now fully customizable instead of just letting you pick within a handful of predefined themes.

If you where using the `france` theme:

values.yaml

 onyxia:
   web:
     env:
-      THEME_ID: france
+      FONT: |
+        { 
+          fontFamily: "Marianne", 
+          dirUrl: "%PUBLIC_URL%/fonts/Marianne", 
+          "400": "Marianne-Regular.woff2",
+          "400-italic": "Marianne-Regular_Italic.woff2",
+          "500": "Marianne-Medium.woff2",
+          "700": "Marianne-Bold.woff2",
+          "700-italic": "Marianne-Bold_Italic.woff2"
+        }
+      PALETTE_OVERRIDE: |
+        {
+          focus: {
+            main: "#000091",
+            light: "#9A9AFF",
+            light2: "#E5E5F4"
+          },
+          dark: {
+            main: "#2A2A2A",
+            light: "#383838",
+            greyVariant1: "#161616",
+            greyVariant2: "#9C9C9C",
+            greyVariant3: "#CECECE",
+            greyVariant4: "#E5E5E5"
+          },
+          light: {
+            main: "#F1F0EB",
+            light: "#FDFDFC",
+            greyVariant1: "#E6E6E6",
+            greyVariant2: "#C9C9C9",
+            greyVariant3: "#9E9E9E",
+            greyVariant4: "#747474"
+          }
+        }
+      SOCIAL_MEDIA_IMAGE: "%PUBLIC_URL%/preview-france.png"

If you where using the `ultraviolet` theme:

values.yaml

 onyxia:
   web:
     env:
-      THEME_ID: ultraviolet
+      PALETTE_OVERRIDE: |
+        {
+          focus: {
+            main: "#067A76",
+            light: "#0AD6CF",
+            light2: "#AEE4E3"
+          },
+          dark: {
+            main: "#2D1C3A",
+            light: "#4A3957",
+            greyVariant1: "#22122E",
+            greyVariant2: "#493E51",
+            greyVariant3: "#918A98",
+            greyVariant4: "#C0B8C6"
+          },
+          light: {
+            main: "#F7F5F4",
+            light: "#FDFDFC",
+            greyVariant1: "#E6E6E6",
+            greyVariant2: "#C9C9C9",
+            greyVariant3: "#9E9E9E",
+            greyVariant4: "#747474"
+          }
+        }
+      SOCIAL_MEDIA_IMAGE: "%PUBLIC_URL%/preview-ultraviolet.png"

If you where using the `verdant` theme:

values.yaml

 onyxia:
   web:
     env:
-      THEME_ID: verdant
+      PALETTE_OVERRIDE: |
+        focus: {
+            main: "#1F8D49",
+            light: "#4EFB8D",
+            light2: "#DFFEE6"
+        },
+        light: {
+            main: "#F4F6FF",
+            light: "#F6F6F6",
+            greyVariant1: "#E6E6E6",
+            greyVariant2: "#C9C9C9",
+            greyVariant3: "#9E9E9E",
+            greyVariant4: "#747474"
+        }

Header parameters

values.yaml

 onyxia:
   web:
     env:
-      HEADER_ORGANIZATION: SSP Cloud
+      HEADER_TEXT_BOLD: SSP Cloud
-      HEADER_USECASE_DESCRIPTION: Datalab
+      HEADER_TEXT_FOCUS: Datalab
-      DESCRIPTION: Shared platform for statistical data processing and data science services
+      SOCIAL_MEDIA_DESCRIPTION: Shared platform for statistical data processing and data science services
+      SOCIAL_MEDIA_TITLE: Datalab - SSP Cloud

Links in the header and the left bar

In addition to the parameter EXTRA_LEFTBAR_ITEMS having being renamed to LEFTBAR_LINKS the iconId property has been renamed icon and you can now use any icon from the Material Design library or even provide your own icons. Please refer to the new documentation of the HEADER_LINKS parameter.

values.yaml

 onyxia:
   web:
     env:
-      EXTRA_LEFTBAR_ITEMS: |
+      LEFTBAR_LINKS: |

Assets must now be bundled

You must now bundle your assets such as the terms of services inside your onyxia instance. The newer version of Onyxia won't fetch resource from arbitrary URLs. See CUSTOM_RESOURCES in the .env file.

Keycloak Theme

If you are using the Onyxia Keycloak theme and your instance is public you might want to fill up the ONYXIA_ prefixed environement variable in your Keycloak envs. See install doc.

v5 -> v6

The only breaking change in this release is the split of Onyxia service account into two separate service accounts : one for the API (which usually requires high permission to deploy services) and one for the WEB pod (qui usually should not have any permissions tied to it). Due to this change, the global serviceAccount values key was duplicated in both web.serviceAccount and api.serviceAccount. See:

and

Example of change :

v4 -> v5

The primary breaking change in this release pertains to Keycloak configuration. With this update, you're no longer limited to using Keycloak; any OIDC-compliant identity provider is now supported. To accommodate this new feature, you'll need to make some adjustments to the configuration of your Onyxia instance.

You don't need to specify the issuerURI in multiple locations as we have done here. If you're using just one identity server (You have only one Keycloak server for example), you can set the issuerURI solely in api->env->oidc.issuer-uri.

onyxia-values.yaml

onyxia:
   web:
     env:
-      KEYCLOAK_URL: https://auth.lab.sspcloud.fr/auth
-      KEYCLOAK_REALM: sspcloud
   api:
     env:
-      keycloak.resource: onyxia
-      keycloak.realm: sspcloud
-      keycloak.auth-server-url: https://auth.lab.sspcloud.fr/auth
-      keycloak.ssl-required: external
-      keycloak.public-client: "true"
-      keycloak.enable-basic-auth: "true"
-      keycloak.bearer-only: "true"
+      oidc.issuer-uri: "https://auth.lab.sspcloud.fr/auth/realms/sspcloud"
+      oidc.clientID: "onyxia"
+      oidc.audience: "onyxia"
       authentication.mode: "openidconnect"
     regions: 
       [
         {
           "id": "paris",
           "services": {
-              "authenticationMode": "admin",
+              "authenticationMode": "serviceAccount",
               "k8sPublicEndpoint": {
                 "URL": "https://apiserver.kub.sspcloud.fr",
-                "keycloakParams": {
-                  "URL": "https://auth.lab.sspcloud.fr/auth",
-                  "realm": "sspcloud",
-                  "clientId": "onyxia"
-                },
+                "oidcConfiguration": {
+                  "issuerURI": "https://auth.lab.sspcloud.fr/auth/realms/sspcloud",
+                  "clientID": "onyxia-k8s-apiserver",
+                }
               }
             },
           "data": {
             "S3": {
-              "keycloakParams": {
-                "URL": "https://auth.lab.sspcloud.fr/auth",
-                "realm": "sspcloud",
-                "clientId": "onyxia-minio",
-              }
+              "oidcConfiguration": {
+                "issuerURI": "https://auth.lab.sspcloud.fr/auth/realms/sspcloud",
+                "clientID": "onyxia-minio",
+              }
             }
          },
          "vault": {
              "URL": "https://vault.lab.sspcloud.fr",
-             "keycloakParams": {
-               "URL": "https://auth.lab.sspcloud.fr/auth",
-               "realm": "sspcloud",
-               "clientId": "onyxia-vault",
-             }
+             "oidcConfiguration": {
+               "issuerURI": "https://auth.lab.sspcloud.fr/auth/realms/sspcloud",
+               "clientID": "onyxia-vault"
+             }
         }
       }
     ]

Migrating to the new helm repo

Previously, the Helm chart of Onyxia was hosted on the inseefrlab/helm-charts repo and has now been moved to inseefrlab/onyxia. As a result you would now install Onyxia like this:

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

-helm install onyxia inseefrlab/helm-charts
+helm install onyxia onyxia/onyxia

In the following we assume the current version of Onyxia is 4.1.4 but you are encorging to use the latest version instead. See releases.

If you use ArgoCD for deploying onyxia:

apps/onyxia/Chart.yaml

 apiVersion: v2
 name: onyxia
 version: 1.0.0
 dependencies:
   - name: onyxia
-    version: 4.1.0
+    version: 4.1.4
-    repository: https://inseefrlab.github.io/helm-charts/
+    repository: https://inseefrlab.github.io/onyxia/

You no longer need to manually manage the version of onyxia-web and onyxia-api, now, if you want to update Onyxia, you just update the chart version number.

helm repo add onyxia https://inseefrlab.github.io/onyxia

DOMAIN=my-domain.net

cat << EOF > ./onyxia-values.yaml
# ...
web:
  image:
-   tag: 2.29.4
api:
  image:
-   tag: v0.32   
# ...
EOF

helm install onyxia onyxia/onyxia -f onyxia-values.yaml

For the Keycloak theme, the version is now synchronized with the Onyxia version.

helm repo add codecentric https://codecentric.github.io/helm-charts

cat << EOF > ./keycloak-values.yaml
# ... See https://docs.onyxia.sh/#enabling-user-authentication
extraInitContainers: |
  - name: realm-ext-provider
    image: curlimages/curl
    imagePullPolicy: IfNotPresent
    command:
      - sh
    args:
      - -c
      - |
-       curl -L -f -S -o /extensions/onyxia.jar https://github.com/InseeFrLab/onyxia/releases/download/v2.29.4/keycloak-theme.jar
+       curl -L -f -S -o /extensions/onyxia.jar https://github.com/InseeFrLab/onyxia/releases/download/v4.1.4/keycloak-theme.jar
    volumeMounts:
      - name: extensions
        mountPath: /extensions
extraVolumeMounts: |
  - name: extensions
    mountPath: /opt/jboss/keycloak/standalone/deployments
extraVolumes: |
  - name: extensions
    emptyDir: {}
# ...
EOF

helm install keycloak codecentric/keycloak -f keycloak-values.yaml

Also note that, the theme will now appear as "onyxia" in the dropdown. Previously it was "onyxia-web"

v6 -> v7

In this major version a lot of the parameters of the webapp have been updated/refined. Here is the changes you need to apply to your values.json to migrate smoothly.

The `THEME_ID` parameter has been removed.

Onyxia is now fully customizable instead of just letting you pick within a handful of predefined themes.

If you where using the `france` theme:

values.yaml

 onyxia:
   web:
     env:
-      THEME_ID: france
+      FONT: |
+        { 
+          fontFamily: "Marianne", 
+          dirUrl: "%PUBLIC_URL%/fonts/Marianne", 
+          "400": "Marianne-Regular.woff2",
+          "400-italic": "Marianne-Regular_Italic.woff2",
+          "500": "Marianne-Medium.woff2",
+          "700": "Marianne-Bold.woff2",
+          "700-italic": "Marianne-Bold_Italic.woff2"
+        }
+      PALETTE_OVERRIDE: |
+        {
+          focus: {
+            main: "#000091",
+            light: "#9A9AFF",
+            light2: "#E5E5F4"
+          },
+          dark: {
+            main: "#2A2A2A",
+            light: "#383838",
+            greyVariant1: "#161616",
+            greyVariant2: "#9C9C9C",
+            greyVariant3: "#CECECE",
+            greyVariant4: "#E5E5E5"
+          },
+          light: {
+            main: "#F1F0EB",
+            light: "#FDFDFC",
+            greyVariant1: "#E6E6E6",
+            greyVariant2: "#C9C9C9",
+            greyVariant3: "#9E9E9E",
+            greyVariant4: "#747474"
+          }
+        }
+      SOCIAL_MEDIA_IMAGE: "%PUBLIC_URL%/preview-france.png"

If you where using the `ultraviolet` theme:

values.yaml

 onyxia:
   web:
     env:
-      THEME_ID: ultraviolet
+      PALETTE_OVERRIDE: |
+        {
+          focus: {
+            main: "#067A76",
+            light: "#0AD6CF",
+            light2: "#AEE4E3"
+          },
+          dark: {
+            main: "#2D1C3A",
+            light: "#4A3957",
+            greyVariant1: "#22122E",
+            greyVariant2: "#493E51",
+            greyVariant3: "#918A98",
+            greyVariant4: "#C0B8C6"
+          },
+          light: {
+            main: "#F7F5F4",
+            light: "#FDFDFC",
+            greyVariant1: "#E6E6E6",
+            greyVariant2: "#C9C9C9",
+            greyVariant3: "#9E9E9E",
+            greyVariant4: "#747474"
+          }
+        }
+      SOCIAL_MEDIA_IMAGE: "%PUBLIC_URL%/preview-ultraviolet.png"

If you where using the `verdant` theme:

values.yaml

 onyxia:
   web:
     env:
-      THEME_ID: verdant
+      PALETTE_OVERRIDE: |
+        focus: {
+            main: "#1F8D49",
+            light: "#4EFB8D",
+            light2: "#DFFEE6"
+        },
+        light: {
+            main: "#F4F6FF",
+            light: "#F6F6F6",
+            greyVariant1: "#E6E6E6",
+            greyVariant2: "#C9C9C9",
+            greyVariant3: "#9E9E9E",
+            greyVariant4: "#747474"
+        }

Header parameters

values.yaml

 onyxia:
   web:
     env:
-      HEADER_ORGANIZATION: SSP Cloud
+      HEADER_TEXT_BOLD: SSP Cloud
-      HEADER_USECASE_DESCRIPTION: Datalab
+      HEADER_TEXT_FOCUS: Datalab
-      DESCRIPTION: Shared platform for statistical data processing and data science services
+      SOCIAL_MEDIA_DESCRIPTION: Shared platform for statistical data processing and data science services
+      SOCIAL_MEDIA_TITLE: Datalab - SSP Cloud

Links in the header and the left bar

values.yaml

 onyxia:
   web:
     env:
-      EXTRA_LEFTBAR_ITEMS: |
+      LEFTBAR_LINKS: |

Assets must now be bundled

Keycloak Theme

If you are using the Onyxia Keycloak theme and your instance is public you might want to fill up the ONYXIA_ prefixed environement variable in your Keycloak envs. See install doc.

Release Notes & Upgrade Instructions

Release Notes & Upgrade Instructions

v9 -> v10

v8 -> v9

v7 -> v8

v6 -> v7

The THEME_ID parameter has been removed.

If you where using the france theme:

If you where using the ultraviolet theme:

If you where using the verdant theme:

Header parameters

Links in the header and the left bar

Assets must now be bundled

Keycloak Theme

v5 -> v6

v4 -> v5

Migrating to the new helm repo

v8 -> v9

Release Notes & Upgrade Instructions

v5 -> v6

v4 -> v5

v7 -> v8

v9 -> v10

Migrating to the new helm repo

v6 -> v7

The THEME_ID parameter has been removed.

If you where using the france theme:

If you where using the ultraviolet theme:

If you where using the verdant theme:

Header parameters

Links in the header and the left bar

Assets must now be bundled

Keycloak Theme

The `THEME_ID` parameter has been removed.

If you where using the `france` theme:

If you where using the `ultraviolet` theme:

If you where using the `verdant` theme:

The `THEME_ID` parameter has been removed.

If you where using the `france` theme:

If you where using the `ultraviolet` theme:

If you where using the `verdant` theme: