Cloned2Preserve
/
TrueChartsClone
mirror of https://github.com/truecharts/charts.git
1
0
Fork 0
Code

Update project documentation

This commit is contained in:
kjeld Schouten-Lebbing 2020-12-30 21:38:12 +01:00
parent 0d30978472
commit 13f44c53b6
No known key found for this signature in database
GPG Key ID: 4CDAD4A532BC1EDB
3 changed files with 60 additions and 161 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
.github/README.md vendored Normal file
View File

@ -0,0 +1,31 @@
# TrueCharts:<br>Community App Catalog for TrueNAS SCALE
[![GitHub last commit](https://img.shields.io/github/last-commit/truecharts/truecharts/master.svg)](https://github.com/truecharts/truecharts/commits) [![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](https://github.com/truecharts/truecharts/blob/master/docs/LICENSE.GPLV2) [![License](https://img.shields.io/badge/License-BSD%203--Clause-orange.svg)](https://github.com/truecharts/truecharts/blob/master/docs/LICENSE.BSD3)
Truecharts is an innitiative to provide high quality Apps to use with the TrueNAS SCALE App Ecosystem.
Our primary goals are:
- Freedom
- Stability
- Consistancy
All our apps are supposed to work together, be easy to setup using the TrueNAS UI and, above all, give the average user more than enough options to tune things to their liking.
## Getting started using TrueCharts
Sadly enough, the TrueNAS SCALE UI currently is not usable with anything except the default apps. Due to much of it being hardcoded. None the less, we are already hard at work preparing as many apps as possible, to be ready when UI support drops.
## Getting into creating Apps
Creating charts takes some getting used to, as it's based on Helm charts. We highly suggest prior knowhow on creation/modifying Helm Charts, before taking on the challenge of creating SCALE Apps.
The specifications of TrueNAS SCALE apps, is layed out in the [wiki](https://github.com/truecharts/truecharts/wiki/TrueNAS-SCALE-Chart-Structure)
## Licence
`SPDX-License-Identifier: BSD-3-Clause`
Truecharts as a whole, is based on a BSD-3-clause license, this ensures almost everyone can use and modify our charts. However: As a lot of Apps are based on upstream Helm Charts, Licences can vary on a per-App basis. This can easily be seen by the presence of a "LICENSE" file in the App rootfolder.

29
LICENSE Normal file
View File

@ -0,0 +1,29 @@
**BSD 3-Clause License**
Copyright (c) 2020, the respective contributors, as shown by the AUTHORS file.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
* Neither the name of the copyright holder nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

161
README.md
View File

@ -1,161 +0,0 @@
# Unofficial Charts Catalog for TrueNAS SCALE
A curated community catalog of TrueNAS SCALE Apps.
## 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/<chart version>/
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
templates/tests # A directory of tests to run using 'helm test'
test_values.yaml # Configuration values for this chart when running the CI
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/<chart version>/app-readme.md
# iX-Chart
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.
```
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 | []dictionary | false | specify the options when the variable type is `string`, for example, <br><br>enum:<br> - value: "RollingUpdate" <br>&nbsp;&nbsp;description: "Create new pods and then kill old ones"<br> - value: "Recreate"<br>&nbsp;&nbsp;description: "Kill existing pods before creating new ones"|
| 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. |
| schema.private | bool | false | specified for declaring information sensitive fields. |
| schema.null | bool | false | specifies if the value for the variable can be null. defaults to false. |
**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`.
There are some novel cases where we would like to provide ability to configure / manage resources for workloads with getting some data from system dynamically.
So a chart can specify certain actions to be performed by the system for a variable by defining a reference. An example better illustrates this concept:
```
- variable: volume
label: "Volume"
schema:
type: dict
$ref:
- "normalize/ixVolume"
attrs:
- variable: mountPath
label: "Mount Path"
description: "Path where the volume will be mounted inside the pod"
schema:
type: path
required: true
- variable: datasetName
label: "Dataset Name"
schema:
type: string
required: true
```
In the above variable we define a `$ref` in schema which specifies that the system should take some action for normalising the value specified for the variable.
In this specific case, `ix_volume` is a concept introduced where we recommend using a volume which we are able to rollback automatically on chart release rollback. In essence,
it is just a `hostPath` volume for which the system automatically creates the dataset specified.
We have following types of actions supported in `$ref` right now:
1) definitions
2) normalize
For (1), system will automatically update schema for a particular definition. For example,
```
- variable: hostInterface
description: "Please specify host interface"
label: "Host Interface"
schema:
type: string
required: true
$ref:
- "definitions/interface"
```
System will automatically populate available interfaces for the user based on what interfaces are available on the system.
For (2), system will normalize values or perform some actions as discussed above.