Doc patches
This commit is contained in:
kjeld Schouten-Lebbing
@@ -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.
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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"
|
||||
```
|
||||
```
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Sometimes we can not guarantee automatic updating between new versions of our Apps.
|
||||
These pages include some common scenario's and give some guidance how to manually move between different versions and Trains.
|
||||
|
||||
##### Between Trains
|
||||
### Between Trains
|
||||
|
||||
An app will always be just in one train. If an App moves to a different train, you will not be able to update automatically
|
||||
Our basic guidence for these cases is:
|
||||
@@ -17,7 +17,17 @@ Our basic guidence for these cases is:
|
||||
- Put back all your old files.
|
||||
- Re start the new App
|
||||
|
||||
##### Between Versions
|
||||
### Between Versions
|
||||
|
||||
When new versions introduce breaking changes (which would often be major version changes) they might(!) require the user to reinstall.
|
||||
However: We often already provide migration scrips and dealth with these issues manually.
|
||||
|
||||
##### Common 2.0 -> common 3.0 based Apps
|
||||
|
||||
In cases you upgrade to a common 3.0 based app, reinstall is currently required. Please be aware: Installing will nuke your data!
|
||||
Be also aware that we do not have common 2.0 based installs available in the version dropdown
|
||||
|
||||
##### Common 3.0 -> common 4.0 based Apps
|
||||
|
||||
In cases you upgrade to a common 4.0 based app, reinstall is currently required. Please be aware: Installing will nuke your data!
|
||||
However: Common 3.0 based Apps are still available to be installed using the version dropdown
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# General Configuration
|
||||
|
||||
There are some setting that are always present on every App from TrueCharts.
|
||||
These are some common settings you might find on Apps and an explaination of their usecase.
|
||||
|
||||
##### Explaination sheet:
|
||||
|
||||
|
||||
@@ -28,3 +28,11 @@ There are, however, multiple downsides to using nodeports:
|
||||
|
||||
- You can only pick ports above 9000
|
||||
- You can not connect two Apps to the same port
|
||||
|
||||
##### LoadBalancer
|
||||
|
||||
Loadbalancer connects a service targetPort directly to the Host Network. However: it can do so in lower ranges than NodePort, making it a great solution for things like DNS servers.
|
||||
|
||||
There are, however, downsides to using LoadBalancer:
|
||||
|
||||
- You can not connect two Apps to the same port
|
||||
|
||||
@@ -4,6 +4,10 @@ Within TrueCharts our aim is to make it as easy as possible to secure your Apps.
|
||||
|
||||
To use Traefik as a Reverse Proxy, all you have to do is enable "Reverse Proxy" in the App of your choice and fill out a little form.
|
||||
|
||||
## Note
|
||||
|
||||
Currently for charts using common 4.0, we do NOT support Reverse-Proxy/Ingress as it's being completely rewrithen from scratch at the moment.
|
||||
|
||||
### Types of Reverse Proxys
|
||||
|
||||
We currently offer the following types of pre-configured reverse proxies:
|
||||
|
||||
@@ -8,7 +8,7 @@ TrueCharts uses multiple different storage systems:
|
||||
Storage is currently seperated into two types:
|
||||
|
||||
1. Integrated Persistent Storage
|
||||
2. Custom Storage
|
||||
2. Custom Storage aka "hostPathMounts"
|
||||
|
||||
|
||||
### Integrated Persistent Storage
|
||||
@@ -26,15 +26,13 @@ We currently have the following Storage options for Integrated Persistent Storag
|
||||
This storage is integrated into TrueNAS SCALE and completely supports reverting upgrades. Thats why this is the default (and only actually supported!) way of storing App configuration files.
|
||||
|
||||
|
||||
### Custom Storage
|
||||
### Custom app storage aka "hostPathMounts"
|
||||
|
||||
Besides the earlier mentioned Integrated Persistent Storage, we also provide the option to mount as many host folders as you want.
|
||||
|
||||
Custom storage currently actually quite simple:
|
||||
hostPathMounts are actually quite simple:
|
||||
It mounts a directory from your TrueNAS SCALE system, directly to a directory inside the App you're installing.
|
||||
|
||||
However: We might port this to PVC's in the future, which is not fully decided on yet.
|
||||
|
||||
|
||||
### Permissions
|
||||
|
||||
@@ -46,7 +44,7 @@ For both Integrated Persistent Storage and Custom storage, we offer special opti
|
||||
These get automatically set to be owned by root:__PGID__
|
||||
There are no options available to configure this.
|
||||
|
||||
##### Custom storage
|
||||
##### Custom app storage aka "hostPathMounts"
|
||||
|
||||
We offer an optional automatic set the permissions according to App PGID and PUID.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user