From 5aa477cc59e1c69e9778b4ad7409bd3b1a2e19d2 Mon Sep 17 00:00:00 2001 From: kjeld Schouten-Lebbing Date: Wed, 29 Sep 2021 12:47:48 +0200 Subject: [PATCH] (docs) restructuring some old docs and moving dev container docs back to ruby --- docs/manual/development/chart-structure.md | 22 ++- .../development/chart-yaml-structure.md | 6 +- docs/manual/development/portal.md | 17 --- docs/manual/development/services.md | 15 -- docs/manual/development/storage.md | 77 +--------- docs/manual/development/unit-tests.md | 132 ++++++++---------- 6 files changed, 67 insertions(+), 202 deletions(-) diff --git a/docs/manual/development/chart-structure.md b/docs/manual/development/chart-structure.md index 03c6e816e83..02aa31eb542 100644 --- a/docs/manual/development/chart-structure.md +++ b/docs/manual/development/chart-structure.md @@ -1,10 +1,8 @@ # 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. +This is a general synopsis about the structure of a SCALE App and/or Helm Chart, it does not directly reflect TrueCharts specific settings. -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. Currently only the `charts` train can be used inside the UI. +The following files are generally considered to be a "normal" Helm chart: ``` charts/// @@ -15,11 +13,15 @@ charts/// values.yaml # The default configuration values for this chart ``` + +The following files are specific for TrueNAS SCALE: + ``` -charts/// - app-readme.md # TrueNAS SCALE Specific: Readme file for display in TrueNAS SCALE UI +charts///SCALE/ + app-readme.md # TrueNAS SCALE Specific: Readme file for display in TrueNAS SCALE UI, automatically generated questions.yaml # TrueNAS SCALE Specific: File containing questions for TrueNAS SCALE UI ix_values.yaml # Hidden configuration values when installing using TrueNAS SCALE + item.yaml # Contains generic information about the App for the TrueNAS SCALE UI ``` *See the upstream Helm chart [developer reference](https://helm.sh/docs/chart_template_guide/) for a complete walk through of developing charts.* @@ -34,14 +36,6 @@ categories: icon_url: "http://ix_url" ``` -After that create `app-readme.md` file. - -``` -$ cat charts///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. -``` Then add a `questions.yaml` file to prompt the user for something. diff --git a/docs/manual/development/chart-yaml-structure.md b/docs/manual/development/chart-yaml-structure.md index 69482ed1275..2dbe2b8dfa8 100644 --- a/docs/manual/development/chart-yaml-structure.md +++ b/docs/manual/development/chart-yaml-structure.md @@ -40,6 +40,7 @@ annotations: example: A list of annotations keyed by name (optional). ``` + ##### Commenting In the above description there are a lot of values that are not actually used. Some of those, like `deprecated`, we just set to false. While others, like `annotations` get commented out. @@ -54,8 +55,5 @@ All other dependencies are expected to be listed in alphabetical order. ##### Maintainers -The first maintainer should always be TrueCharts, as the TrueCharts core team is expected to step in if the other maintainers fail to maintain their work. +The only maintainer should always be TrueCharts, as the TrueCharts core team is expected to step in if the other maintainers fail to maintain their work. An example of how to list TrueCharts as a maintainer is available in our standard Chart.yaml [template](https://github.com/truecharts/apps/tree/master/tools/templates/chart/Chart.yaml). - -While currently we primarily use the CODEOWNERS file to define maintainers. We might in the future either automate keeping track of maintainers, completely rely on the maintainers or do both. For this reason it's important to add yourself as a maintainer if you expect to maintain your work. -All other maintainers are, ofcoarse, expected to be entered in importance. With the primary maintainer under "truecharts" and secondary maintainers thereunder. diff --git a/docs/manual/development/portal.md b/docs/manual/development/portal.md index 8e210861414..e9f04947166 100644 --- a/docs/manual/development/portal.md +++ b/docs/manual/development/portal.md @@ -41,18 +41,6 @@ questions: There are also some additional (advanced) options availale, these can be added below the above required portion as required: -**ingressPort:** -``` - - variable: ingressPort - label: "Port when ingress is not using 443" - description: "Advanced setting, please enter a different port to use if Ingress uses something other than port 443" - schema: - hidden: true - editable: false - type: int - default: 8443 -``` - **host:** ``` - variable: host @@ -64,8 +52,3 @@ 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" diff --git a/docs/manual/development/services.md b/docs/manual/development/services.md index e4319b50e78..3e70d35afca 100644 --- a/docs/manual/development/services.md +++ b/docs/manual/development/services.md @@ -4,21 +4,6 @@ Every App needs to be exposed to something, either an UI, API or other container ### Two kinds of services -##### First: hostNetwork - -Always add the hostNetwork option above the "services" section. -This is to try and keep things clear for the user. - -``` - # Enable Host Networking - - variable: hostNetwork - group: "Networking" - label: "Enable Host Networking" - schema: - type: boolean - default: false -``` - ##### Main Service Every App is required to have a main service, the primary thing that users (or other Apps!) connect with. No mater if it's a webUI, an API, a database connection or something totally else, A service is always required. diff --git a/docs/manual/development/storage.md b/docs/manual/development/storage.md index 8dc46cec445..b746b097a57 100644 --- a/docs/manual/development/storage.md +++ b/docs/manual/development/storage.md @@ -101,80 +101,5 @@ It should always be included in any App, to give users the option to customise t ##### Example ``` - - variable: hostPathMounts - label: "Custom app storage" - group: "Storage and Devices" - schema: - type: list - default: [] - items: - - variable: volumeMount - label: "Custom Storage" - schema: - type: dict - attrs: - - variable: enabled - label: "Enabled" - schema: - type: boolean - default: true - required: true - hidden: true - editable: false - - variable: setPermissions - label: "Automatic Permissions" - description: "Automatically set permissions on install" - schema: - type: boolean - default: true - hidden: false - - variable: name - label: "Mountpoint Name" - schema: - type: string - default: "" - required: true - editable: true - - variable: emptyDir - label: "EmptyDir Volume" - schema: - type: dict - hidden: false - attrs: - - variable: enabled - label: "Use emptyDir volume" - schema: - type: boolean - default: false - hidden: false - - variable: medium - label: "EmptyDir Medium" - schema: - type: string - default: "" - enum: - - value: "" - description: "Default" - - value: "Memory" - description: "Memory" - - variable: mountPath - label: "Mount Path" - description: "Path to mount inside the pod" - schema: - type: path - required: true - default: "" - editable: true - - variable: hostPathEnabled - label: "host Path Enabled" - schema: - type: boolean - default: true - hidden: true - - variable: hostPath - label: "Host Path" - description: "Path on the host to mount inside the container, ignored when emptyDir is enabled" - schema: - type: hostpath - required: true + ``` diff --git a/docs/manual/development/unit-tests.md b/docs/manual/development/unit-tests.md index 913c146999c..9d7e2b58860 100644 --- a/docs/manual/development/unit-tests.md +++ b/docs/manual/development/unit-tests.md @@ -1,106 +1,86 @@ # Unit tests -We unit test our common library, while it isn't near complete coverage but -it does offer some basic checks. +We unit test our common library, while it isn't near complete coverage but it does offer some basic checks. -Running these tests can be done any way you like. In this document we describe -a number of approaches. +## Running the tests -## Directly on your development machine +Running these tests can be done any way you like. In this document we limit ourselves to using Visual Studie Code, using our Development Container. -First set up the environment: -```sh -go mod download -``` +### Using Visual Studio Code -Run the tests: +Our repo comes with a Visual Studio Code [development container](https://code.visualstudio.com/docs/remote/containers) definition and `launch.json` that allow you to quickly set up an environment in which you can run the tests. -```sh -go test ./charts/.../tests -``` - -## Using Visual Studio Code - -Our repo comes with a Visual Studio Code -[development container](https://code.visualstudio.com/docs/remote/containers) -definition and `launch.json` that allow you to quickly set up an environment -in which you can run the tests. - -### Prerequisites +##### Prerequisites - Visual Studio Code is installed. - Docker is installed and running. -- The "Remote - Containers" extension is installed and enabled in Visual Studio -Code. +- The "Remote - Containers" extension is installed and enabled in Visual Studio Code. -For more details, please refer to the -[official documentation](https://code.visualstudio.com/docs/remote/containers#_system-requirements). +For more details, please refer to the [official documentation](https://code.visualstudio.com/docs/remote/containers#_system-requirements). -### Running tests +##### Running tests -Once Visual Studio Code is set up, and you open the `charts` workspace, you -will see a popup asking if you wish to re-open the workspace in a development -container: +Once Visual Studio Code is set up, and you open the `charts` workspace, you will see a popup asking if you wish to re-open the workspace in a development container: -![Visual Studio Code development container popup](../../assets/screenshots/vscode_devcontainer_popup.png) +![Visual Studio Code development container popup](https://raw.githubusercontent.com/k8s-at-home/charts/master/docs/images/vscode_devcontainer_popup.png) -Select the option that you prefer. The workspace will be reopened and a -Dockerized workspace will be built. You can now use Visual Studio Code as -normal. +Select to do so and a Dockerized workspace will be built. You can now use Visual Studio Code as normal. -To run or debug the unit tests, click the "Run" button on the left sidebar -and select the desired configuration: +To run or debug the unit tests, click the "Run" button on the left sidebar and select the desired configuration: -![Visual Studio Code run configurations](../../assets/screenshots/vscode_run_unittests.png) +![Visual Studio Code run configurations](https://raw.githubusercontent.com/k8s-at-home/charts/master/docs/images/vscode_run_unittests.png) -- _stable/common tests_: This configuration will run the all test -files for the `common` library chart. +* _UnitTest - active spec file only_: This configuration will try to run the currently opened test file. -Next, press the green "Play" icon. This will start the tests show the -outcome in a terminal window. + **Note:** Make sure that you have opened a valid test file (`.rb` files in the `test/charts` folder), or this will not work. -## Using a local Docker container +* _UnitTest - all spec files_: This configuration will run the all test files in the `test/charts` folder. -The [Visual Studio Code development container](#using-visual-studio-code) -can also be leveraged without using Visual Studio Code. +Next, press the green "Play" icon. This will start the tests show the outcome in a terminal window. -### Prerequisites - -- Docker is installed and running. -- You have the charts repo root folder opened in your shell of choice. The - commands in this article assume you are running a Bash-compatible shell. - -### Running tests - -The first step is to build the development container image containing the -required tools. This step only needs to be done once. To build the container, -run this command in your shell: - -```sh -docker build -t k8s-at-home/charts-unit-test -f .devcontainer/Dockerfile . -``` - -When you wish to run the tests, run this command in your shell: - -```sh -docker run --rm -it -l \ - -v $(pwd):/charts --entrypoint "/bin/bash" \ - -w /charts k8s-at-home/charts-unit-test \ - -c "go mod download && go test ./charts/.../tests" -``` - -This will create a container with the charts repo root folder mounted to -`/charts` and execute all the test files belonging to the different charts. - -!!! note - Depending on the performance of your environment, this can take a long time - where it seems as if your machine is not doing anything! ## Output A successful test will output something like the following... ```text -ok github.com/k8s-at-home/library-charts/charts/stable/common/tests 54.087s +Started with run options --seed 52955 + +common-test::statefulset volumeClaimTemplates + can set values for volumeClaimTemplates PASS (0.16s) + volumeClaimTemplates should be empty by default PASS (0.06s) + +common-test::ports settings + targetPort can be overridden PASS (0.17s) + port name can be overridden PASS (0.17s) + defaults to name "http" on port 8080 PASS (0.16s) + targetPort cannot be a named port PASS (0.05s) + +common-test::pod replicas + defaults to 1 PASS (0.08s) + accepts integer as value PASS (0.08s) + +common-test::Environment settings + Check no environment variables PASS (0.05s) + set "valueFrom" environment variables PASS (0.11s) + set "static" and "Dynamic/Tpl" environment variables PASS (0.15s) + set "Dynamic/Tpl" environment variables PASS (0.11s) + set "static" environment variables PASS (0.10s) + +common-test::ingress + ingress with hosts PASS (0.10s) + should be disabled when ingress.enabled: false PASS (0.06s) + ingress with hosts template is evaluated PASS (0.11s) + ingress with hosts and tls PASS (0.15s) + ingress with hosts and tls templates is evaluated PASS (0.16s) + should be enabled when ingress.enabled: true PASS (0.06s) + +common-test::controller type + accepts "daemonset" PASS (0.06s) + accepts "statefulset" PASS (0.06s) + defaults to "Deployment" PASS (0.06s) + +Finished in 2.26077s +22 tests, 59 assertions, 0 failures, 0 errors, 0 skips ```