values.schema.json overrides

Instance Level Customization of the Service Catalog

This is the most common customization path.

It lets you change defaults and constraints without forking catalogs.

Use it to:

• set global policies (example: default RAM, max disk)

• restrict advanced options to specific roles (example: H100 only for users with a specific role assigned)

Mental model

Some fields in a chart’s values.schema.json point to a schema file.

Onyxia ships a set of “well-known” schema files in the API:

onyxia-api/onyxia-api/src/main/resources/schemas at main · InseeFrLab/onyxia-apiGitHub

When a chart uses x-onyxia.overwriteSchemaWith, Onyxia resolves that schema path.

How overwriteSchemaWith works

In the catalog charts (example: InseeFrLab/helm-charts-interactive-services), look for x-onyxia.overwriteSchemaWith in charts/*/values.schema.json.

Example:

charts/jupyter-python/values.schema.json (excerpt)

{
  "properties": {
    "service": {
      "properties": {
        "image": {
          "properties": {
            "custom": {
              "properties": {
                "enabled": {
                  "x-onyxia": {
                    "overwriteSchemaWith": "ide/customImage.json"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

This means: “for this field, use the schema at ide/customImage.json”.

That schema file can come from:

• the default schemas embedded in Onyxia API

• an override you provide at the instance level (see below)

Instance-wide overrides

Let's consider the ide/customImage.json schema for exaple. By default this will be used:

ide/customImage.json (default)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Use a custom image instead",
  "type": "boolean",
  "default": false
}

It enable users to provide a custom Docker image for a given service, let's say we want to remove this option. To do that you would configure your Onyxia instance like this:

apps/onyxia/values.yaml

onyxia:
  api:
    schemas:
      enabled: true
      files:
        - relativePath: ide/customImage.json
          content: |
            {
              "$schema": "http://json-schema.org/draft-07/schema#",
              "hidden": true,
              "const": false
            }

Result: the “custom image” toggle disappears from the launcher.

Other Example: change default resource sliders

This is a typical way to enforce sane defaults and limits for CPU/memory.

apps/onyxia/values.yaml (excerpt)

onyxia:
  api:
    schemas:
      enabled: true
      files:
        - relativePath: ide/resources.json
          content: |
            {
              "$schema": "http://json-schema.org/draft-07/schema#",
              "title": "Resources",
              "description": "Your service will have at least the requested resources and never more than its limits.",
              "type": "object",
              "properties": {
                "requests": {
                  "description": "Guaranteed resources",
                  "type": "object",
                  "properties": {
                    "cpu": {
                      "title": "CPU",
                      "type": "string",
                      "default": "100m",
                      "render": "slider",
                      "sliderMin": 50,
                      "sliderMax": 10000,
                      "sliderStep": 50,
                      "sliderUnit": "m",
                      "sliderExtremity": "down",
                      "sliderExtremitySemantic": "guaranteed",
                      "sliderRangeId": "cpu"
                    },
                    "memory": {
                      "title": "Memory",
                      "type": "string",
                      "default": "2Gi",
                      "render": "slider",
                      "sliderMin": 1,
                      "sliderMax": 200,
                      "sliderStep": 1,
                      "sliderUnit": "Gi",
                      "sliderExtremity": "down",
                      "sliderExtremitySemantic": "guaranteed",
                      "sliderRangeId": "memory"
                    }
                  }
                },
                "limits": {
                  "description": "Max resources",
                  "type": "object",
                  "properties": {
                    "cpu": {
                      "title": "CPU",
                      "type": "string",
                      "default": "5000m",
                      "render": "slider",
                      "sliderMin": 50,
                      "sliderMax": 10000,
                      "sliderStep": 50,
                      "sliderUnit": "m",
                      "sliderExtremity": "up",
                      "sliderExtremitySemantic": "maximum",
                      "sliderRangeId": "cpu"
                    },
                    "memory": {
                      "title": "Memory",
                      "type": "string",
                      "default": "50Gi",
                      "render": "slider",
                      "sliderMin": 1,
                      "sliderMax": 200,
                      "sliderStep": 1,
                      "sliderUnit": "Gi",
                      "sliderExtremity": "up",
                      "sliderExtremitySemantic": "maximum",
                      "sliderRangeId": "memory"
                    }
                  }
                }
              }
            }

Role-based overrides (different schema per user role)

Instance-wide overrides apply to everyone.

You can also apply schema overrides per role.

Onyxia reads roles from the decoded JWT access token.

By default, it uses the roles claim.

You can change that in your OIDC configuration.

See OpenID Connect Configuration.

Example: let fullgpu users choose H100

Here we override the built-in nodeSelector-gpu.json schema only for users with role fullgpu.

Other users still get the default schema.

apps/onyxia/values.yaml

onyxia:
  api:
    schemas:
      enabled: true
      roles:
        - roleName: fullgpu
          files:
            - relativePath: nodeSelector-gpu.json
              content: |
                {
                  "$schema": "http://json-schema.org/draft-07/schema#",
                  "title": "Node Selector",
                  "type": "object",
                  "properties": {
                    "disktype": {
                      "description": "The type of disk",
                      "type": "string",
                      "enum": ["ssd", "hdd"],
                      "default": "ssd"
                    },
                    "gpu": {
                      "description": "The type of GPU",
                      "type": "string",
                      "enum": ["A2", "H100"],
                      "default": "A2"
                    }
                  },
                  "additionalProperties": false
                }

Result: fullgpu users can request GPU nodes and select H100.

Next: user-specific defaults

So far you can override schemas:

• for everyone (instance-wide)

• for a subset of users (per role)

If you want per-user defaults (prefill from identity), use x-onyxia.overwriteDefaultWith.

Follow up with:

x-onyxia