From cd8b7afa8f7c8ec63a321541a5519a8235d3dd77 Mon Sep 17 00:00:00 2001 From: Waqar Ahmed Date: Tue, 20 Oct 2020 21:40:37 +0500 Subject: [PATCH] Add readme explaining basic schema --- README.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000000..ba779bab75 --- /dev/null +++ b/README.md @@ -0,0 +1,108 @@ +# iX Official Catalog + +A curated collection of TrueNAS SCALE enhanced Helm charts. + +## TrueNAS SCALE Chart Structure + +A TrueNAS SCALE chart repository differs slightly in directory structure from upstream repos in that it includes an `app version` directory. + +A TrueNAS SCALE chart also has three additional files an `app-readme.md` file that provides a high level overview display in the TrueNAS SCALE UI and a `questions.yaml` file defining questions to prompt the user with and an `item.yaml` file outlining item specific details. + +There are 2 directories `charts` and `test`, each representing a train. Chart releases created from catalog items in a specific train cannot be moved to another train. + +``` +charts/ix-chart// + app-readme.md # TrueNAS SCALE Specific: Readme file for display in TrueNAS SCALE UI + charts/ # Directory containing dependency charts + Chart.yaml # Required Helm chart information file + questions.yaml # TrueNAS SCALE Specific: File containing questions for TrueNAS SCALE UI + README.md # Optional: Helm Readme file (will be rendered in TrueNAS SCALE UI as well) + requirements.yaml # Optional YAML file listing dependencies for the chart + templates/ # A directory of templates that, when combined with values.yml will generate K8s YAML + values.yaml # The default configuration values for this chart +``` +*See the upstream Helm chart [developer reference](https://helm.sh/docs/topics/chart_template_guide/) for a complete walk through of developing charts.* + +To convert an upstream chart to take advantage of TrueNAS SCALE enhanced UX, first create an `item.yaml` file. +This file among other catalog item information provides a list of categories that this chart fits into. This helps users navigate and filtering when browsing the catalog UI. + +``` +$ cat charts/ix-chart/item.yaml +categories: + - generic +icon_url: "http://ix_url" +``` + +After that create `app-readme.md` file. + +``` +$ cat charts/ix-chart//app-readme.md + +# Wordpress ROCKS! +``` + +Then add a `questions.yaml` file to prompt the user for something. + +``` +groups: + - name: "Container Images" + description: "Image to be used for container" +questions: + - variable: image + description: "Docker Image Details" + group: "Container Images" + schema: + type: dict + required: true + attrs: + - variable: repository + description: "Docker image repository" + label: "Image repository" + schema: + type: string + required: true + - variable: tag + description: "Tag to use for specified image" + label: "Image Tag" + schema: + type: string + default: "latest" + - variable: pullPolicy + description: "Docker Image Pull Policy" + label: "Image Pull Policy" + schema: + type: string + default: "IfNotPresent" + enum: + - "IfNotPresent" + - "Always" + - "Never" +``` + +The above will prompt the user with 2 text fields and a dropdown in the UI getting details for image configuration in a helm chart. + +#### Question Variable Reference + +| Variable | Type | Required | Description | +| ------------- | ------------- | --- |------------- | +| variable | string | true | define the variable name specified in the `values.yaml`file. | +| label | string | true | define the UI label. | +| description | string | false | specify the description of the variable. | +| group | string | false | group questions by input value. | +| schema | dictionary | true | specify schema details for the `variable` | +| schema.type | string | true | specify type of value for `variable` (current supported types are string, int, boolean, path, hostpath, list, dict, ipaddr, and cron).| +| schema.required | bool | false | define if the variable is required or not (true \ false), defaults to false | +| schema.default | object | false | specify the default value. | +| schema.min_length | int | false | min character length for string type variable.| +| schema.max_length | int | false | max character length for string type variable.| +| schema.min | int | false | min integer length. | +| schema.max | int | false | max integer length. | +| schema.enum | []string | false | specify the options when the variable type is `string`, for example,

enum:
- "RollingUpdate"
- "Recreate"| +| schema.valid_chars | string | false | regular expression for input chars validation. | +| schema.subquestions | []subquestion | false | add an array of subquestions.| +| schema.show_if | string | false | show current variable if condition specified is true, for example `show_if: [["workloadType", "=", "CronJob"]]` | +| schema.show_subquestions_if | string | false | show subquestions if is true or equal to one of the options. for example `show_subquestion_if: "static"`. system will convert this to the filters format specifid for `shcema.show_if` automatically.| +| schema.attrs | []variables | false | specified when `schema.type` is dictionary to declare attributes allowed in the dictionary. | +| schema.items | []variables | false | specified when `schema.type` is list to declare attributes allowed in the list. | + +**subquestions**: `subquestions[]` cannot contain `subquestions` or `show_subquestions_if` keys, but all other keys in the above table are supported. Also variables having `schema.type` list do not support `subquestions`.