forked from truenas/charts
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
NAS-118965 / 23.10 / Update documentation (truenas#998)
* 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
- Loading branch information
Showing
12 changed files
with
489 additions
and
80 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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" | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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` | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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` | |
Oops, something went wrong.