starlingx/app-gen-tool
Code Issues Proposed changes

Update README

Browse Source 
Update README so it reflects recent changes to the
app generator.

Story: 2010937
Task: 49326

Change-Id: I20c7bfa743693d3267c10e0b50952dcdcefa4119
Signed-off-by: Daniel Caires <daniel.caires@encora.com>
This commit is contained in:
Daniel Caires 2023-12-27 09:21:57 -03:00
parent b57e56f487
commit 0793f0bfee
1 changed files with 34 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
README.md
View File

@ -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,