Extending Helm chart parameters with metadata

When a Helm chart is deployed in the IBM® Cloud Private web console, a Parameters section is displayed in the Configuration tab. The Configuration tab displays all of the parameters that are declared in the values.yaml file that is packaged in the chart.tgz file based on type inference. Chart developers can optionally package an additional values-metadata.yaml file in the chart.tgz file which is used by the IBM® Cloud Private web console to enhance the deployment experience.

The values.yaml file

Helm charts must include a values.yaml file, which declares the parameters for the chart. The format of this file does not allow for the parameters to be formally described.

The values-metadata.yaml file

Chart developers can optionally package an additional values-metadata.yaml file in the chart.tgz file which is used by the IBM® Cloud Private web console to enhance the presentation of the parameters during deployment. For example, instead of a generic text box for a string parameter, the metadata file could indicate the parameter is limited to a set of strings. This set of strings can be presented as a drop down selection list to the user.

The metadata defined in the values-metadata.yaml file extends the information that is in the values.yaml file. The structure of the values-metadata.yaml must be the same as that of the values.yaml file, except that each property is identified as __metadata.

When the values-metadata.yaml file or a specific parameter is missing, the IBM® Cloud Private web console displays all of the default parameters that are declared in the values.yaml file based on type inference.

Values-metadata.yaml specifications

You can define the metadata for each parameter in the values-metadata.yaml file by beginning it with the __metadata key. Each parameter can include one or more of the following attributes:

Property	Data type	Possible Values	Default value	Description	Applicable to grouping ___metadata
description	String	String (146 characters, or less)		Description of the parameter. This should appear in a tooltip or, if there is a group description, as a subheader.	true
hidden	Boolean	true, false	false	If hidden = true, the element is hidden (does the same thing as immutable, but the form field is never exposed in the UI).	false
immutable	Boolean	true, false	false	If immutable = true, the user is not allowed to modify the parameter (field = disabled).	false
label	String			Title of the parameter. If label is not specified, then key from the `values.yaml` file is used.	true
multiline	Boolean	true, false	false	If type = string, display a text area field.	false
options	Array of Objects, where each object has the shape `label: any, value: any`.			Describes a parameter that would transform into a dropdown.	false
required	Boolean	true, false	false	Describes if the parameter is required. If so, a `*` is displayed beside name in the web console.	false
type	String	string, boolean, number, password		Type of the parameter (Note: Array and object are also `type: string` to resolve historical backwards-compatibility issues)	false
validation	String (regex)	any valid Javascript regex .		Regular expression to validate parameter value.	false

Values-metadata.yaml structure example

The following content shows an example of how to create your own metadata parameters in the values-metadata.yaml file:

demonstration:
  __metadata:
    label: Demonstration
    description: I am an h2
  stringField:
    __metadata:
      label: String field
      type: string
      required: true
  numberField:
    __metadata:
      label: Number field (with validation)
      type: number
      required: true
  checkboxField:
    __metadata:
      label: Checkbox field
      type: boolean
      required: true
  selectField:
    __metadata:
      label: Select field
      type: string
      required: true
      options:
      - label: myOpt1
        value: myNotSelectedValue
      - label: myOpt2
        value: mySelectedValue
  multilineField:
    __metadata:
      label: Multiline field
      type: string
      multiline: true
      required: true
  immutableField:
    __metadata:
      label: Immutable field
      type: string
      required: true
      immutable: true
  arrayField:
    __metadata: ### arrayField: "[]" or [] must be set in values.yaml (see below for details).
      label: Array field
      type: string   ### do to backwards-compat bug, type must be string
      description: I am an array.
      required: true
  objectField: ### objectField: "{}" or {} must be set in values.yaml (see below for details)
    __metadata:
      label: Object field (new)
      type: string   ### do to backwards-compat bug, type must be string
      description: I am an object.
      required: true

Parameter characteristics

required: Field cannot be empty if the required parameter is set to true. If empty, the installation does not complete, and an error message is displayed.

Example:

__metadata:
  label: Datacenter
  description: Datacenter description
  type: string
  immutable: false
  required: true

string: Input element. There is no default validation.

__metadata:
  label: Datacenter
  description: Datacenter description
  type: string
  immutable: false
  required: false

number: Input element with type='number'. Number validation is completed.

__metadata:
  label: Datacenter
  description: Datacenter description
  type: number
  immutable: false
  required: false

password: Input element with type="password". There is no default validation.

__metadata:
  label: Datacenter
  description: Datacenter description
  type: password
  required: true

options: Creates a drop down menu with the options.

__metadata:
  label: Datacenter
  description: Datacenter description
  type: string
  required: false
  options:
  -
   label: foo
   value: 123
  -
   label: bar
   value: bar

boolean: Creates a check box.

__metadata:
  label: Datacenter
  description: Datacenter description
  type: boolean
  required: true

multiline: Creates an editable text area. New line characters are preserved.

__metadata:
  label: loggingOptions
  description: loggingOptions
  type: string
  multiline: true

immutable: This entry must remain as it is, and cannot be edited.

__metadata:
  label: loggingOptions
  description: loggingOptions
  type: string
  immutable: true

hidden: The required value is provided to the values.yaml file, but is not displayed on the web console.

__metadata:
  label: loggingOptions
  description: loggingOptions
  type: string
  hidden: true

yaml widget (array): Array widget expects input provided in YAML format. Validation is run on the array format, and a message is shown if the array format is not valid. Note: because of a backwards compatibility bug, the type must be string.

/* values.yaml */
loggingOptions: []

// or

loggingOptions: "[]"

// ...to set a default for the field:

loggingOptions:
  - 1
  - 2
  - 3

/* values-metadata.yaml */
__metadata:
  label: loggingOptions
  description: loggingOptions
  type: string  ### because of a backwards compatibility bug, the type *must* be string.
  ...

yaml widget (object): Object widget expects input provided in YAML format. Validation is run on the object format, and a message is shown if the object format is not valid. Note: because of a backwards compatibility bug, the type must be string.

/* values.yaml */
loggingOptions: "{}"

// or

loggingOptions: {}

// (there is currently no way to set a default)

/* values-metadata.yaml */
__metadata:
  label: loggingOptions
  description: loggingOptions
  type: string  ### because of a backwards compatibility bug, the type *must* be string.
  ...

User example

The following example shows how you can use the previous example to display your content:

database:
  readinessProbePeriodSeconds:
    __metadata:
      label: I am a label
      description: I am a custom description
      type: number
      immutable: false
      required: false
  readinessProbeInitialDelaySeconds:
    __metadata:
      label: I am a label
      description: I am a custom description
      type: number
      required: false
  livenessProbePeriodSeconds:
    __metadata:
      label: I am a label
      type: number
      required: false
  livenessProbeInitialDelaySeconds:
    __metadata:
      label: I am a label
      description: I am a custom description
      type: number
      required: false