Better Helm Chart installation experience in OpenShift Console using `values.schema.json`

helm-chart-schema.md

Better Helm Chart installation experience in OpenShift Console using values.schema.json

Introduction

OCP 4.4 introduced native support for Helm Charts including a UI experience in OpenShift Developer Console to install and manage charts.

Release of OCP 4.6 will enhance the Helm experience further more in Developer Console by introducing dynamic form generation in chart installation using values schema.

A chart maintainer can define a schema in values.schema.json file to enable dynamic form chart installation experience in console. A schema is represented as a JSON Schema. It might look something like this:

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "properties": {
    "image": {
      "description": "Container Image",
      "properties": {
        "repo": {
          "type": "string"
        },
        "tag": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "name": {
      "description": "Service name",
      "type": "string"
    },
    "port": {
      "description": "Port",
      "minimum": 0,
      "type": "integer"
    },
    "protocol": {
      "type": "string"
    }
  },
  "required": [
    "protocol",
    "port"
  ],
  "title": "Values",
  "type": "object"
}

Framework

Developer Console uses react-jsonschema-form framework along with some custom implementation to generate dynamic forms based on valid JSON Schema.

• This library partially supports inline schema definition dereferencing, but it only supports local definition referencing.
• The value in the $ref keyword should be a JSON Pointer in URI fragment identifier format.
• Live playground can be used to test the dynamic form generation experience on a basic level using valid JSON Schema.
  • Note: This is just for initial testing. The UX would be totally different from what you actually see on Developer Console.

Tips to craft good Helm Chart schemas

• Convert values.yaml of the chart to valid JSON.

• Use JSON Schema Generator tool to generate JSONSchema from chart value JSON.

• Currently we do not fully support anyOf schema in form generation.

  • From the settings in JSON Schema Generator tool, select First (single achema) from Array validation dropdown.

• Use default property in the schema to provide default value for the form field.

  • Example Schema using default -

    {
      "$id": "#/properties/replicaCount",
      "type": "integer",
      "title": "Replica Count",
      "description": "Number of replicas needed in the deployment.",
      "default": 1,
    }

• Use local definition referencing in the schema to reuse commonly used field schemas.

  • Example schema using referencing -

  {
    "definitions": {
      "address": {
        "type": "object",
        "properties": {
          "street_address": { "type": "string" },
          "city": { "type": "string" },
          "state": { "type": "string" }
        },
        "required": ["street_address", "city", "state"]
      }
    },
    "type": "object",
    "properties": {
      "billing_address": { "$ref": "#/definitions/address" },
      "shipping_address": { "$ref": "#/definitions/address" }
    }
  }

• title property of the schema is used to label the form field.

• description property of the schema is used to provide help text for the form field.

  • Example of properly defined title and description

  "replicaCount": {
    "default": 1,
    "description": "Define number of nodejs pods running",
    "title": "Replica Count",
    "type": "integer"
  }

  

• Schema type of object can be rendered in the form in an expand collapse section to introduce hierarchy into the nested form fields and to keep the form more readable and compact.

  • The object schema is rendered in expand collapse only if it contains title and description properties.
  • Note: Do not add title and description properties in the root schema to avoid having the intial form load up in expand collapse section.
  • Example of expand collapse section of form -

  Collapsed -

  Expanded -

• required property of the schema can be used to define custom order of form fields.

  • All the required properties in a schema are given more priority and are rendered before optional properties in the form.
  • The order of properties in the required array itself is maintained while rendering corresponding form fields in the form and can be used to render important form fields first in the form.

• type of property of the schema is used to validate the form values entered by user.

Sample chart installation experience in Developer Console

Quick Links:

• Schema files in Helm Chart
• react-jsonschema-form
• Live playground for react-jsonschema-form
• JSON Schema Generator tool
• Helm Schema Generator
• Example chart nodejs-ex-k