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 therequired
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 thevalues.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