From 0793f0bfee42766213430c984d3b2319740a5d4d Mon Sep 17 00:00:00 2001 From: Daniel Caires Date: Wed, 27 Dec 2023 09:21:57 -0300 Subject: [PATCH] Update README Update README so it reflects recent changes to the app generator. Story: 2010937 Task: 49326 Change-Id: I20c7bfa743693d3267c10e0b50952dcdcefa4119 Signed-off-by: Daniel Caires --- README.md | 102 ++++++++++++++++++------------------------------------ 1 file changed, 34 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index 03ad2a4..1ae3074 100644 --- a/README.md +++ b/README.md @@ -9,20 +9,22 @@ Below you will find the steps to deploy an application as a **StarlingX App**. - [StarlingX Application Generation Tool](#starlingx-application-generation-tool) - [Why deploy an application as a StarlingX application?](#why-deploy-an-application-as-a-starlingx-application) - - [Tools requirements](#tools-requirements) + - [Software Requirements](#software-requirements) - [Prerequisites](#prerequisites) + - [Standalone Installation](#standalone-installation) + - [Option 1 - Install in same folder](#option-1---install-in-same-folder) + - [Option 2 - Install From Url](#option-2---install-from-url) - [Generate the StarlingX Application package](#generate-the-starlingx-application-package) - [App manifest configuration](#app-manifest-configuration) - [Metadata File Configuration](#metadata-file-configuration) - [App Setup configuration](#app-setup-configuration) - - [Run the StarlingX App Generator](#run-the-stx-app-generator) - - [FluxCD Packaging](#fluxcd-packaging) + - [Run the StarlingX App Generator](#run-the-starlingx-app-generator) + - [Flux Packaging](#flux-packaging) - [FluxCD Manifest](#fluxcd-manifest) - [Plugins](#plugins) - [Metadata](#metadata) - [Tarballs](#tarballs) - - [Customizing the application](#customizing-the-application) - - [FluxCD Manifest](#fluxcd-manifest) + - [Customizing the application](#customizing-the-application) - [FluxCD](#fluxcd) - [Plugins](#plugins-1) - [Other files](#other-files) @@ -91,9 +93,9 @@ This is what you'll find in the `app-gen-tool` repository: ```shell. . +├── app_manifest.yaml ├── LICENSE ├── README.md -├── app_manifest.yaml ├── bandit.yaml ├── debian_build_layer.cfg ├── debian_iso_image.inc @@ -109,39 +111,6 @@ This is what you'll find in the `app-gen-tool` repository: │ │ ├── deployment.yaml │ │ └── service.yaml │ └── values.yaml -├── output -│ └── app-test -│ ├── charts -│ ├── fluxcd-manifests -│ │ ├── adminer -│ │ │ ├── adminer-static-overrides.yaml -│ │ │ ├── adminer-system-overrides.yaml -│ │ │ ├── helmrelease.yaml -│ │ │ └── kustomization.yaml -│ │ ├── base -│ │ │ ├── helmrepository.yaml -│ │ │ ├── kustomization.yaml -│ │ │ └── namespace.yaml -│ │ └── kustomization.yaml -│ ├── metadata.yaml -│ └── plugins -│ ├── __init__.py -│ ├── k8sapp_app_test -│ │ ├── __init__.py -│ │ ├── common -│ │ │ ├── __init__.py -│ │ │ └── constants.py -│ │ ├── helm -│ │ │ ├── __init__.py -│ │ │ └── adminer.py -│ │ ├── kustomize -│ │ │ ├── __init__.py -│ │ │ └── kustomize_app_test.py -│ │ └── lifecycle -│ │ ├── __init__.py -│ │ └── lifecycle_app_test.py -│ ├── setup.cfg -│ └── setup.py ├── playbooks │ └── app-gen-tool-tox-coverage │ └── pre.yaml @@ -162,10 +131,10 @@ This is what you'll find in the `app-gen-tool` repository: │ └── stx-app-generator │ ├── app_gen_tool │ │ ├── __init__.py -│ │ ├── application.py │ │ ├── cmd │ │ │ ├── __init__.py │ │ │ └── generator.py +│ │ ├── application.py │ │ ├── common.py │ │ ├── constants.py │ │ ├── fluxcd.py @@ -230,20 +199,8 @@ which will help you fill them out for you application: - **version** field: your chart version as it is in the chart metadata. - **path** field: relative path to the Helm chart directory, Helm repo or Helm package file. - > _NOTE_: Currently only Helm charts in directories have been tested. - **chartGroup** field: chartgroup in which the helm-chart belong -- **chartGroup** - - **name**: Name of the chartgroup - - **description**: description of chart set - - **sequenced**: enables sequenced chart deployment in a group - - **chart_names**: a list of the names of the charts from your application. -- **manifest**: - - **name**: manifest name - - **releasePrefix**: appends to the front of all charts released by the manifest in order to manage releases throughout their lifecycle -Note that the minimum required fields that will need to be filled in order -for the StarlingX App Generator to work properly will depend on the intended -type of packaging. ### Metadata File Configuration @@ -294,16 +251,22 @@ stx-app-generator -i app_manifest.yaml -o ./output ``` With the command above, the StarlingX App Generator will create a set of files -and package everything in the chosen StarlingX format, and then finally place -the file in an output folder. +necessary for integration with the StarlingX platform. -## Supported Packaging Methods +Then, by running: + +```shell +stx-app-generator -i app_manifest.yaml -o ./output --package-only +``` + +The generator will package everything in the chosen StarlingX format, and then +place the file in the output folder. + +### Flux Packaging The following sections explain in high-level the most important parts of the package. -### Flux Packaging - #### FluxCD Manifest The generator will first create the FluxCD Manifest following the structure below: @@ -325,7 +288,11 @@ fluxcd-manifests/ For every Helm chart configured in the `app_manifest.yaml` file, a folder with the name of the chart will be created. -> **_NOTE_**: The `CHART-NAME-static-overrides.yaml` file will be empty. +> **_NOTE_**: The `CHART-NAME-static-overrides.yaml` file will be created with +> the same contents as the values file from the Helm chart. + +> **_NOTE_**: The `CHART-NAME-system-overrides.yaml` file will be empty, this is by +> design. #### Plugins @@ -365,8 +332,8 @@ section in the `app_manifest.yaml`. #### Tarballs -After the main files have been created, the generator will start packaging -everything. +After the main files have been created, by using the `--package-only` flag, the +generator will start packaging everything. Firstly it will package every helm-chart, that was given in the `app_manifest.yaml` file, into a `.tgz` file, saving these files into a folder @@ -402,11 +369,10 @@ The structure of the app inside the tarball will be the following: If you wish to add customization for the particularities of your application, it is important to modify some of the generated files. -In order to allow such customization, the generator provides additional -functions to modify specific files in the package. +The execution of the generator is made to allow such customization. ```shell -stx-app-generator -i app_manifest.yaml [-o ./output] [--overwrite] [--no-package]|[--package-only] +stx-app-generator -i app_manifest.yaml [-o ./output] [--overwrite] [--package-only] ``` Where: @@ -415,27 +381,27 @@ Where: - `-o/--output`: output folder. Defaults to a new folder with the app name in the current directory. - `--overwrite`: deletes existing output folder before starting. -- `--no-package`: only creates the FluxCD manifest, plugins and the - metadata file, without compressing them in a tarball. - `--package-only`: create the plugins wheels, sha256 file, helm-chart tarball and package the entire application into a tarball. This means that, in order to be able to make additional configuration, one must: -- first run the App Generator with `--no-package`; +- Simply run the App Generator; - then do the changes (described in the following sections); - finally, run the App Generator again with `--package-only`. -### Flux Manifest +### Customizing the application #### FluxCD -> _NOTE_: this section needs improvement. Most of the generated manifest won't need any modification, but for every Helm chart in the `app_manifest.yaml`, a static-overrides file will be created. The static-overrides file contains all information that is not to be overwritten inside the values.yaml of the Helm chart. +> _NOTE_: By default, the static-overrides will be created with all the +> contents of the values.yaml file. + #### Plugins The StarlingX App Generator will create 3 main plugins: the Helm,