truenas/chart
1
0
Fork 0
mirror of https://github.com/truenas/charts.git synced 2026-11-03 22:24:05 +08:00
Code Issues Packages Projects Releases Wiki Activity

NAS-118965 / 23.10 / Update documentation (#998)

Browse Source 
* update *.md formatting

* upgrade string schema

* add some extra fields

* add some extra options

* add int

* full variable expample

* add boolean

* expand

* add dict

* typo

* add list

* more docs

* add show_if operators

* change description

* add some notes
This commit is contained in:
Stavros Kois
2023-04-12 15:53:22 +03:00
committed by GitHub
parent 3efd747d4e
commit 42ea4d99ed
12 changed files with 488 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
docs/README.md Normal file
View File

@@ -0,0 +1,64 @@
# Questions.yaml structure
This file have some top level attributes:
- Groups
- Portals
- Questions
## Groups
Groups can be defined to "group" questions together. This is useful when you have a lot of questions and want to split them into logical groups.
```yaml
groups:
- name: "Group 1"
description: "Description of group 1"
- name: "Group 2"
description: "Description of group 2"
```
- `name` is what will be used to reference the group in the `questions.yaml` file.
- `description` is a what will be displayed in the UI.
> Groups can only be referenced by the top level variables in `questions` attribute.
## Portals
Portals can be defined to display a button on the UI that will open a new tab to a specific URL.
```yaml
portals:
button_name:
protocols:
- https
host:
- example.com
ports:
- 443
path: /path/to/something
```
> You can define more than 1 portal. But the name of the portal must be unique.
Portals support some variables that can be used to dynamically generate the URL.
- `$variable-VARIABLE_NAME.NESTED_VARIABLE_NAME` will be replaced by the value of the variable `NESTED_VARIABLE_NAME` under the variable `VARIABLE_NAME`.
(Variables are defined in the `questions` attribute)
- `$kubernetes-resource_configmap.RESOURCE_NAME.RESOURCE_KEY` will be replaced by the value of the key `RESOURCE_KEY` in the configmap named `RESOURCE_NAME`.
- `$node_ip` will be replaced by the IP of the node where the app is running.
## Questions
Questions are the main attribute of the `questions.yaml` file. It is used to define the questions that will be displayed in the UI.
```yaml
questions:
- variable: variable_name
label: Friendly Name
group: "Group 1"
description: "Description of the variable"
schema:
type: string
default: "something"
```

30
docs/schema/boolean.md Normal file
View File

@@ -0,0 +1,30 @@
# Boolean Schema
## Example of boolean schema options
```yaml
- variable: boolean_variable
label: Boolean Variable
description: Description of boolean variable
schema:
type: boolean
required: true
editable: true
immutable: true
hidden: true
default: true
```
Following attributes can be added to `boolean` schema to enforce validation when a chart release is being created/edited:
Those attributes are set in the schema during the chart development and are not user configurable.
| Attribute | Type | Default | Description |
| :--------------------- | :----------: | :-----: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `immutable` | `boolean` | `false` | When set to true, the value of this variable cannot be changed after the chart is installed. |
| `required` | `boolean` | `false` | When set to true, the value of this variable is required to be set to `true`, Useful when user is required to "accept" terms of use for example. |
| `editable` | `boolean` | `false` | When set to true, the value of this variable cannot be edited by the user. Useful if you want a user to see the value but not be able to edit. |
| `hidden` | `boolean` | `false` | When set to true, this variable is is hidden from the user. |
| `default` | `boolean` | `false` | When set to a boolean, the value of this variable will be set to the specified value by default. |
| `show_if` | `expression` | unset | When set to an [expression](show_if.md#expression-syntax) that evaluates to true, it will make the variable visible and effective. If it evaluates to false, it will be hidden and it won't be passed to the helm chart |
| `show_subquestions_if` | `boolean` | unset | When set to a value and the parent value matches, it will show the subquestions. Note that subquestion variables will be passed to the helm chart on the same level as the "parent" variable. It won't be nested. |
| `subquestions` | `dict` | unset | Define subquestion variables, following the usual schema per type, only difference is that you **can't** define `show_subquestions_if` under `subquestions` |

28
docs/schema/dict.md Normal file
View File

@@ -0,0 +1,28 @@
# Dict Schema
## Example of dict schema options
```yaml
- variable: dict_variable
label: Dict Variable
description: Description of dict variable
schema:
type: dict
additional_attrs: true
show_if: [[ "some_variable", "=", "some_value" ]]
attrs:
- variable: string_variable
label: String Variable
description: Description of string variable
schema:
type: string
```
Following attributes can be added to `dict` schema to enforce validation when a chart release is being created/edited:
Those attributes are set in the schema during the chart development and are not user configurable.
| Attribute | Type | Default | Description |
| :----------------- | :----------: | :-----: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `additional_attrs` | `boolean` | `false` | When set to `true`, allows additional variables to be added. |
| `attrs` | `dict` | unset | Define variables within the dict |
| `show_if` | `expression` | unset | When set to an [expression](show_if.md#expression-syntax) that evaluates to true, it will make the variable visible and effective. If it evaluates to false, it will be hidden and it won't be passed to the helm chart |

38
docs/schema/int.md Normal file
View File

@@ -0,0 +1,38 @@
# Int Schema
## Example of int schema options
```yaml
- variable: int_variable
label: Int Variable
description: Description of int variable
schema:
type: int
required: true
editable: true
immutable: true
hidden: true
"null": true
min: 5
max: 12
valid_chars: "[0-9]{3}"
default: 10
```
Following attributes can be added to `int` schema to enforce validation when a chart release is being created/edited:
Those attributes are set in the schema during the chart development and are not user configurable.
| Attribute | Type | Default | Description |
| :--------------------- | :----------: | :-----: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `immutable` | `boolean` | `false` | When set to true, the value of this variable cannot be changed after the chart is installed. |
| `required` | `boolean` | `false` | When set to true, the value of this variable is required and cannot be empty. |
| `editable` | `boolean` | `false` | When set to true, the value of this variable cannot be edited by the user. Useful if you want a user to see the value but not be able to edit. |
| `hidden` | `boolean` | `false` | When set to true, this variable is is hidden from the user. |
| `"null"` | `boolean` | `false` | When set to true, this variable can be `null`. |
| `min` | `integer` | unset | When set to a value greater than 0, the value of this variable cannot be smaller than the specified number. |
| `max` | `integer` | unset | When set to a value greater than 0, the value of this variable larger than the specified number. |
| `valid_chars` | `string` | unset | When set to a regex, the value of this variable must conform to the specified regex. Underneath the [Python3 Regex Library](https://docs.python.org/3/library/re.html) is used. |
| `default` | `int` | unset | When set to an int, the value of this variable will be set to the specified value by default. |
| `show_if` | `expression` | unset | When set to an [expression](show_if.md#expression-syntax) that evaluates to true, it will make the variable visible and effective. If it evaluates to false, it will be hidden and it won't be passed to the helm chart |
| `show_subquestions_if` | `int` | unset | When set to a value and the parent value matches, it will show the subquestions. Note that subquestion variables will be passed to the helm chart on the same level as the "parent" variable. It won't be nested. |
| `subquestions` | `dict` | unset | Define subquestion variables, following the usual schema per type, only difference is that you **can't** define `show_subquestions_if` under `subquestions` |

48
docs/schema/list.md Normal file
View File

@@ -0,0 +1,48 @@
# List Schema
## Example of list schema options
```yaml
- variable: list_variable
label: List Variable
description: Description of list variable
schema:
type: list
show_if: [["some_variable", "=", "some_value"]]
default: ["value1", "value2"]
# Single Variable (Passed to helm chart as a list of strings (or the type defined))
items:
- variable: string_variable
label: String Variable
description: Description of string variable
schema:
type: string
# Dicts (Passed to helm chart as a list of dicts)
items:
- variable: dict_variable
label: Dict Variable
description: Description of dict variable
schema:
type: dict
attrs:
# Dict can have one or more variables
- variable: string_variable
label: String Variable
description: Description of string variable
schema:
type: string
- variable: int_variable
label: Int Variable
description: Description of int variable
schema:
type: int
```
Following attributes can be added to `list` schema to enforce validation when a chart release is being created/edited:
Those attributes are set in the schema during the chart development and are not user configurable.
| Attribute | Type | Default | Description |
| :-------- | :----------: | :-----: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `show_if` | `expression` | unset | When set to an [expression](show_if.md#expression-syntax) that evaluates to true, it will make the variable visible and effective. If it evaluates to false, it will be hidden and it won't be passed to the helm chart |
| `default` | `list` | unset | A default list of items can be defined in a `json` format. Single variable, multiple values: `["value1", "value2"]`. Dict variable, Multiple variables: `[{"var1": "val1", "var2": "val2"}, {"var1": "other_val1", "var2": "other_val2"}]` |
| `items` | `dict` | unset | Define variables within the dict. This is like a template. Each time user clicks "Add" a form containing the defined variables will be presented |

133
docs/schema/ref/README.md Normal file
View File

@@ -0,0 +1,133 @@
# $ref
Key `$ref` can be defined under `schema`. It's used to fetch values from the host system API.
Supported actions:
- Definitions
- Normalize
## Definitions
### Timezone
This will populate a drop down menu of timezones.
```yaml
- variable: timezone
label: Configure timezone
group: Configuration
description: "Configure timezone"
schema:
type: string
$ref:
- "definitions/timezone"
```
This returns a string with the timezone name. For example `America/New_York`.
### Interface
This will populate a drop down menu of network interfaces.
```yaml
- variable: interface
label: Configure network interface
group: Configuration
description: "Configure network interface"
schema:
type: string
$ref:
- "definitions/interface"
```
This returns a string with the interface name. For example `eth0`.
### GPU
This will populate a drop down menu of GPU configurations.
```yaml
- variable: interface
label: Configure network interface
group: Configuration
description: "Configure network interface"
schema:
type: dict
$ref:
- "definitions/gpuConfiguration"
```
This will return a dict with the following format:
```yaml
gpuConfiguration:
nvidia.com/gpu: "1"
```
### Node IP
This will populate with the IP of the node where the app is running.
```yaml
- variable: host
label: "Node IP"
schema:
type: string
$ref:
- "definitions/nodeIP"
```
### Certificate
This will populate the drop down menu with the certificates that are available in the host system.
```yaml
- variable: certificate
label: "Certificate"
schema:
type: int
$ref:
- "definitions/certificate"
```
This will return an integer with the certificate ID.
You can use this ID to get certificate values from `.Values.ixCertificates`.
Format:
```yaml
ixCertificates:
"1":
privatekey: |
-----BEGIN PRIVATE KEY-----
........................
-----END PRIVATE KEY-----
certificate: |
-----BEGIN CERTIFICATE-----
........................
-----END CERTIFICATE-----
...
```
## Normalize
### ixVolume
```yaml
- variable: datasetName
label: "Configuration Volume Dataset Name"
schema:
type: string
default: config
$ref:
- "normalize/ixVolume"
```
Defining a value here (eg. `config`) will instruct API to create a "volume" in the user configured ix-application dataset.
Then within the helm chart you can search in `.Values.ixVolumes` for the dataset name and get the mount point.
`.Values.ixVolumes` is a list of dicts with the following format:
```yaml
ixVolumes:
- hostPath: /mnt/POOL/ix-applications/APP/DATASET_NAME
```

40
docs/schema/show_if.md Normal file
View File

@@ -0,0 +1,40 @@
# Show if
`show_if` can only access variables that are defined in the same level as the variable that has `show_if` defined.
## Expression syntax
`[[ "variable_name", "operator", "value" ]]`
| Operator | Description | Example |
| :------: | :-------------------------------------------------------------- | :--------------------------------------- |
| `=` | Value of `variable_name` is equal to "value" | `[[ "variable_name", "=", "value" ]]` |
| `!=` | Value of `variable_name` is not equal to "value" | `[[ "variable_name", "!=", "value" ]]` |
| `>` | Value of `variable_name` is greater than "value" | `[[ "variable_name", ">", "10" ]]` |
| `>=` | Value of `variable_name` is greater or equal to "value" | `[[ "variable_name", ">=", "10" ]]` |
| `<` | Value of `variable_name` is less than "value" | `[[ "variable_name", "<", "10" ]]` |
| `<=` | Value of `variable_name` is less or equal than "value" | `[[ "variable_name", "<=", "10" ]]` |
| `in` | Value of `variable_name` is contained in "value" | `[[ "variable_name", "in", "value" ]]` |
| `nin` | Value of `variable_name` is **not** contained in "value" | `[[ "variable_name", "nin", "value" ]]` |
| `rin` | Value of `variable_name` includes "value" | `[[ "variable_name", "rin", "value" ]]` |
| `rnin` | Value of `variable_name` does **not** include "value" | `[[ "variable_name", "rnin", "value" ]]` |
| `^` | Value of `variable_name` starts with "value" | `[[ "variable_name", "^", "value" ]]` |
| `!^` | Value of `variable_name` does not start with "value" | `[[ "variable_name", "!^", "value" ]]` |
| `$` | Value of `variable_name` ends with "value" | `[[ "variable_name", "$", "value" ]]` |
| `!$` | Value of `variable_name` does not end with "value" | `[[ "variable_name", "!$", "value" ]]` |
| `~` | Value of `variable_name` matches the regular expression "value" | `[[ "variable_name", "~", "value" ]]` |
Examples:
```yaml
- variable: variable1
label: Variable 1
schema:
type: string
default: "some value"
- variable: variable2
label: Variable 2
schema:
type: string
show_if: [["variable2", "=", "some value"]]
```

61
docs/schema/string.md
View File

@@ -1,28 +1,57 @@
## String Schema
# String Schema
## Example of string schema options
#### Example of string schema options:
```
schema:
```yaml
- variable: string_variable
label: String Variable
description: Description of string variable
schema:
type: string
private: true
required: true
editable: true
immutable: true
hidden: true
min_length: 5
max_length: 12
default: "default_value"
valid_chars: "[a-zA-Z0-9]$"
enum:
- value: "value1"
description: "Description of value1"
show_if: [["variable1", "=", "some value"]]
show_subquestions_if: "value1"
subquestions:
- variable: subquestion1
label: Subquestion 1
schema:
type: string
required: true
```
Following attributes can be added to string schema to enforce validation when a chart release is being created/edited:
Following attributes can be added to `string` schema to enforce validation when a chart release is being created/edited:
Those attributes are set in the schema during the chart development and are not user configurable.
`min_length` is an integer field which adds validation to ensure value provided for this variable is at least the specified
characters.
| Attribute | Type | Default | Description |
| :--------------------- | :----------: | :-----: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `immutable` | `boolean` | `false` | When set to true, the value of this variable cannot be changed after the chart is installed. |
| `private` | `boolean` | `false` | When set to true, each character of the value will appear as `*` in the UI. Useful for sensitive fields like passwords. |
| `required` | `boolean` | `false` | When set to true, the value of this variable is required and cannot be empty. |
| `editable` | `boolean` | `false` | When set to true, the value of this variable cannot be edited by the user. Useful if you want a user to see the value but not be able to edit. |
| `hidden` | `boolean` | `false` | When set to true, this variable is is hidden from the user. Useful if you want to set a value that is populated from a `$ref` during the installation, but you don't want user to see the field. |
| `min_length` | `integer` | unset | When set to a value greater than 0, the value of this variable must be at least the specified characters. |
| `max_length` | `integer` | unset | When set to a value greater than 0, the value of this variable must be at most the specified characters. |
| `valid_chars` | `string` | unset | When set to a regex, the value of this variable must conform to the specified regex. Underneath the [Python3 Regex Library](https://docs.python.org/3/library/re.html) is used. |
| `default` | `string` | unset | When set to a string, the value of this variable will be set to the specified value by default. |
| `enum` | `array` | unset | When set to an array of objects, the `value` of this variable must be one of the specified values. UI will have a dropdown with the values defined. `description` is what the user will see. |
| `show_if` | `expression` | unset | When set to an [expression](show_if.md#expression-syntax) that evaluates to true, it will make the variable visible and effective. If it evaluates to false, it will be hidden and it won't be passed to the helm chart |
| `show_subquestions_if` | `string` | unset | When set to a value and the parent value matches, it will show the subquestions. Note that subquestion variables will be passed to the helm chart on the same level as the "parent" variable. It won't be nested. |
| `subquestions` | `dict` | unset | Define subquestion variables, following the usual schema per type, only difference is that you **can't** define `show_subquestions_if` under `subquestions` |
`max_length` is an integer field which adds validation to ensure value provided for this variable is at max the specified
characters.
## Notes
`private` is a boolean field which when set by chart maintainer, will result in the value of the variable not being
shown to the user in the UI. This is useful for sensitive fields like password where a dummy character is placed for
each character provided for this string in the UI.
`valid_chars` is a string field which chart maintainer can specify to provide a regex to enforce that the value provided
for the variable should conform to a pattern. TrueNAS Scale will use python3 regex (https://docs.python.org/3/library/re.html)
syntax to enforce `valid_chars`.
- Having `required` set to true and an enum with empty `value` will not allow the user to save the form.
- Having `required` set to true and `editable` set to false will not allow the user to save the form.
- Having `editable` set to true and `immutable` set to true will only allow the user to edit the value once. (Same as `immutable` alone)
- Having `hidden` set to true, `required` set to true and `default` without a value will not allow the user to save the form.

2
docs/upgrade.md
View File

@@ -21,7 +21,7 @@ For such custom scenarios, TrueNAS SCALE allows to stop workloads specifically
before a snapshot is taken of an application's volumes. Workloads in this case can
add the following annotation to the deployment/statefulset:
```
```yaml
"ix.upgrade.scale.down.workload": true
```