Difference between revisions of "StarlingX/Containers/Applications/AppIntegration"
(→Guidelines) |
|||
Line 127: | Line 127: | ||
== Guidelines == | == Guidelines == | ||
− | We strongly encourage you to enable the auto update feature unless there are special extra steps needed for an application update to happen. See [https://wiki.openstack.org/ | + | We strongly encourage you to enable the auto update feature unless there are special extra steps needed for an application update to happen. See [https://wiki.openstack.org/wiki/StarlingX/Containers/StarlingXAppsInternals#upgrades.2Fauto_update `updates/auto_update`] above. |
Revision as of 12:50, 7 February 2023
This page should provide an insight about configuration, features and general guidelines of StarlingX Apps and interaction with the App Framework.
For a build perspective of StarlingX Apps this tutorial should cover the FluxCD apps: https://wiki.openstack.org/wiki/StarlingX/Containers/HowToAddNewFluxCDAppInSTX
StarlingX management commands: https://docs.starlingx.io/cli_ref/system.html#application-management
General directory structure of a StarlingX App at build time: https://wiki.openstack.org/wiki/StarlingX/Containers/HowToAddNewFluxCDAppInSTX#Step_7:_Develop_your_application_FluxCD_packaging
TBD schema for state transition
Contents
Core of a StarlingX App
Referencing the general directory structure (https://wiki.openstack.org/wiki/StarlingX/Containers/HowToAddNewFluxCDAppInSTX#Step_7:_Develop_your_application_FluxCD_packaging), enabling features can be done by modifying a yaml file located at: stx-APPNAME-helm/stx-APPNAME-helm/files/metadata.yaml
There is a function definition called 'def find_metadata_file' in https://opendev.org/starlingx/config/src/branch/master/sysinv/sysinv/sysinv/sysinv/common/utils.py, that lists entries used by the framework.
Note: Currently there are a few entries missing from utils.py, this will be updated when code there will be updated. The guide in later steps may still explain and show examples of entries not listed here.
app_name: <name> app_version: <version> upgrades: auto_update: <true/false/yes/no> update_failure_no_rollback: <true/false/yes/no> from_versions: - <version.1> - <version.2> supported_k8s_version: minimum: <version> maximum: <version> supported_releases: <release>: - <patch.1> - <patch.2> ... repo: <helm repo> - optional: defaults to HELM_REPO_FOR_APPS disabled_charts: - optional: charts default to enabled - <chart name> - <chart name> ... maintain_user_overrides: <true|false> - optional: defaults to false. Over an app update any user overrides are preserved for the new version of the application ... behavior: - optional: describes the app behavior platform_managed_app: <true/false/yes/no> - optional: when absent behaves as false desired_state: <uploaded/applied> - optional: state the app should reach evaluate_reapply: - optional: describe the reapply evaluation behaviour after: - optional: list of apps that should be evaluated before the current one - <app_name.1> - <app_name.2> triggers: - optional: list of what triggers the reapply evaluation - type: <key in APP_EVALUATE_REAPPLY_TRIGGER_TO_METADATA_MAP> filters: - optional: list of field:value, that aid filtering of the trigger events. All pairs in this list must be present in trigger dictionary that is passed in the calls (eg. trigger[field_name1]==value_name1 and trigger[field_name2]==value_name2). Function evaluate_apps_reapply takes a dictionary called 'trigger' as parameter. Depending on trigger type this may contain custom information used by apps, for example a field 'personality' corresponding to node personality. It is the duty of the app developer to enhance existing triggers with the required information. Hard to obtain information should be passed in the trigger. To use existing information it is as simple as defining the metadata. - <field_name.1>: <value_name.1> - <field_name.2>: <value_name.2> filter_field: <field_name> - optional: field name in trigger dictionary. If specified the filters are applied to trigger[filter_field] sub-dictionary instead of the root trigger dictionary. apply_progress_adjust: - optional: Positive integer value by which to adjust the percentage calculations for the progress of a monitoring task. Default value is zero (no adjustment)
maintain_user_overrides
Currently if you create overrides for a helm chart, when you update an app the overrides will be lost.
system helm-override-update <app name> <chart name> <namespace>
The overrides themselves are stored in sysinv database table helm_overrides in a column called 'user_overrides'.
If you want to keep the overrides during app update you can update the metadata.yaml ([1] example location for one app), adding at root level the following `maintain_user_overrides: true`
There is more. You can override the behavior present by adding a special flag during 'system application-update'. You can force the information either way: reuse(will keep the overrides) or not reuse(reset overrides).
system application[sysadmin@controller-0 ~(keystone_admin)]$ system application-update usage: system application-update [-n <app name>] [-v <app version>] [--reuse-user-overrides <true/false>] [--reuse-attributes <true/false>] <tar file>
system application[sysadmin@controller-0 ~(keystone_admin)]$ system application-update -n MY_APP -v MY_VERSION --reuse-user-overrides true /path/to/tar.gz
maintain_attributes
Currently if you disable a helm chart when you update an app it will be re-enabled by default on the newer version.
[sysadmin@controller-0 ~(keystone_admin)]$ system helm-chart-attribute-modify usage: system helm-chart-attribute-modify [--enabled <true/false>] <app name> <chart name> <namespace>
system helm-chart-attribute-modify --enabled false MY_APP MY_CHART MY_NAMESPACE
The chart attribute(enabled/disabled) itself is stored in sysinv database table helm_overrides in a column called 'system_overrides' (bad naming, will be aligned later).enabled
If you want to keep the disabled status during app update you can update the metadata.yaml ([1] example location for one app), adding at root level the following `maintain_attributes: true`
There is more. You can override the behavior present by adding a special flag during 'system application-update'. You can force the information either way: reuse(will keep disabled the charts that were disabled) or not reuse(reset all the charts to be enabled).
system application[sysadmin@controller-0 ~(keystone_admin)]$ system application-update usage: system application-update [-n <app name>] [-v <app version>] [--reuse-user-overrides <true/false>] [--reuse-attributes <true/false>] <tar file>
system application[sysadmin@controller-0 ~(keystone_admin)]$ system application-update -n MY_APP -v MY_VERSION --reuse-attributes true /path/to/tar.gz
upgrades/auto_update
There is a mechanism to allow apps to be automatic updated. This can be used both when 1)delivering an updated app part of a platform patch and 2) during platform upgrades `system upgrade-activation` step.. Probably a bad naming because it is present under a key named 'upgrades', but it was designed under an upgrades context, we didn't realize the `patching` context at that moment.
If you want to enable the auto update feature you need to update the metadata.yaml ([1] example location for one app), adding at root level the following
upgrades: auto_update: true
Guidelines
We strongly encourage you to enable the auto update feature unless there are special extra steps needed for an application update to happen. See `updates/auto_update` above.