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

Merge pull request #477 from Ornias1993/4rework

Browse Source 
Change Apps for Common 4.*
This commit is contained in:
Kjeld Schouten-Lebbing
2021-05-23 20:53:39 +02:00
committed by GitHub
parent 4bb573c7a6 54c0f3ce32
commit a291635b61
181 changed files with 7952 additions and 9224 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
+83 -35
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"
@@ -88,30 +88,59 @@ groups:
- name: "Configuration"
description: "additional container configuration"
- name: "Networking"
description: "Configure / service for container"
- name: "Storage and Devices"
description: "Configure Network and Services for container"
- name: "Storage"
description: "Persist and share data that is separate from the lifecycle of the container"
- name: "Resources and Devices"
description: "Specify resources/devices to be allocated to workload"
- name: "Reverse Proxy Configuration"
description: "Reverse Proxy configuration"
- name: "Ingress Configuration"
description: "Ingress Configuration"
- name: "Security"
description: "Configure security context"
- name: "Advanced"
description: "Advanced Configuration"
- name: "WARNING"
description: "WARNING"
```
##### General Configuration options
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.
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.
```
- variable: timezone
- variable: env
group: "Configuration"
label: "Timezone"
label: "Image Environment"
schema:
type: string
default: "Etc/UTC"
$ref:
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"
schema:
type: int
default: 568
- variable: PGID
label: "PGID"
description: "Sets the PGID env var for LinuxServer.io (compatible) containers"
schema:
type: int
default: 568
- variable: UMASK
label: "UMASK"
description: "Sets the UMASK env var for LinuxServer.io (compatible) containers"
schema:
type: string
default: "002"
# Configure Custom Enviroment Variables
- variable: environmentVariables
@@ -136,33 +165,12 @@ They are called general options, because they affect the basic functionalities o
type: string
```
And at the bottom some advanced settings:
```
- variable: PUID
group: "Advanced"
label: "Common Group ID"
description: "The UserID of the user running any included common chart-based pods"
schema:
type: int
default: 568
##### Security Context Configuration options
- variable: PGID
group: "Advanced"
label: "Storage and Common Group ID"
description: "The groupID of the user/group running any included common chart-based pods and owning the files!"
schema:
type: int
default: 568
- variable: UMASK
group: "Advanced"
label: "UMASK (Common Chart)"
description: "The UMASK used (if supported) by any included common chart-based pod"
schema:
type: string
default: "002"
```
# Enable privileged
- variable: securityContext
group: "Advanced"
group: "Security"
label: "Security Context"
schema:
type: dict
@@ -172,4 +180,44 @@ And at the bottom some advanced settings:
schema:
type: boolean
default: false
# Set Pod Security Policy
- variable: podSecurityContext
group: "Security"
label: "Pod Security Context"
schema:
type: dict
attrs:
- variable: runAsNonRoot
label: "runAsNonRoot"
schema:
type: boolean
default: true
- variable: runAsUser
label: "runAsUser"
description: "The UserID of the user running the application"
schema:
type: int
default: 568
- variable: runAsGroup
label: "runAsGroup"
description: The groupID this App of the user running the application"
schema:
type: int
default: 568
- variable: fsGroup
label: "fsGroup"
description: "The group that should own ALL storage."
schema:
type: int
default: 568
- variable: fsGroupChangePolicy
label: "When should we take ownership?"
schema:
type: string
default: "OnRootMismatch"
enum:
- value: "OnRootMismatch"
description: "OnRootMismatch"
- value: "Always"
description: "Always"
```
docs/development/app development/services.md
+81 -48
View File
@@ -26,75 +26,108 @@ Every App is required to have a main service, the primary thing that users (or o
Please keep in mind that every App is different, some just have one service (which *ALWAYS* has to be called `main`) and others need more (which each has to have an unique name). Every App also uses different ports, so please alter accordingly.
```
- variable: services
- variable: service
group: "Networking"
label: "Configure Service"
label: "Configure Service(s)"
schema:
type: dict
attrs:
- variable: main
label: "Main service"
label: "Main Service"
description: "The Primary service on which the healthcheck runs, often the webUI"
schema:
type: dict
attrs:
- variable: enabled
label: "Enable the service"
schema:
type: boolean
default: true
hidden: true
label: "Enable the service"
schema:
type: boolean
default: true
hidden: true
- variable: type
label: "Service type"
description: "ClusterIP's are only internally available, nodePorts expose the container to the host node System"
label: "Service Type"
description: "ClusterIP's are only internally available, nodePorts expose the container to the host node System, Loadbalancer exposes the service using the system loadbalancer"
schema:
type: string
default: "ClusterIP"
default: "NodePort"
enum:
- value: "nodePort"
- value: "NodePort"
description: "NodePort"
- value: "ClusterIP"
description: "ClusterIP"
- variable: port
label: "Port configuration"
- value: "LoadBalancer"
description: "LoadBalancer"
- variable: loadBalancerIP
label: "LoadBalancer IP"
description: "LoadBalancerIP"
schema:
show_if: [["type", "=", "LoadBalancer"]]
type: string
default: ""
required: true
- variable: exetrnalIPs
label: "External IP's"
description: "External IP's"
schema:
show_if: [["type", "=", "LoadBalancer"]]
type: list
default: []
items:
- variable: externalIP
label: "External IP"
required: true
schema:
type: string
- variable: ports
label: "Service's Port(s) Configuration"
schema:
type: dict
attrs:
- variable: protocol
label: "Port Type"
- variable: main
label: "Main Service Port Configuration"
schema:
type: string
default: "HTTP"
hidden: false
enum:
- value: HTTP
description: "HTTP"
- value: "HTTPS"
description: "HTTPS"
- variable: port
label: "container port"
schema:
type: int
default: 80
editable: false
hidden: true
- variable: targetport
label: "Internal Service port"
description: "When connecting internally to this App, you'll need this port"
schema:
type: int
default: 80
editable: false
hidden: true
- variable: nodePort
label: "(optional) host nodePort to expose to"
description: "only get used when nodePort is selected"
schema:
type: int
min: 9000
max: 65535
default: 36052
required: true
type: dict
attrs:
- variable: protocol
label: "Port Type"
schema:
type: string
default: "HTTP"
hidden: false
enum:
- value: HTTP
description: "HTTP"
- value: "HTTPS"
description: "HTTPS"
- value: TCP
description: "TCP"
- value: "UDP"
description: "UDP"
- variable: port
label: "Container Port"
schema:
type: int
default: 5076
editable: false
hidden: true
- variable: targetport
label: "Target Port"
description: "This port exposes the container port on the service"
schema:
type: int
default: 5076
editable: true
hidden: false
required: true
- variable: nodePort
label: "Node Port (Optional)"
description: "This port gets exposed to the node. Only considered when service type is NodePort"
schema:
type: int
min: 9000
max: 65535
default: 36041
required: true
```
##### Unlimited custom services
docs/development/app development/storage.md
+17 -8
View File
@@ -7,7 +7,6 @@ This article serves as a development extention to the storage article available
For all these storage solutions we require the commonchart to be added to the App.
The Common-Chart handles both the connection/addition of storage to the container and spinning up special k8s jobs to fix the permissions if requested for the Custom storage.
### Integrated Persistent Storage
When adding an App, there are almost always certain folders that are required for solid Apps performance. For example config files that should be persistent across restarts.
@@ -56,9 +55,15 @@ 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
type: dict
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.
docs/manual/Migration Guides/index.md
+12 -2
View File
@@ -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
docs/manual/general-configuration.md
+1 -1
View File
@@ -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:
docs/manual/networking.md
+8
View File
@@ -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
docs/manual/reverse-proxy.md
+4
View File
@@ -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:
docs/manual/storage.md
+4 -6
View File
@@ -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.