Jump to: navigation, search

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

(Created page with "WIP")
 
Line 1: Line 1:
−
WIP
+
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
 +
 
 +
== Configuration ==
 +
Referencing the general directory structure, 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)

Revision as of 12:07, 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

Configuration

Referencing the general directory structure, 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)
Retrieved from "https://wiki.openstack.org/w/index.php?title=StarlingX/Containers/Applications/AppIntegration&oldid=182634"