Enhancement for values.json.schema and this is handle in onyxia ecosystem.. (launcher of helm charts)

[fcomte]

Onyxia utilizes a JSON schema located within each chart to dynamically create forms as users initiate services. This schema fulfills two main functions:

1. Validation Control: It ensures that user inputs adhere to specific requirements, such as data types, mandatory fields, and value ranges. This helps in maintaining data integrity and reducing errors during processing.

This validation process isn't widely implemented because we aim for any instance to utilize our open-source chart as a subchart. For instance, we have introduced a specific field called 'listEnum' instead of the standard 'enum' for Docker images.

2. UI Specification: The schema also defines the layout and elements of the user interface. For instance, it can specify whether a data input field should appear as a text box, a dropdown menu, or a set of checkboxes. It might also include details like labels which assist in automatically generating the user interface based on the schema specifications.

Description of the problems

Handling a nodeSelector object in a dynamic form schema like Onyxia's is particularly challenging due to its dependency on specific contexts. Here's a generic pattern that could be incorporated into an opensource Helm chart.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Node Selector",
  "description": "A nodeSelector is an object with arbitrary string key-value pairs, used to select specific nodes.",
  "additionalProperties": {
    "type": "string",
    "description": "The value for the node label, which must be a string."
  }
}

However, for a specific instance (maybe region in fact), it would be crucial to use this particular pattern instead to create a practical and effective chart.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Node Selector",
  "description": "A nodeSelector with optional known key-value pairs, each key having exactly one allowed value.",
  "properties": {
    "zone": {
      "type": "string",
      "enum": ["east"],
      "description": "Specifies the node must be in the 'east' zone. This key is optional."
    },
    "diskType": {
      "type": "string",
      "enum": ["ssd"],
      "description": "Specifies the node must use 'ssd' type disks. This key is optional."
    },
    "cpuClass": {
      "type": "string",
      "enum": ["high"],
      "description": "Specifies the node must have 'high' CPU power class. This key is optional."
    }
  },
  "additionalProperties": false
}

Idea and proposal

In JSON Schema, $ref is a keyword used to reference a definition or a schema fragment from elsewhere within the same document or from an external document. This allows you to reuse pieces of a schema without having to duplicate code, which can make your schemas more manageable and easier to maintain.

For example, if you have a common structure that is used in multiple places within a schema, you can define it once and then reference it wherever needed using $ref. This is particularly useful for large schemas or schemas that share common data structures across various parts of an application.

We recommend configuring the values.schema.json in this way.
The base ID will be determined by the specific instance URL for all subsequent schemas.

{
"$id": "https://datalab.sspcloud.fr/api/schemas/(...catalog, chart et version id)",
"type": "object",
"properties": {
    .....
    "nodeSelector": { "$ref": "api/schemas/nodeSelector" }
}

Onyxia-api or any similar schema management module could by default provide the following standard object.

{
  "$id": "https://datalab.sspcloud.fr/api/schemas/nodeSelector",
  "title": "Node selector",
  "description": "A simple form with additional properties example.",
  "type": "object",
  "additionalProperties": {
    "type": "string"
  }
}

But instance (or region) may overwrite this schema and provide instead the following schema

{
  "$id": "https://datalab.sspcloud.fr/api/schemas/nodeSelector",
  "type": "object",
  "title": "Node Selector",
  "description": "A nodeSelector with a restricted list of known key-value pairs.",
  "properties": {
    "zone": {
      "type": "string",
      "enum": ["east", "west"],
      "description": "Specifies the zone of the node which must be either 'east' or 'west'."
    },
    "diskType": {
      "type": "string",
      "enum": ["ssd", "hdd"],
      "description": "Type of disk, which must be either 'ssd' or 'hdd'."
    },
    "cpuClass": {
      "type": "string",
      "enum": ["high", "medium", "low"],
      "description": "Class of CPU power, which must be either 'high', 'medium', or 'low'."
    }
  },
  "additionalProperties": false
}

In summary, we aim to include a collection of standard schemas within Onyxia, allowing administrators the ability to override them. This approach will offer a highly versatile solution applicable across all instances.

Additionally, it will be possible to introduce new schemas

[garronej]

Enabling Onyxia instance owners to overwrite the default schema is a brilliant idea that I'm looking forward to implementing in Onyxia!
It will be very powerful to enable defining validation based on the specificities of a particular deployment. You did a good job conveying this in this post.

However I have reservations regarding the $ref implementation.
The good thing is that it's a standard; however, introducing it would effectively make the values.schema.json of our chart unprocessable by any tool other than Onyxia.
To get the definition of "$ref": "api/schemas/nodeSelector", you'd have to make a GET request to datalab.sspcloud.fr/api/schemas/nodeSelector.
I'm not very comfortable with the Helm Chart Catalog being that tied to our Onyxia instance. I'd prefer them to remain usable as standalone pieces of technology.
The definition of the value's schema of a chart would become spread out between multiple locations. Some common field schemas would be defined in the default region, that is in the onyxia-api code, and most of the rest will be in the values.schema.json of the charts.

I would personally prefer an approach where an Onyxia instance administrator could configure in his region the specific field definitions he wished to override.

It would look something like:

apps/onyxia/values.yaml

 onyxia:
   ingress:
     enabled: true
     hosts:
       - host: datalab.$DOMAIN
   web:
     env:
       # ...
   api:
     catalogs:
       [
         {
           id: "ide",
           location: "https://inseefrlab.github.io/helm-charts-interactive-services"
         },
         {
           id: "databases",
           location: "https://inseefrlab.github.io/helm-charts-databases"
         }
       ]
     regions: [
       {
         id: "my-region",
         services: {
           type: "KUBERNETES",
           singleNamespace: true,
           authenticationMode: "serviceAccount",
           expose: {
             domain: "lab.$DOMAIN"
           }
         },
+        valuesSchemaOverride: [
+          {
+            targets: {
+              path: "nodeSelector"
+            },
+            schema: {
+              properties: {
+                zone: {
+                  type: "string",
+                  enum: ["east", "west"],
+                  description: "Specifies the zone of the node which must be either 'east' or 'west'."
+                },
+                diskType: {
+                  type: "string",
+                  enum: ["ssd", "hdd"],
+                  description: "Type of disk, which must be either 'ssd' or 'hdd'."
+                },
+                cpuClass: {
+                  type: "string",
+                  enum: ["high", "medium", "low"],
+                  description: "Class of CPU power, which must be either 'high', 'medium', or 'low'."
+                }
+              },
+              additionalProperties: "unset"
+            }
+          },
+          {
+            targets: {
+              catalogId: "ide",
+              chartName: "jupyter-*",
+              path: "service.image.version"
+            },
+            schema: {
+              enum: [
+                "inseefrlab/onyxia-jupyter-python:py3.11.6",
+                "inseefrlab/onyxia-jupyter-python:py3.10.13",
+                "inseefrlab/onyxia-jupyter-python:py4.0.0-beta.0"
+              ],
+              default: "inseefrlab/onyxia-jupyter-python:py4.0.0-beta.0"
+            }
+          }
+        ]
+      }
     ]

Let's break down how this would be applied.

The following would mean that the schema override would apply to every chart of every catalog which has a nodeSelector property.

targets: {
    path: "nodeSelector"
}

If this is the relevant part of the schema in the values.schema.json:

{
    "nodeSelector": {
        "type": "object",
        "title": "Node Selector",
        "description": "A nodeSelector is an object with arbitrary string key-value pairs, used to select specific nodes.",
        "additionalProperties": {
            "type": "string",
            "description": "The value for the node label, which must be a string."
        }
    }
}

The following schema overrides will be applied to it:

{
    properties: {
      zone: {
        type: "string",
        enum: ["east", "west"],
        description: "Specifies the zone of the node which must be either 'east' or 'west'."
      },
      diskType: {
        type: "string",
        enum: ["ssd", "hdd"],
        description: "Type of disk, which must be either 'ssd' or 'hdd'."
      },
      cpuClass: {
        type: "string",
        enum: ["high", "medium", "low"],
        description: "Class of CPU power, which must be either 'high', 'medium', or 'low'."
      }
    },
    additionalProperties: "unset"
}

Which would result, after merge into this specification being used for nodeSelector value:

{
    "nodeSelector": {
        "type": "object",
        "title": "Node Selector",
        "description": "A nodeSelector is an object with arbitrary string key-value pairs, used to select specific nodes.",
        "properties": {
          "zone": {
            "type": "string",
            "enum": ["east", "west"],
            "description": "Specifies the zone of the node which must be either 'east' or 'west'."
          },
          "diskType": {
            "type": "string",
            "enum": ["ssd", "hdd"],
            "description": "Type of disk, which must be either 'ssd' or 'hdd'."
          },
          "cpuClass": {
            "type": "string",
            "enum": ["high", "medium", "low"],
            "description": "Class of CPU power, which must be either 'high', 'medium', or 'low'."
          }
        }
    }
}

We could discuss of the format and specific specification of the targets property that enables to precisely filter the where the schema override should be applied but I think the above example does enough to convey the idea at this stage of the reflection.

Advantages of the proposed approach:

• It gives full control to the Onyxia instance administrator to edit the values schema however he sees fit, even without having ownership of the helm chart repo. In the original proposition, it is at the discretion of the chart maintainer to define what property can be overwritten.
• It's very concise. Only the properties that would need to diverge from the default values have to be specified.
• The Charts remain usable standalone thing. Other tools like Kubeapps would remain able to consume them.

Drawback of this approach:

• It would be at the charge of the Onyxia instance administrator to know which properties are relevant to be overwritten at the instance level.
• The syntax for writing overwriting rules in the region is arguably less straightforward than what it would be if the initial proposal were to be implemented.

Here are the measures that could be taken to mitigate these drawbacks:

• Provide in onyxia-ops canonical overwrite as frames of reference.
• Put up a web app in the like of the react-jsonschema-form playground that would generate in real-time, given a values.schema.json, a region configuration and a XOnyxia context:
  • The schema resulting of the merge.
  • The form as it would be rendered in the Onyxia Launcher page.

This would be very empowering for Onyxia instance maintainers, significantly improving the ease of crafting custom configurations.

Regardless of the option we land on, I think this will be a big leap forward for Onyxia. 🚀

[slim0]

1. Validation Control: It ensures that user inputs adhere to specific requirements, such as data types, mandatory fields, and value ranges. This helps in maintaining data integrity and reducing errors during processing.
   This validation process isn't widely implemented because we aim for any instance to utilize our open-source chart as a subchart. For instance, we have introduced a specific field called 'listEnum' instead of the standard 'enum' for Docker images.

Not sure to understand the constraints related to the subcharts.
We just did some tests and it seems possible to overwrite the values.schema.json in a subchart.
So even if there is a strong policy at the base chart, it should be possible to overwrite it on a subchart. (we only try it using the helm lint command, but I think it is the same validation procedure for installation...).

We don't use Region in our onyxia instance, but from what I read, your proposition seems interesting. Essentially because :

It gives full control to the Onyxia instance administrator to edit the values schema however he sees fit, even without having ownership of the helm chart repo.

[johnksv]

Hi! As discussed on the community call Both proposal have their pros and cons. My suggestion is to implement the proposal by @garronej first and see how this fit the need of the users, as this is simpler to implement and does not block the proposal by @fcomte if we see that the solution is not a good fit.