Difference between revisions of "StarlingX/Containers/Applications/AppIntegration"
(evaluate_reapply/triggers) |
m (→evaluate_reapply/triggers) |
||
Line 201: | Line 201: | ||
===== evaluate_reapply/triggers ===== | ===== evaluate_reapply/triggers ===== | ||
We can control what triggers the Framework to evaluate the re-apply for apps using a list variable called ''triggers''. | We can control what triggers the Framework to evaluate the re-apply for apps using a list variable called ''triggers''. | ||
− | An app can be instructed to subscribe to some events by creating the necessary configuration in | + | An app can be instructed to subscribe to some events by creating the necessary configuration in ''metadata.yaml'' for it. |
behavior: | behavior: | ||
Line 212: | Line 212: | ||
The definition is explained in [1]. A snapshot of trigger types can be found at [2]. | The definition is explained in [1]. A snapshot of trigger types can be found at [2]. | ||
− | Triggers are created and passed to | + | Triggers are created and passed to ''evaluate_apps_reapply'' function inside conductor [3]. |
A real life example of such call is | A real life example of such call is | ||
self.evaluate_apps_reapply(context, trigger={'type': constants.APP_EVALUATE_REAPPLY_HOST_AVAILABILITY, | self.evaluate_apps_reapply(context, trigger={'type': constants.APP_EVALUATE_REAPPLY_HOST_AVAILABILITY, |
Revision as of 17:39, 16 March 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. Plan is to finish app_lifecycle_actions. Possible add a diagram for app state transitions.
Core of a StarlingX App
metadata.yaml
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
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
This was introduced in stx.8.0 by: https://review.opendev.org/c/starlingx/config/+/865327
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) after platform upgrades `system upgrade-complete` 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. For explaining the platform upgrades see Upgrade consideration.
The auto update will be triggered only when the app is in applied state.
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
In case of patching a live system, after the patch is applied, when a new version of an app is delivered via the patch and the new version has this mechanism enabled, it will get automatically updated(up-versioned) to the new version. In case of patching a live system, after the patch is applied, when a new version of an app is delivered via the patch and the new version does not have this mechanism enabled, it will not get automatically updated(up-versioned) to the new version.
In case of patching a live system, after the patch is removed, when an old version of an app is delivered via the patch removal and the old version has this mechanism enabled, it will get automatically updated(down-versioned) to the old version. In case of patching a live system, after the patch is removed, when an old version of an app is delivered via the patch removal and the old version does not have this mechanism enabled, it will not get automatically updated(down-versioned) to the old version.
auto_update flag / update procedure | N->N+1(up-version) | N+1->N(down-version) |
---|---|---|
enabled on N version | not affected | automatic down-version |
enabled on N+1 version | automatic up-version | not affected |
disabled on N version | not affected | needs manual intervention to update to older(N) version |
disabled on N+1 version | needs manual intervention to update to newer(N+1) version | not affected |
This was introduced in stx.6.0 by https://review.opendev.org/c/starlingx/config/+/800821
behavior/platform_managed_app
There is a mechanism to tell the Framework the app should be managed by the Framework. We call this a platform managed app. The advantages of a platform managed app are:
- the Framework can perform some automated tasks such as auto reapply of the app based on specific triggers.
- the Framework can achieve a desired state after unlocking the first controller.
The functionalities are described later in their specific sections.
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
behavior: platform_managed_app: yes
This was introduced in stx.5.0 by https://review.opendev.org/c/starlingx/config/+/773451
behavior/desired_state
In case an app is declared a platform managed app the desired state to be achieve by the Framework can controlled using a variable called desired_state. Only uploaded and applied states are supported now.
Currently the Framework can achieve uploaded state by setting this metadata:
behavior: platform_managed_app: yes desired_state: uploaded
Currently the Framework can achieve applied state by setting this metadata:
behavior: platform_managed_app: yes desired_state: applied
This was introduced in stx.5.0 by https://review.opendev.org/c/starlingx/config/+/773451
behavior/evaluate_reapply
In case an app is declared a platform managed app doing automatic app re-applies by the Framework, based on specific conditions, can be controlled using a variable called evaluate_reapply. The Framework will determine(evaluate) if there is a change that require an app apply.
This was introduced in stx.5.0 by https://review.opendev.org/c/starlingx/config/+/773451
evaluate_reapply/after
We can control the order in which the Framework evaluates/re-applies the apps using a list variable called after. This will ensure current app will only be re-evaluated/re-applied after the apps listed there. For example current app will be re-evaluated/re-applied after another-app1 and another-app2
behavior: platform_managed_app: yes evaluate_reapply: after: - another-app1 - another-app2
A concrete example based on [1]: oidc-auth-apps will be always be evaluated after platform-integ-apps, such that if there is a change that requires platform-integ-apps to be applied, then platform-integ-apps will be applied before oidc-auth-apps.
evaluate_reapply/triggers
We can control what triggers the Framework to evaluate the re-apply for apps using a list variable called triggers. An app can be instructed to subscribe to some events by creating the necessary configuration in metadata.yaml for it.
behavior: platform_managed_app: yes evaluate_reapply: triggers: - trigger1 - trigger2
The definition is explained in [1]. A snapshot of trigger types can be found at [2].
Triggers are created and passed to evaluate_apps_reapply function inside conductor [3]. A real life example of such call is
self.evaluate_apps_reapply(context, trigger={'type': constants.APP_EVALUATE_REAPPLY_HOST_AVAILABILITY, 'availability': availability})
The most basic trigger is
evaluate_apps_reapply(context, trigger={'type': 'some-type'})
which can be subscribed to by this metadata:
behavior: platform_managed_app: yes evaluate_reapply: triggers: - type: some-type
A list of filters can be applied to a trigger (all key:value pairs must match)
evaluate_apps_reapply(context, trigger={'type': 'some-type', 'key1': 'value1', 'key2': 'value2'})
which can be subscribed to by this metadata:
behavior: platform_managed_app: yes evaluate_reapply: triggers: - type: some-type filter: - key1: value1 - key2: value2
A list of filters can be applied to a trigger (all key:value pairs must match) on a subdictionary
evaluate_apps_reapply(context, trigger={'type': 'some-type', 'subdict1': {'key1': 'value1', 'key2': 'value2'}})
which can be subscribed to by this metadata:
behavior: platform_managed_app: yes evaluate_reapply: triggers: - type: some-type filter_field: subdict1 filter: - key1: value1 - key2: value2
[1]: https://opendev.org/starlingx/config/src/commit/6e832b47070ec980d3e31d564862beeb5dd0432d/sysinv/sysinv/sysinv/sysinv/common/utils.py#L2248
[2]: https://opendev.org/starlingx/config/src/commit/6e832b47070ec980d3e31d564862beeb5dd0432d/sysinv/sysinv/sysinv/sysinv/common/constants.py#L1922
[3]: https://opendev.org/starlingx/config/src/commit/e948a02f29fbd377c4663a91dbe33a688ff3f3c0/sysinv/sysinv/sysinv/sysinv/conductor/manager.py#L14019
This was introduced in stx.5.0 by https://review.opendev.org/c/starlingx/config/+/773451
app_lifecycle_actions
TBD Purpose, location, example from an app
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.
Upgrade considerations
To update your app during platform upgrades currently an App Developer has to add the app in this list [1]. What will happen is one of the 2 things:
- If the app is in uploaded state an 'system application-delete' will happen for the N version, followed by an 'system application-upload' for N+1 version.
- If the app is in applied state an 'system application-delete' will happen for the N version, followed by an 'system application-update' to N+1 version.
In case the app is not added to [1], after the platform upgrade completes (system upgrade-complete was executed), the app may still be auto updated if metadata for such operation was added: upgrades/auto_update
Related work
We continue with a wiki targeting people involved in App Framework area. This next page is not currently designed to be facing App Developers themselves, and probably never will: App Framework page