Difference between revisions of "StarlingX/Containers/Applications/AppIntegration"

Revision as of 18:04, 14 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

This is still under construction. Plan is to finish the metadata.yaml options. Possible add a diagram for app state transitions.

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. For example this snapshot of https://opendev.org/starlingx/config/src/commit/e9705f5bc61f29618dd34b408a4608797422a7ad/sysinv/sysinv/sysinv/sysinv/common/utils.py#L2235, doesn't have `maintain_attributes` entry:

   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

[1]: https://opendev.org/starlingx/platform-armada-app/src/branch/master/stx-platform-helm/stx-platform-helm/files/metadata.yaml

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

[1]: https://opendev.org/starlingx/platform-armada-app/src/branch/master/stx-platform-helm/stx-platform-helm/files/metadata.yaml

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, I suspect no one realized there is a `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

[1]: https://opendev.org/starlingx/platform-armada-app/src/branch/master/stx-platform-helm/stx-platform-helm/files/metadata.yaml

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.

We strongly encourage you to enable maintaining user overrides feature unless there are special extra steps needed for an application update to happen. See `maintain_user_overrides` above.

Rationale for updates and maintaining user overrides would be:

Are there any steps required before `system application-update`when applying a patch on a live system?
Are there any steps required before `system application-update` at `system upgrade-activate` time?
Was there an override format change that requires a transformation between version N and N+1 of the format? Can I update helm-charts to allow both formats so that a transformation can be skipped?

We strongly encourage you to enable maintaining disabled helm-charts feature. See `maintain_attributes` above.