DevOps/truecharts
2
0
Fork 0
Code Issues Pull Requests Actions 33 Packages Projects Releases 1 Wiki Activity

Doc patches

Browse Source
This commit is contained in:
kjeld Schouten-Lebbing
2021-05-23 20:34:11 +02:00
parent f8b79ac51a
commit a869e30188
10 changed files with 75 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/development/app development/chart-structure.md
+11 -5
View File
@@ -7,22 +7,28 @@ A TrueNAS SCALE chart also has three additional files an `app-readme.md` file th
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. Currently only the `charts` train can be used inside the UI.
```
charts/ix-chart/<chart version>/
app-readme.md # TrueNAS SCALE Specific: Readme file for display in TrueNAS SCALE UI
charts/<train>/<chart name>/
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)
templates/ # A directory of templates that, when combined with values.yml will generate K8s YAML
values.yaml # The default configuration values for this chart
```
```
charts/<train>/<chart name>/
app-readme.md # TrueNAS SCALE Specific: Readme file for display in TrueNAS SCALE UI
questions.yaml # TrueNAS SCALE Specific: File containing questions for TrueNAS SCALE UI
ix_values.yaml # Hidden configuration values when installing using TrueNAS SCALE
```
*See the upstream Helm chart [developer reference](https://helm.sh/docs/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
$ cat charts/<train>/<chart name>/SCALE/item.yaml
categories:
- generic
icon_url: "http://ix_url"
@@ -31,7 +37,7 @@ icon_url: "http://ix_url"
After that create `app-readme.md` file.
```
$ cat charts/ix-chart/<chart version>/app-readme.md
$ cat charts/<train>/<chart name>/SCALE/app-readme.md
iX-chart is a chart designed to let user deploy a docker image in a TrueNAS SCALE kubernetes cluster.
It provides a mechanism to specify workload type, add external host interfaces in the pods, configure volumes and allocate host resources to the workload.
docs/development/app development/portal.md
+5
View File
@@ -64,3 +64,8 @@ There are also some additional (advanced) options availale, these can be added b
type: string
default: "test.com"
```
##### Known issues
- Portal currently doesn't work (yet) when setting the servicetype to "Loadbalancer"
docs/development/app development/questions-yaml.md
+13 -27
View File
@@ -78,7 +78,7 @@ For (2), system will normalize values or perform some actions as discussed above
To minimise the maintenance load of our App collection, we always aim to standardise as much as possible. The same goes for questions.yaml. Included here are some code standardised code-snippets that are expected to be included in every App.
Be aware that sometimes specific functions might or might not completely function. Leaving them out would, however, everely increase the maintenance load and often said functionality will be added in the common-chart later on anyway.
##### Groups
To make sure all apps stay somewhat the same, we use a standardised `groups:` section. Please make sure to use this in your Apps:
To make sure all apps stay somewhat the same, we use a list of standardised groups for the groups section. Please make sure to use these groups in your Apps:
```
groups:
- name: "Container Image"
@@ -107,24 +107,22 @@ groups:
These options are always* included because almost every chart (eventually) has a use for them and/or other parts of the common chart depend on them.
They are called general options, because they affect the basic functionalities of a chart. For example: Custom User environment variables, permissions and timezones.
*`PUID`, `PGID`, `UMASK` are only included when they are needed.
*`PUID`, `PGID`, `UMASK` are only included when they are needed.
```
- variable: timezone
group: "Configuration"
label: "Timezone"
schema:
type: string
default: "Etc/UTC"
$ref:
- "definitions/timezone"
- variable: env
group: "Configuration"
label: "Image Environment"
schema:
type: dict
attrs:
- variable: TZ
label: "Timezone"
schema:
type: string
default: "Etc/UTC"
$ref:
- "definitions/timezone"
- variable: PUID
label: "PUID"
description: "Sets the PUID env var for LinuxServer.io (compatible) containers"
@@ -193,31 +191,19 @@ They are called general options, because they affect the basic functionalities o
label: "runAsNonRoot"
schema:
type: boolean
default: false
default: true
- variable: runAsUser
label: "runAsUser"
description: "The UserID of the user running the application"
schema:
type: int
default: 0
default: 568
- variable: runAsGroup
label: "runAsGroup"
description: The groupID this App of the user running the application"
schema:
type: int
default: 0
- variable: supplementalGroups
label: "supplementalGroups"
description: "Additional groups this App needs access to"
schema:
type: list
default: []
items:
- variable: Group
label: "Group"
schema:
type: int
default: 568
default: 568
- variable: fsGroup
label: "fsGroup"
description: "The group that should own ALL storage."
@@ -234,4 +220,4 @@ They are called general options, because they affect the basic functionalities o
description: "OnRootMismatch"
- value: "Always"
description: "Always"
```
```
docs/development/app development/storage.md
+16 -7
View File
@@ -56,9 +56,14 @@ Preventing the user to disable them, ensures that users don't (by mistake) remov
- variable: emptyDir
label: "Mount a ramdisk instead of actual storage"
schema:
type: boolean
default: false
hidden: true
attrs:
- variable: enabled
label: "Enable emptyDir"
schema:
type: boolean
default: false
hidden: true
- variable: accessMode
label: "Access Mode (Advanced)"
description: "Allow or disallow multiple PVC's writhing to the same PVC"
@@ -87,7 +92,7 @@ It should always be included in any App, to give users the option to customise t
##### Example
```
- variable: additionalAppVolumeMounts
- variable: hostPathMounts
label: "Custom app storage"
group: "Storage and Devices"
schema:
@@ -122,12 +127,16 @@ It should always be included in any App, to give users the option to customise t
required: true
editable: true
- variable: emptyDir
label: "emptyDir"
label: "Mount a ramdisk instead of actual storage"
schema:
type: boolean
default: false
hidden: true
editable: false
attrs:
- variable: enabled
label: Enable emptyDir
schema:
type: boolean
default: false
hidden: true
- variable: mountPath
label: "Mount Path"
description: "Path to mount inside the pod"
docs/development/app development/values-yaml.md
+1 -12
View File
@@ -7,7 +7,7 @@ However, we have multiple different values.yaml files, with different goals. Bec
##### values.yaml
The normal file with default setting in helm charts. However, for our non-library and non-dependency charts, this is not used for TrueCharts. As questions.yaml generates configs on demand (with addition of ix_values.yaml), this file might interfere with some Helm operations combined with the questions.yaml or test_values.yaml systems or cause unexpected behavior if used.
This file contains the default config when running the App using stock helm (not SCALE). It also gets used for the testingsuite.
##### ix_values.yaml
@@ -39,14 +39,3 @@ image:
##
```
##### test_values.yaml
Our Apps often use special features of TrueNAS inside questions.yaml and our charts. However these features are not (always) compatible with stock Helm. Therefore we define a set of seperate "test" values.yaml setting that get used when we run the test CI.
They should, however, be as close as possible to your "actual" default settings in questions.yaml
##### default_values.yaml
This on is the "odd one" of the bunch. We prefer not to use it for actual default, but to store default when porting charts from upstream.